OpenMemory

AI memory engine exposed as an MCP server. Structured knowledge with server-side intelligence - domain routing, entity extraction, deduplication, and supersession. Any AI tool can query it. You own the data.

The Problem

AI agents can store knowledge, but existing approaches limit how effectively it can be structured and retrieved. Built-in memories like ChatGPT and Claude store flat text with no schema or relationships — and are not portable across tools. Developer libraries offer memory primitives but require significant integration work. Knowledge graph engines provide rich entity extraction at the cost of multiple LLM calls per ingestion and operational overhead. Lightweight solutions achieve cross-tool sharing but without structure, confidence scoring, or deduplication.

The common gap: structured, schema-driven knowledge with effective retrieval, working across any AI tool, without significant infrastructure cost.

Related MCP server: HKC Memory Server

The Solution

One place that accumulates structured knowledge - validated, owned by you - and every AI tool can query it with granular permissions. Works for personal identity, team knowledge, project context, or any use case where AI needs persistent memory.

Quick Start

Add to your AI tool's MCP configuration:

{
  "mcpServers": {
    "openmemory": {
      "command": "npx",
      "args": ["-y", "@openmem/mcp@0.8.0"]
    }
  }
}

Works with Claude Code, Claude Desktop, Cursor, and any MCP-compatible tool. Data is stored at ~/.openmemory by default. To change this, add "env": { "OPENMEMORY_DATA": "/absolute/path" } to the config above.

Disable your client's built-in memory. OpenMemory replaces it — running both fragments your knowledge across two systems. In Claude Desktop: Settings → Memory → off. In ChatGPT: Settings → Personalisation → Memory → off. This ensures OpenMemory is the single source of truth.

How It Works

OpenMemory captures knowledge through two complementary paths:

1. Fast capture — During conversation, the AI calls capture_fact whenever it learns something useful. Facts are stored immediately in a session staging buffer.

2. Batch consolidation — Periodically, the server processes all pending facts as a batch: classifying domains, extracting entities (people, places, organisations), detecting duplicates and contradictions, and building a knowledge graph.

Optionally, the server can also scan raw conversation events during consolidation to extract facts the AI missed — a safety net that ensures important knowledge isn't lost.

The result is a structured, evolving knowledge graph that any AI tool can query via MCP.

Features

• Hybrid knowledge capture — AI explicitly captures facts during conversation. Optionally, the server can also extract facts from raw events during consolidation as a safety net.

• Batch consolidation — Periodic processing integrates pending captures into the long-term knowledge graph: classifies domains, extracts entities, resolves duplicates, detects contradictions.

• Entity graph — People, places, organisations automatically extracted and linked. Relationship strength tracks corroboration.

• Hybrid search — BM25 keyword + structured domain + entity-graph paths, merged via Reciprocal Rank Fusion with temporal decay.

• In-session memory — Recently captured facts are immediately accessible via get_session_context, even before consolidation.

• Immutable history — Facts are never deleted, only superseded. Full history preserved.

• Source traceability — Every fact links back to the conversation events that produced it.

• Manual consolidation — Call consolidate at natural breakpoints (topic change, task completion, pre-compaction). No reliance on session boundaries.

MCP Resources

Resources are context the client loads automatically — no tool call, no decision by the AI. Tools only help if the assistant remembers to reach for them; resources are simply present.

• memory://briefing — Everything worth knowing right now: profile, what was learned in the last consolidation, open threads, and recent knowledge. Markdown, kept to roughly a screenful.

• memory://profile — Core identity facts, most important first.

Both are read-only views over the same database the tools query, so they can't drift from it. They're regenerated on read, and clients that subscribe are notified when a consolidation changes what they'd say. Clients without resource support lose no capability — the read tools below cover the same ground on demand.

MCP Tools

Session

• log_event — Log conversation events (messages, artifacts).

• get_events — Retrieve events from current or previous session.

• get_session_context — Recall facts captured in the current session (in-session working memory).

Reading

• get_entity — Everything known about any named subject — person, organisation, project, place, product — and how it connects

• get_context — Everything relevant to a topic (search + entity traversal)

• search_knowledge — Hybrid search across graduated knowledge

Writing

• capture_fact — Store a fact. Fast append with session tagging. Full intelligence deferred to consolidation.

• consolidate — Integrate pending facts into long-term knowledge. Extracts entities, resolves duplicates, detects contradictions, builds the knowledge graph. Call at natural breakpoints or before context compaction.

Meta

• get_schemas — Available domains and structure

• get_stats — Fact count, entity count, domain distribution

Session Event Logging

OpenMemory captures every interaction as a SessionEvent — the DIKW Data layer. This is the episodic ground truth that consolidation, search, and recall all build on.

How events are captured

All events are captured via the log_event MCP tool or the openmemory log-event CLI command. The calling AI logs conversation messages; Claude Code hooks can automate this:

Claude Code Hooks

For Claude Code, hooks provide deterministic capture — they fire every time, regardless of whether the AI "remembers" the tool description.

Available hooks

Setup

Install the CLI for hooks:

npm install -g @openmem/mcp

Alternatively, replace openmemory with npx -y @openmem/mcp in the hook commands below (no install needed, but adds ~2-3s latency per hook).

Add to .claude/settings.json (project-level) or ~/.claude/settings.json (global):

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "openmemory log-event --role user --event-type message"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "openmemory log-event --role assistant --event-type message"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "^(?!mcp__openmemory__)",
        "hooks": [
          {
            "type": "command",
            "command": "openmemory log-event --role tool --event-type tool_result"
          }
        ]
      }
    ]
  }
}

The CLI reads the hook JSON payload from stdin and extracts the relevant content field (prompt for UserPromptSubmit, last_assistant_message for Stop, full JSON for PostToolUse). Events are appended to the most recently active session in the database.

