# jalipata-mcp-memory

[![npm version](https://img.shields.io/npm/v/@jalipata/mcp-memory.svg)](https://www.npmjs.com/package/@jalipata/mcp-memory)

Persistent **long-term memory** for AI tools, over [MCP](https://modelcontextprotocol.io). 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:

```bash
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:

```bash
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):**

```bash
npx -y @jalipata/mcp-memory
```

**HTTP (remote):**

```bash
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:

```bash
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:

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

**OpenCode** (`opencode.json`):

```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:

```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:

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

**Remote HTTP:**

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

## How memory works

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

```json
{ "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

```bash
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