Open Brain Knowledge MCP Server

A persistent, cross-session knowledge base for AI agents. Built on the Model Context Protocol (MCP), this server gives AI coding assistants like Claude Code long-term memory — they can recall what happened in previous sessions, store permanent knowledge, and search across their entire history.

The problem: AI agents start from zero every session. They forget what you worked on, what decisions were made, and what errors were resolved.

The solution: Open Brain indexes every session into a searchable SQLite database with full-text search (FTS5). Agents can query it with kb_recall to find anything from any previous session — errors, decisions, code patterns, stored facts — instantly.

Why Not Just Use Claude Code's Built-in Memory?

Claude Code has a file-based memory system (~/.claude/projects/<project>/memory/) — but it's just markdown files loaded into context at session start. It's manual, not searchable, and not connected to session history.

Open Brain Knowledge is fundamentally different — it's an automated, searchable, indexed knowledge base that captures everything across every session and makes it queryable.

| Capability | Claude Code Built-in | Open Brain Knowledge | |---|---|---| | Cross-session recall | No — each session starts from zero | Yes — kb_recall searches all past sessions | | Full-text search over history | No | Yes — FTS5 with ranked results | | Persistent knowledge storage | No | Yes — kb_store / kb_forget | | Project-scoped vs global memory | No | Yes — scoped by default, global on demand | | Session indexing | No | Yes — automatic via SessionEnd hook | | Session summarization | No | Yes — kb_summarize + kb_store_summary | | Auto-tagging | No | Yes — tech keywords, error types, file extensions | | TTL-based pruning | No | Yes — 90-day default | | Searchable by category/tags/time | No | Yes — filter by error, project, timeframe |

Claude Code's memory is like sticky notes. Open Brain Knowledge is a searchable database with full-text indexing.

Project Scoping vs Global Memory

When you're working on multiple projects, you don't want session history from Project A polluting searches in Project B. But you do want general knowledge (preferences, processes, learned facts) available everywhere.

Open Brain Knowledge solves this with scoped-by-default, global-on-demand architecture:

How scoping works

| Data Type | Default Behavior | Override | |---|---|---| | Session chunks & summaries | Scoped to project when project is passed | global: true searches all projects | | Stored knowledge | Global by default (available everywhere) | scope: "project" restricts to one project |

Examples

# Search only the current project's history (recommended default)
kb_recall({ queries: ["auth bug"], project: "/path/to/myapp" })

# Search everything across all projects
kb_recall({ queries: ["auth bug"], global: true })

# Store a fact available everywhere
kb_store({ content: "Deploy process: ...", key: "deploy-process" })

# Store a fact only relevant to one project
kb_store({
  content: "Uses Clerk for auth with custom middleware",
  key: "auth-setup",
  scope: "project",
  project_dir: "/path/to/myapp"
})

# List knowledge for current project (global + project-scoped)
kb_list({ project: "/path/to/myapp" })

Design principles

• Session data is project-scoped by default — agents should always pass their working directory as project when calling kb_recall
• Stored knowledge is global by default — facts, preferences, and decisions are typically useful across projects
• Global knowledge always surfaces — even in project-scoped searches, knowledge with no project_dir is included
• Single database — no schema splits or sync headaches; scoping is done via filtering

How It Works

┌─────────────────┐     ┌──────────────────┐     ┌───────────────────┐
│  Claude Code     │────▶│  context-mode     │────▶│  Session .db      │
│  (AI Agent)      │     │  (MCP plugin)     │     │  files            │
└─────────────────┘     └──────────────────┘     └────────┬──────────┘
        │                                                  │
        │  kb_recall / kb_store                           │ SessionEnd hook
        │                                                  │ (auto-index.mjs)
        ▼                                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    Open Brain Knowledge MCP                         │
│                                                                     │
│  ┌─────────────┐  ┌──────────┐  ┌────────────┐  ┌──────────────┐  │
│  │  sessions    │  │  chunks   │  │  knowledge  │  │  summaries   │  │
│  │  (metadata)  │  │  (FTS5)  │  │  (FTS5)     │  │  (FTS5)      │  │
│  └─────────────┘  └──────────┘  └────────────┘  └──────────────┘  │
│                                                                     │
│                    ~/.claude/context-mode/knowledge.db               │
└─────────────────────────────────────────────────────────────────────┘

