jalipata-mcp-memory

Persistent long-term memory for AI tools, over MCP. Give Claude Code, OpenCode, Cursor, Antigravity, Codex — or any MCP-capable client — a shared knowledge graph it can read and write across sessions. Like Claude's memory, but tool-agnostic.

Features

• Knowledge graph memory — entities, atomic observations, and directed relations (compatible with @modelcontextprotocol/server-memory).
• Model-driven — the model recalls and saves via MCP tools, guided by an injected prompt. No host-specific integration required.
• Multi-tenant — memory is scoped by namespace (user:alice, user:alice:project:frontend), so users, projects, and agents never mix.
• SQLite storage — transactional, WAL mode, zero-setup, single portable file.
• Keyword search — SQLite FTS5 with a substring fallback; no external services.
• Live updates — mutation tools notify subscribed clients via MCP resources.
• Two transports — stdio (default, local) and Streamable HTTP (remote).

Quick start

Wire memory into Claude Code, OpenCode, Cursor, Antigravity, or Codex with one interactive command:

npx -y @jalipata/mcp-memory init

The wizard asks which tools, where to set it up, the database path, and a memory namespace — then writes the MCP config, injects usage guidance, and optionally installs an auto-inject hook/plugin. Restart your AI tool and start chatting.

Run it outside a project (e.g. from $HOME)? It detects that and defaults to a user/global setup instead of cluttering your home directory. Re-running is safe — existing files are merged, never overwritten.

Generated configs pin a specific version (@jalipata/mcp-memory@<version>). After publishing a new release, bump the pinned version in all existing configs with one command:

npx -y @jalipata/mcp-memory update

It scans every configured tool (project + user scope) and rewrites only the pinned version — no interactive prompts.

What the wizard writes

Config and guidance cells show the project path / user-global path. The auto-inject column shows the project path — user scope mirrors it under your home directory.

| Tool | Config file | Guidance file | Auto-inject | | --- | --- | --- | --- | | Claude Code | .mcp.json / ~/.claude.json | CLAUDE.md / ~/.claude/CLAUDE.md | .claude/settings.json — SessionStart hook, disables auto memory | | OpenCode | opencode.json / ~/.config/opencode/opencode.json | AGENTS.md / ~/.config/opencode/AGENTS.md | .opencode/plugins/memory-guidance.ts — system.transform plugin | | Cursor | .cursor/mcp.json / ~/.cursor/mcp.json | .cursor/rules/memory.mdc / ~/.cursor/rules/memory.mdc | none — rules auto-applied (alwaysApply) | | Antigravity | .agents/mcp_config.json / ~/.gemini/config/mcp_config.json | AGENTS.md / ~/.gemini/GEMINI.md | .agents/hooks.json — PreInvocation hook | | Codex | .codex/config.toml / ~/.codex/config.toml | AGENTS.md / ~/.codex/AGENTS.md | .codex/hooks.json — SessionStart hook |

For Claude Code, the injected guidance makes the model treat the memory MCP server as its primary long-term memory, instead of Claude's built-in memory.

Auto-inject memory guidance (hooks / plugin)

File guidance (CLAUDE.md / AGENTS.md / GEMINI.md) is advisory — the model reads it but is free to ignore it. The wizard can go one step further and make the memory guidance automatically injected on every session, so you never have to tell the model to use mcp-memory again:

• Claude Code — SessionStart hook returning additionalContext (system reminder before the first prompt); disables Claude's built-in auto memory.
• OpenCode — plugin tapping experimental.chat.system.transform (guidance appended to the system prompt before every LLM request).
• Antigravity — PreInvocation hook emitting injectSteps[].ephemeralMessage before every model call.
• Codex — SessionStart hook returning additionalContext (same contract as Claude) with matcher: startup|resume.

Pick project, user/global, or both when prompted; existing settings and hooks are merged, never overwritten.

Adding a new AI tool

Integrations are adapters, not scattered patches. The wizard (init.ts) is a single generic loop that only talks to the ToolAdapter contract (src/cli/adapters/types.ts); it contains zero per-tool logic. Adding a tool means two steps:

