Show HN: MCP Memory – Fast Agent Memory Using Google's OKF and SQLite FTS5

MCP-Memory is simply a Model Context Protocol (MCP) server that equips AI agents (such arsenic Claude Desktop, Cursor, Antigravity, Windsurf, aliases Codex) pinch persistent, semipermanent representation capabilities.

Memory records are formatted utilizing the Open Knowledge Format (OKF v0.2) modular and indexed pinch a section SQLite lawsuit (supporting FTS5 full-text search) for accelerated key-value lookups, tag filtering, and contented search.

Fast Track: Jump straight to Quick Start

• Persistent State Across Sessions: Enables AI agents to read, store, search, and delete stateful representation snippets that persist crossed chat turns and sessions.
• OKF Standard Compliance: Stores each representation point formatted arsenic an OKF v0.2 Markdown archive pinch YAML frontmatter (type, key, namespace, tags, generated, sources, verified, status, stale_after), adhering strictly to SPEC.md and OKF_RULES.md.
• Dual-Layer Architecture:
  • Human-Browseable OKF Directory: Automatically dumps and syncs each representation to disk arsenic a earthy .md record wrong the memory/ bundle directory pinch hierarchical index.md progressive disclosure files (root index.md versioned pinch okf_version: "0.2") and log.md update history tracking.
  • High-Performance SQLite Indexing: SQLite FTS5 (Full-Text Search) and automatic triggers for sub-20ms cardinal lookups and instant keyword searches.
• Namespace Isolation: Supports contextual separation (e.g. user/preferences, project/architecture, default).
• Zero Boilerplate Setup: Quick setup wizard (python3 setup.py) auto-configures installed MCP devices (Antigravity, Claude, Cursor, Windsurf, Codex).

The server exposes 4 superior MCP devices to interacting agents:

Stores aliases updates a representation grounds successful OKF v0.2 format.

• Parameters:
  • key (string, required): Unique identifier aliases way for the representation (e.g. user/preferences/coding_style aliases project/architecture).
  • content (string aliases object, required): Core accusation to store.
  • project_root (string, required): Absolute way to the progressive task guidelines directory (e.g. /Users/user/Projects/my-app).
  • tags (array of strings, optional): Classification tags for filtering.
  • namespace (string, optional, default: "default"): Scope/namespace.
  • concept_type (string, optional, default: "Agent Memory"): OKF conception type (e.g. Metric, Playbook, Attested Computation).
  • title (string, optional): Display name.
  • description (string, optional): One-line summary.
  • resource (string, optional): Canonical URI of underlying asset.
  • status (string, optional, default: "stable"): Lifecycle authorities (draft | unchangeable | deprecated).
  • stale_after (string, optional): ISO day (YYYY-MM-DD).
  • sources (array of objects, optional): Provenance sources [{resource, id, title, author, usage_count, last_modified}].
  • verified (array of objects aliases object, optional): Verification events [{by, at}].
  • generated_by (string, optional): Actor identifier pursuing character normal (<producer>/<version>, human:<id>, process:<id>).

Retrieves a circumstantial representation by its cardinal and namespace.

• Parameters:
  • key (string, required): The representation cardinal to look up.
  • project_root (string, required): Absolute way to the progressive task guidelines directory.
  • namespace (string, optional, default: "default"): Scope/namespace.

Finds memories matching keywords, tags, aliases namespace filters.

• Parameters:
  • project_root (string, required): Absolute way to the progressive task guidelines directory.
  • query (string, optional): Keyword hunt query crossed keys, frontmatter, and content.
  • tags (array of strings, optional): Filter by circumstantial tags.
  • namespace (string, optional): Scope hunt to a namespace.
  • limit (integer, optional, default: 10): Maximum number of results.

AGENT DIRECTIVE (Session Start): Retrieves the past recorded convention checkpoint (system/last_memory) truthful the AI supplier instantly knows wherever activity was near disconnected erstwhile opening a task aliases starting a session.

• Parameters:
  • project_root (string, required): Absolute way to progressive task guidelines directory.
  • namespace (string, optional, default: "default"): Scope/namespace.

AGENT DIRECTIVE (Milestones & Progress): Updates the canonical convention checkpoint (system/last_memory) whenever completing a milestone, making cardinal changes, aliases pausing work.

• Parameters:
  • content (string aliases object, required): Brief statement aliases system dictionary summarizing advancement and referencing cardinal representation files.
  • project_root (string, required): Absolute way to progressive task guidelines directory.
  • namespace (string, optional, default: "default"): Scope/namespace.
  • summary (string, optional): One-sentence explanation of the milestone achieved.

Every stored representation strictly adheres to the OKF v0.2 specification (SPEC.md & OKF_RULES.md):

Run setup.py to auto-detect and registry mcp-memory pinch your AI tools:

Note: Once setup.py finishes configuring your tools, your AI customer will motorboat mcp-memory automatically successful the inheritance whenever needed. You do not request to manually commencement aliases support a server process moving successful your terminal.

If you want to manually verify startup, inspect stdio output, aliases pre-initialize the virtual situation (.venv), you tin tally run.sh directly:

If you for illustration to configure your MCP customer manually, adhd the "memory" server introduction pointing to run.sh:

Add to your client's mcp_config.json aliases claude_desktop_config.json:

Add to ~/.codex/config.toml:

• Claude Code CLI:
  claude mcp adhd --scope personification representation -- /ABSOLUTE/PATH/TO/run.sh
• Codex CLI:
  codex mcp adhd representation -- /ABSOLUTE/PATH/TO/run.sh

Run the automated trial suite to verify OKF serialization, SQLite database operations, and FastMCP instrumentality execution:

By default, mcp-memory creates project-isolated representation stores wrong each project's guidelines directory:

• OKF Markdown Files (Human-readable): memory/ files successful task root.
• SQLite Database (Hidden index): .mcp_memory/memories.db successful task root.

You tin customize this behaviour utilizing situation variables:

• MCP_MEMORY_PROJECT_ROOT: Project guidelines directory (default: process existent moving directory cwd).
• MCP_MEMORY_DB_PATH: SQLite database record way (default: .mcp_memory/memories.db comparative to task root).
• MCP_MEMORY_DIR: Directory for Open Knowledge Format (OKF) .md files (default: representation comparative to task root).

Tip: If you for illustration a azygous world representation shop shared crossed each projects, group MCP_MEMORY_DB_PATH=~/.mcp_memory/memories.db and MCP_MEMORY_DIR=~/.mcp_memory/memory successful your client's MCP configuration.