1. context-mode (dependency MCP plugin) captures session events as .db files during each Claude Code session
2. When a session ends, the SessionEnd hook (auto-index.mjs) automatically indexes new events into the knowledge base
3. Events are chunked (max 2000 chars), categorized, and auto-tagged with tech keywords, error types, and file extensions
4. All content is indexed with SQLite FTS5 (porter stemming + unicode61 tokenizer) for fast, ranked full-text search
5. Agents query the knowledge base via MCP tools (kb_recall, kb_store, etc.)

Dependencies

Required: context-mode MCP Plugin

Open Brain Knowledge depends on context-mode to capture session data. context-mode records everything that happens during a Claude Code session (prompts, tool results, file changes, errors, commands) into per-session SQLite .db files.

Install context-mode:

npm install -g @anthropic/context-mode
# or follow the context-mode repo's installation instructions

context-mode must be registered as a Claude Code plugin. After installation, verify it appears in your Claude Code settings:

// ~/.claude/settings.json
{
  "enabledPlugins": {
    "context-mode@context-mode": true
  }
}

Runtime Dependencies

| Package | Version | Purpose | |---|---|---| | @modelcontextprotocol/sdk | ^1.26.0 | MCP server framework (StdioServerTransport) | | better-sqlite3 | ^12.6.2 | SQLite database driver with FTS5 support | | zod | ^3.25.0 | Schema validation for tool parameters |

Dev Dependencies

| Package | Version | Purpose | |---|---|---| | typescript | ^5.7.0 | TypeScript compiler | | tsx | ^4.21.0 | TypeScript execution for development | | @types/better-sqlite3 | ^7.6.13 | Type definitions | | @types/node | ^22.19.11 | Node.js type definitions |

Installation

The recommended install location is ~/.claude/knowledge-mcp/ — right alongside the ~/.claude/context-mode/ directory. Both are Claude Code infrastructure and belong together.

~/.claude/
├── context-mode/        # Session capture (dependency)
│   ├── sessions/        # Per-session .db files
│   └── knowledge.db     # The knowledge base (created by this server)
├── knowledge-mcp/       # ← This server lives here
│   ├── src/
│   ├── build/
│   ├── scripts/
│   └── package.json
├── settings.json
└── projects/

1. Clone and build

cd ~/.claude
git clone https://github.com/YOUR_USERNAME/open-brain-knowledge.git knowledge-mcp
cd knowledge-mcp
npm install
npm run build

2. Register as an MCP server in Claude Code

Add the server via the Claude Code CLI:

claude mcp add open-brain-knowledge -- node ~/.claude/knowledge-mcp/build/server.js

Or manually add it to your Claude Code settings file (~/.claude/settings.json):

{
  "mcpServers": {
    "open-brain-knowledge": {
      "command": "node",
      "args": ["~/.claude/knowledge-mcp/build/server.js"]
    }
  }
}

3. Set up the SessionEnd auto-index hook

The SessionEnd hook automatically indexes new session data when a Claude Code session ends. Add it to your Claude Code settings:

// ~/.claude/settings.json
{
  "hooks": {
    "SessionEnd": [
      {
        "type": "command",
        "command": "node ~/.claude/knowledge-mcp/scripts/auto-index.mjs"
      }
    ]
  }
}

4. Verify installation

Start a new Claude Code session and ask the agent to run kb_stats. You should see output showing the knowledge base tables are initialized.

MCP Tools Reference

Open Brain Knowledge exposes 10 tools via MCP:

Search & Recall

kb_recall

Search across all indexed sessions, stored knowledge, and session summaries. This is the primary tool agents use to remember things. By default, results are scoped to the project you specify — always pass your current working directory as project for best results.