1. Create src/cli/adapters/<tool>.ts — a ToolAdapter implementing:
   • hasExistingConfig — pre-select the tool when its config already declares the memory server
   • targets(scope, ctx) — resolve config + guidance file paths for project/user/both
   • autoInject? — an AutoInjectMechanism, or undefined for rules-only tools
2. Register it — one line in src/cli/adapters/registry.ts (TOOL_ADAPTERS).

Reusable building blocks:

• Config formats — CONFIG_FORMATS (mcpServers / servers / mcp / mcpServersToml) in src/cli/config.ts. Most tools reuse mcpServers; Codex's TOML [mcp_servers.*] shape uses mcpServersToml (serialized by the built-in src/cli/toml.ts parser). A genuinely new shape needs only a new format entry.
• Plugin mechanisms — createFilePluginMechanism (adapters/pluginMechanism.ts) covers any tool that auto-injects guidance by writing a plugin file (OpenCode uses it; a future Cursor extension would too). Supply file paths + a content renderer, get install/uninstall/isInstalled for free.
• Hook mechanisms — adapters/hookMechanism.ts provides createSessionStartHookMechanism for any client whose session-start hook returns additionalContext (Claude Code, Codex — matcher/handler-fields/extra-settings per spec) and createPreInvocationHookMechanism for Antigravity's injectSteps.
• Guidance variants — buildGuidanceBlock(scope, variant) wording is per-target (claude vs generic); rule-file formats get YAML frontmatter (e.g. Cursor .mdc alwaysApply: true).

Cursor ships as a reference adapter: it reuses the mcpServers format and .cursor/rules/memory.mdc with alwaysApply: true, so it needs no auto-inject mechanism at all.

Running the server

The server is a normal MCP process. stdio is the default transport — most clients spawn it themselves from your MCP config, so you rarely run it directly. HTTP is for remote setups.

stdio (default):

npx -y @jalipata/mcp-memory

HTTP (remote):

MEMORY_TRANSPORT=http MEMORY_HTTP_PORT=3000 npx -y @jalipata/mcp-memory

Web dashboard

Visualize and inspect your memories in the browser — a read-only graph view with entity details, observations, relations, and search:

npx -y @jalipata/mcp-memory serve

Then open http://127.0.0.1:4824 (default). Pick a namespace from the dropdown, click nodes to inspect them, and search across names/types/observations.

Environment

| Env var | Description | Default | | ------------------ | ------------------------------------ | ----------------------- | | MEMORY_DB_PATH | SQLite database file | ~/.jalipata/memory.db | | MEMORY_TRANSPORT | stdio or http | stdio | | MEMORY_HTTP_PORT | Port when transport is http | 3000 | | MEMORY_WEB_HOST | Host the web dashboard binds to | 127.0.0.1 | | MEMORY_WEB_PORT | Port the web dashboard listens on | 4824 |

Memory is centralized in one database (~/.jalipata/memory.db by default). Projects stay isolated through namespaces, not separate files. Set an absolute MEMORY_DB_PATH in client configs if you move it — the default is resolved from your home directory.

Manual MCP client setup

Skipped the wizard? Add the server to your client's MCP config. On Windows, prefix npx with cmd /c.

Most clients (Claude Code .mcp.json, Claude Desktop claude_desktop_config.json, Cursor .cursor/mcp.json, Antigravity .agents/mcp_config.json) — mcpServers format:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@jalipata/mcp-memory"],
      "env": { "MEMORY_DB_PATH": "/absolute/path/to/memory.db" }
    }
  }
}

OpenCode (opencode.json):

{
  "mcp": {
    "memory": {
      "type": "local",
      "command": ["npx", "-y", "@jalipata/mcp-memory"],
      "enabled": true,
      "environment": { "MEMORY_DB_PATH": "/absolute/path/to/memory.db" }
    }
  }
}

Codex (.codex/config.toml or ~/.codex/config.toml) — TOML:

[mcp_servers.memory]
command = "npx"
args = ["-y", "@jalipata/mcp-memory"]
env = { MEMORY_DB_PATH = "/absolute/path/to/memory.db" }

VS Code / Copilot (.vscode/mcp.json) — uses the servers key:

