Skip to main content
Glama
jalipata-mcp-memory

jalipata-mcp-memory

jalipata-mcp-memory

npm version

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).

Related MCP server: Mnemosyne

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

Available Tools

10 tools
add_observationsAdd ObservationsA

Add new observations (atomic facts) to existing entities in the knowledge graph. Fails if an entity does not exist.

Inputs: observations (required), namespace. Returns: results, namespace

create_entitiesCreate EntitiesA

Create multiple new entities in the knowledge graph. Entities with an existing name are ignored.

Inputs: entities (required), namespace. Returns: entities, namespace

create_relationsCreate RelationsA

Create multiple new relations between entities. Relations should be in active voice. Missing endpoint entities are created automatically.

Inputs: relations (required), namespace. Returns: namespace, relations

delete_entitiesDelete EntitiesA
DestructiveIdempotent

Delete entities and their associated relations and observations from the knowledge graph (cascading). Silent if an entity does not exist.

Inputs: entityNames (required), namespace. Returns: message, success

delete_observationsDelete ObservationsA
DestructiveIdempotent

Delete specific observations from entities in the knowledge graph. Silent if an observation does not exist.

Inputs: deletions (required), namespace. Returns: message, success

delete_relationsDelete RelationsA
DestructiveIdempotent

Delete specific relations from the knowledge graph. Silent if a relation does not exist.

Inputs: relations (required), namespace. Returns: message, success

list_namespacesList NamespacesA
Read-onlyIdempotent

List all memory namespaces (scopes) stored in this server.

Inputs: no named parameters. Returns: namespaces

open_nodesOpen NodesA
Read-onlyIdempotent

Retrieve specific nodes by name, along with relations connected to them. Silently skips non-existent nodes.

Inputs: names (required), namespace. Returns: entities, namespace, relations

read_graphRead GraphA
Read-onlyIdempotent

Read the entire knowledge graph for a namespace, including all entities and relations.

Inputs: namespace. Returns: entities, namespace, relations

search_nodesSearch NodesA
Read-onlyIdempotent

Keyword search for nodes in the knowledge graph by entity names, entity types, and observation content. Returns matching entities and their connected relations.

Inputs: query (required), namespace. Returns: entities, namespace, relations

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool targets a distinct operation: creating entities, creating relations, adding observations, and deleting each of those, plus distinct retrieval methods (read graph, search, open by name) and namespace listing. No two tools have overlapping purposes.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (create_entities, delete_relations, open_nodes, etc.). The only slight variation is 'add_observations' versus 'create_*', but 'add' is still a clear active verb in the same style.

    Tool Count5/5

    With 10 tools, the server is well-scoped for a knowledge graph memory system. Each tool covers a essential operation without redundancy, and the count is within the ideal range for a focused server.

    Completeness4/5

    The surface covers the full CRUD lifecycle for entities, relations, and observations, plus retrieval and namespace listing. Minor gaps exist such as no update/rename operation for entities or relations, but these are not critical for typical memory graph workflows.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides AI agents with persistent knowledge storage, enabling them to store, search, and retrieve text, documents, and files using semantic and keyword search via MCP tools.
      34
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Provides persistent, graph-based memory for AI agents via MCP, enabling semantic search, wikilink traversal, reminders, and injection protection.
      9
      34
      Apache 2.0
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI coding agents and IDEs to capture conversations, extract structured knowledge into a queryable graph database, and recall past decisions, patterns, files, and errors across all projects and workspaces. Provides persistent memory tools for saving, searching, and cleaning up knowledge via MCP.
      2
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides a self-hosted shared memory service that lets AI agents capture and recall durable facts, decisions, and context across multiple tools and MCP-capable clients.
      3
      MIT