jalipata-mcp-memory

Persistent long-term memory for AI tools, over MCP. Give Claude Code, OpenCode, 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 and/or OpenCode 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 and injects usage guidance into CLAUDE.md / AGENTS.md. 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.

What the wizard writes

Scope	Claude Code	OpenCode
Project	.mcp.json + CLAUDE.md	opencode.json + AGENTS.md
User / global	~/.claude.json + ~/.claude/CLAUDE.md	~/.config/opencode/opencode.json + ~/.config/opencode/AGENTS.md

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.

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. Pick a namespace from the dropdown, click nodes to inspect them, and search across names/types/observations.

Env var	Description	Default
MEMORY_WEB_HOST	Host the dashboard binds to	127.0.0.1
MEMORY_WEB_PORT	Port the dashboard listens on	4824

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_SERVER_NAME	Server name advertised over MCP	jalipata-memory

The web dashboard adds MEMORY_WEB_HOST (127.0.0.1) and MEMORY_WEB_PORT (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) — 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" }
    }
  }
}

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 (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          # setup wizard logic (tool targets, scopes, merge)
│   └── init.ts            # interactive `init` wizard
├── 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