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