{
  "servers": {
    "memory": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@jalipata/mcp-memory"],
      "env": { "MEMORY_DB_PATH": "/absolute/path/to/memory.db" }
    }
  }
}

Remote HTTP:

{
  "mcpServers": {
    "memory": { "url": "http://localhost:3000/mcp" }
  }
}

How memory works

Memories form a knowledge graph of entities, atomic observations, and directed relations:

{ "name": "Alfian", "entityType": "person", "observations": ["Prefers TypeScript"] }
{ "from": "Alfian", "to": "jalipata", "relationType": "works_on" }

The guidance injected into CLAUDE.md / AGENTS.md / GEMINI.md (or the bundled memory-guidance prompt) tells the model to:

1. Recall relevant context at the start of a conversation with search_nodes / open_nodes.
2. Save durable facts with create_entities, create_relations, and add_observations.
3. Stay clean — atomic observations, reuse existing entities, delete stale memory — always under a consistent namespace.

MCP tools

All tools accept an optional namespace argument (defaults to default).

| Tool | Description | | --------------------- | ----------------------------------------------------------------- | | create_entities | Create entities; duplicates by name are ignored | | create_relations | Create directed relations; missing endpoints are auto-created | | add_observations | Append atomic facts to entities (fails if entity is missing) | | delete_entities | Delete entities — cascades to relations & observations | | delete_observations | Delete specific observations | | delete_relations | Delete specific relations | | read_graph | Read the full knowledge graph for a namespace | | search_nodes | Keyword search over names, types, and observations (FTS5 + LIKE) | | open_nodes | Retrieve specific nodes plus their connected relations | | list_namespaces | List all memory namespaces |

MCP resources

• memory://namespaces — all known namespaces (JSON)
• memory://graph/{namespace} — full graph of a namespace (JSON), subscribable

Development

npm run typecheck   # tsc --noEmit
npm test            # vitest run (unit tests)
npm run dev         # tsx watch

Stack: Node.js ≥ 22 · TypeScript · @modelcontextprotocol/sdk · better-sqlite3 · SQLite FTS5 · zod · @clack/prompts

Project layout

src/
├── index.ts               # entry point: stdio + HTTP transports + `init`/`serve` dispatch
├── config.ts              # env configuration
├── prompts.ts             # LLM memory-guidance prompt
├── resources.ts           # MCP resources + subscribe notifications
├── db/
│   ├── schema.ts          # SQLite DDL + FTS5 triggers
│   ├── connection.ts      # better-sqlite3 bootstrap
│   └── knowledgeGraph.ts  # namespace-aware CRUD + search
├── cli/
│   ├── config.ts          # format registry (mcpServers/servers/mcp/mcpServersToml), merge/write engine, guidance
│   ├── toml.ts            # minimal TOML parser/serializer (Codex config.toml)
│   ├── init.ts            # interactive `init` wizard — one generic loop, no per-tool logic
│   ├── plan.ts            # pure planner: selection + scope → targets & mechanism installs
│   ├── hooks.ts           # Claude Code hook file layout + script renderer
│   └── adapters/          # pluggable AI-tool integrations
│       ├── types.ts           # ToolAdapter / AutoInjectMechanism / WizardContext contracts
│       ├── registry.ts        # static registry (TOOL_ADAPTERS) — the only wiring point
│       ├── pluginMechanism.ts # generic "write a plugin file" mechanism factory
│       ├── hookMechanism.ts   # generic SessionStart (additionalContext) + PreInvocation (injectSteps) hooks
│       ├── claudeCode.ts      # Claude Code adapter (SessionStart hook + auto memory disable)
│       ├── opencode.ts        # OpenCode adapter (system-transform plugin mechanism)
│       ├── cursor.ts          # Cursor adapter (rules-only, reuses mcpServers format)
│       ├── antigravity.ts     # Antigravity adapter (PreInvocation hook, mcp_config.json)
│       └── codex.ts           # Codex adapter (SessionStart hook, TOML config)
├── web/
│   ├── server.ts          # web dashboard HTTP server + read-only JSON API
│   └── static/            # frontend (index.html, styles.css, app.js)
└── tools/
    └── index.ts           # MCP tool registration (zod schemas)

License

MIT