| Parameter | Type | Required | Description | |---|---|---|---| | queries | string[] | Yes | Search queries — batch multiple questions in one call | | sessions | number | No | Limit to last N sessions | | since | string | No | Time window (e.g. "7 days", "30 days", "2 hours") | | category | enum | No | Filter: prompt, tool_result, file_change, file_read, error, command_output, knowledge, summary, other | | project | string | No | Your current working directory — scopes results to this project | | global | boolean | No | Search across ALL projects instead of scoping (default: false) | | tags | string[] | No | Filter by tags (e.g. ["typescript", "error:enoent"]) | | verbose | boolean | No | Return full content instead of snippets (default: false) | | limit | number | No | Results per query (default: 5) |

Example usage by an agent: ```

Project-scoped search (recommended)

kb_recall({ queries: ["authentication bug", "login error fix"], project: "/home/user/myapp", since: "7 days", category: "error", verbose: true })

Global search across all projects

kb_recall({ queries: ["deploy process"], global: true }) ```

Indexing

kb_index

Index a specific session .db file. Supports incremental updates — if the session was already indexed but has new events, only new data is processed.

| Parameter | Type | Required | Description | |---|---|---|---| | db_file | string | Yes | Absolute path to a session .db file |

kb_reindex

Scan the sessions directory and index all new or updated .db files. Incremental by default.

| Parameter | Type | Required | Description | |---|---|---|---| | force | boolean | No | Drop and rebuild the entire knowledge base (default: false) |

Knowledge Management

kb_store

Store a piece of knowledge permanently. By default, knowledge is stored globally (available across all projects). Set scope to "project" and pass a project_dir to restrict it to a specific project.

| Parameter | Type | Required | Description | |---|---|---|---| | content | string | Yes | The knowledge to store | | key | string | No | Short label for retrieval (e.g. "deploy-process") | | tags | string[] | No | Tags for categorization | | source | string | No | Origin (default: "manual") | | scope | enum | No | "global" (default) = available everywhere. "project" = scoped to a project. | | project_dir | string | No | Project directory to scope to (only used when scope is "project") |

kb_forget

Remove stored knowledge by ID or key.

| Parameter | Type | Required | Description | |---|---|---|---| | id | number | No | Knowledge entry ID | | key | string | No | Knowledge key |

kb_list

List all manually stored knowledge entries. Pass project to see only global + project-scoped entries for that directory.

| Parameter | Type | Required | Description | |---|---|---|---| | limit | number | No | Max entries to return (default: 20) | | project | string | No | Filter to global + this project's knowledge entries |

Summarization

kb_summarize

Returns unsummarized session chunks for the calling agent to read and summarize. No external API needed — the agent itself writes the summary.

| Parameter | Type | Required | Description | |---|---|---|---| | session_id | string | No | Summarize a specific session | | last | number | No | Return last N unsummarized sessions (default: 5) |

kb_store_summary

Store an agent-generated session summary.

| Parameter | Type | Required | Description | |---|---|---|---| | session_id | string | Yes | The session ID | | summary | string | Yes | Summary text (3-8 sentences) |

Maintenance

kb_stats

Show knowledge base statistics — sessions indexed, chunks, tags, stored knowledge, summaries, disk usage, breakdowns by project and category.

kb_prune

Remove sessions older than their TTL (default: 90 days).

Database Schema

The knowledge base lives at ~/.claude/context-mode/knowledge.db (SQLite, WAL mode).

| Table | Purpose | |---|---| | sessions | Session metadata (id, project_dir, timestamps, event_count, TTL) | | chunks | Session events broken into searchable chunks (max 2000 chars) | | chunks_fts | FTS5 virtual table over chunks (porter + unicode61 tokenizer) | | tags | Many-to-many chunk tags (auto-extracted: tech keywords, error types, file extensions) | | knowledge | Manually stored knowledge (permanent, optionally project-scoped via project_dir) | | knowledge_fts | FTS5 virtual table over knowledge | | summaries | Agent-generated session summaries | | summaries_fts | FTS5 virtual table over summaries |

Auto-Tagging

Content is automatically tagged during indexing:

• Tech keywords — typescript, react, convex, docker, claude, etc. (~80 keywords)
• Tool names — tool:read, tool:bash, tool:edit, etc.
• Error types — error:enoent, error:typeerror, error:econnrefused, etc.
• File extensions — ext:ts, ext:py, ext:json, etc.
• Event categories — prompt, tool_result, file_change, error, command_output, etc.