The PostToolUse matcher excludes OpenMemory's own tools (^(?!mcp__openmemory__)) to avoid capturing internal operations.

CLI Reference

openmemory init [dir]

Optional — the server creates its data directory and database on first run anyway. Use init to set things up ahead of time and, more usefully, to write a config.json you can tune (without it, the defaults are invisible):

# Initialise the default location (~/.openmemory):
openmemory init

# Or a specific directory:
openmemory init ~/my-memory

# Options:
#   --data     Data directory (alternative to the positional argument)
#   --force    Overwrite an existing config.json with defaults

It creates the data directory, applies the database schema, writes config.json with the shipped defaults, and prints a ready-to-paste MCP config block. Re-running is safe: an existing config.json is left untouched unless you pass --force, and your data is preserved.

The generated config.json is where you change consolidation behaviour — most notably intelligence.provider, which selects how facts are extracted (cli by default, which runs the claude CLI; set it to heuristic for a zero-dependency regex fallback, or override at runtime with OPENMEMORY_PROVIDER=heuristic).

openmemory log-event

The openmemory log-event command inserts events directly into the database (no running server needed):

# From a hook (reads JSON payload from stdin):
echo '{"hook_event_name":"UserPromptSubmit","prompt":"hello"}' | openmemory log-event --role user

# With explicit content:
openmemory log-event --role user --event-type message --content "hello world"

# Options:
#   --role          user | assistant | system | tool (default: user)
#   --event-type    message | tool_call | tool_result | artifact (default: message)
#   --content-type  text | json | image | audio | binary (default: text)
#   --content       Event content (or pipe via stdin)
#   --session-id    Target session (default: most recent)
#   --data          Data directory (default: ~/.openmemory or $OPENMEMORY_DATA)

openmemory search <query>

Search the knowledge base from the command line. This runs the same hybrid search the search_knowledge tool runs, so it answers "what does it actually know about me?" — and "why did the AI say that?" — without wiring up a client:

openmemory search "coffee"

# Prioritise a domain:
openmemory search "coffee" --domain preferences

# Machine-readable output for scripting:
openmemory search "coffee" --json

# Options:
#   --domain   Prioritise a domain (profile, preferences, medical, people, work,
#              or any other in use). Biases ranking; does not filter — see below
#   --limit    Maximum results (default: 20)
#   --json     Emit the raw search payload instead of formatted text
#   --data     Data directory (default: ~/.openmemory or $OPENMEMORY_DATA)

Results carry a relevance score and confidence, plus coverage and confidence estimates for the result set as a whole — so a thin result set looks thin rather than silently passing as complete.

--domain biases ranking rather than filtering. Facts in the domain are surfaced and rank higher, and a fact that both matches your query and sits in that domain ranks top — but a strong match in another domain still appears below it. This is deliberate: domains are assigned by a classifier and are approximate, so a fact you are looking for may be filed under a near-synonym. A hard filter would hide it and show you an empty result, with no way to tell "nothing is known" from "it was filed elsewhere". Ranking degrades where a filter fails absolutely.

openmemory stats

Show what the knowledge base holds — fact counts, entities, domains, and how facts are distributed across domains:

openmemory stats
openmemory stats --json

# Options:
#   --json     Emit the raw statistics payload instead of formatted text
#   --data     Data directory (default: ~/.openmemory or $OPENMEMORY_DATA)

Facts are immutable — superseded facts are kept, never deleted — so the current count and the total legitimately differ once anything has been superseded. Both are reported.

Integration Patterns

OpenMemory's tool descriptions are the primary integration layer — they tell AI assistants when to capture facts and search knowledge, working with every MCP client out of the box. For deeper integration, clients can add rules-based hooks (instructions loaded into the AI's context) at key moments in the conversation lifecycle. These are optional but make capture and retrieval more reliable.

Without Configuration

The capture_fact tool description tells the AI to "call this proactively whenever you learn something useful." The search_knowledge description says "call this BEFORE answering questions that might benefit from personal context." These descriptions ship with the server and drive behaviour without any client setup.

Hook Points

On pre-compaction: This is the highest-value hook point — without it, knowledge is silently lost when the client compresses context. Calling consolidate before compaction processes all pending facts into long-term knowledge. If event extraction is enabled, the server also scans the raw conversation events to extract facts the AI missed.

Claude Code

Create .claude/rules/openmemory.md in your project (or ~/.claude/rules/openmemory.md globally). This loads automatically into context:

# OpenMemory

- At the start of each conversation, call `get_profile` to load identity context
- Before answering questions about preferences, people, or history, call `search_knowledge`
- When the user mentions preferences, personal details, relationships, or decisions, call `capture_fact`
- When the conversation is getting long, call `consolidate` to process pending facts before they are lost to compaction
- At natural breakpoints (topic change, task completion), call `consolidate` to keep the knowledge graph current

To allow OpenMemory tools without per-call approval prompts, add to the permissions.allow array in .claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__openmemory__*"
    ]
  }
}

Cursor / Windsurf

Add to .cursorrules (Cursor) or .windsurfrules (Windsurf) in your project root:

When the openmemory MCP server is available:
- At conversation start, call get_profile to load user context
- Before answering questions about preferences or history, call search_knowledge
- When the user shares preferences, facts, or decisions, call capture_fact
- When context is getting long, call consolidate to process pending facts before they are lost

Claude Desktop / Other MCP Clients

No configuration needed. Tool descriptions handle integration automatically — the AI assistant reads the tool descriptions and knows when to capture and search.

Development

git clone https://github.com/gordonkjlee/openmemory
cd openmemory
npm install
npm run build
npm test

License

MIT