Hardening Memory Instructions

To make AI agents reliably use the knowledge base, you need to add hardened memory instructions to your Claude Code configuration. Without these, agents will default to saying "I don't remember" instead of searching the knowledge base.

What are hardened memory instructions?

They are rules placed in Claude Code's memory system that tell the agent to always check the knowledge base before claiming it has no memory of something. This transforms the agent from a stateless assistant into one with persistent recall.

Step 1: Add to CLAUDE.md (project-level)

Add the following to any project's CLAUDE.md file where you want agents to have persistent memory:

## Persistent Memory

This project uses Open Brain Knowledge MCP for cross-session memory.

- When asked about previous sessions or past work, ALWAYS call `kb_recall` before responding
- Always pass your current working directory as `project` when calling `kb_recall` to scope results
- Never say "I don't have memory of that" without first searching the knowledge base
- Use broad AND specific queries to maximize recall (e.g., both the topic name and related keywords)
- Store project-specific decisions with `kb_store({ scope: "project", project_dir: "<this dir>" })`
- Store general knowledge (preferences, processes) with `kb_store` (global by default)

Step 2: Add to Claude Code's auto-memory system

If you use Claude Code's built-in memory (the ~/.claude/projects/<project>/memory/ directory), create a feedback memory file that reinforces the behavior:

Create ~/.claude/projects/<project>/memory/feedback_use_knowledge_base.md:

---
name: Use Open Brain Knowledge MCP for previous session recall
description: When the user asks about previous sessions or past conversations, always use kb_recall from Open Brain Knowledge MCP before saying "I don't remember"
type: feedback
---

When the user asks about something from a previous session, ALWAYS search Open Brain Knowledge MCP (`kb_recall`) before responding. Never say "I don't have any memory of that" without checking first.

**Why:** Open Brain stores cross-session context. Saying "I don't remember" without checking is incorrect — the knowledge may be there.

**How to apply:**
1. When the user references a previous session or asks "what were we talking about", immediately call `kb_recall` with relevant queries.
2. Use broad and specific query variations to maximize recall (e.g., both the topic name and related keywords).
3. Only after checking Open Brain and finding nothing should you tell the user the information wasn't found.

Step 3: Add to MEMORY.md index

In your ~/.claude/projects/<project>/memory/MEMORY.md, add a pointer to the feedback file:

## Feedback
- [feedback_use_knowledge_base.md](feedback_use_knowledge_base.md) — Always check Open Brain kb_recall before saying "I don't remember" when asked about previous sessions

Step 4: Test the hardening

Store a test marker in one session: `` Agent: kb_store({ content: "TEST MARKER — purple octopus test", key: "test-marker", tags: ["test"] }) ``

Start a new session and ask about it: `` User: "We were talking about a purple octopus, why?" Agent: [should call kb_recall before responding] ``

If the agent finds the marker without prompting, your hardened instructions are working.

Optional: Session-start recall hook

For even stronger memory behavior, you can instruct the agent to proactively check the knowledge base at the start of every session. Add this to your feedback memory:

---
name: Read memory at session start
description: Always read user profile and key memory files at the start of every session
type: feedback
---

Read memory files at the start of every session before responding.

**Why:** The user expects continuity across sessions. Forgetting context feels impersonal and wastes time.

**How to apply:** At the beginning of each session, read MEMORY.md and relevant memory files so you know the user's name, preferences, and current project context.

Development

# Run in development mode (hot reload via tsx)
npm run dev

# Build for production
npm run build

# Run production build
npm start

Project Structure

knowledge-mcp/
├── src/
│   ├── server.ts      # MCP server — tool definitions and handlers
│   ├── db.ts          # SQLite database layer, schema, queries
│   ├── indexer.ts      # Session file indexing (incremental)
│   └── tags.ts        # Auto-tag extraction (regex-based)
├── scripts/
│   └── auto-index.mjs  # SessionEnd hook for automatic indexing
├── build/              # Compiled JavaScript output (gitignored)
├── package.json
└── tsconfig.json

License

MIT