persistent-kb-mcp

A Model Context Protocol (MCP) server that gives any MCP-capable AI agent a persistent, searchable knowledge base stored locally in a single SQLite file. Survives session restarts, context compaction, and machine reboots.

What it does

Exposes 5 MCP tools for interacting with a local SQLite knowledge base:

Tool	Purpose
kb_add	Save a fact, lesson, decision, or reference (with title, kind, tags)
kb_search	Full-text search via SQLite FTS5
kb_show	Fetch a single entry's full content + metadata
kb_list	Browse entries, filter by kind / tag / date
kb_tag	Add or remove tags on an existing entry

Storage default: ~/.persistent-kb/kb.sqlite (override via KB_DB).

Why

AI coding agents lose everything between sessions. This server lets your agent save and recall facts across sessions — without sending data to a cloud service.

Install

Requires Python 3.10+.

pip install canola-persistent-kb-mcp

Or from source:

pip install git+https://github.com/0x67108864/persistent-kb-mcp.git

Configure your agent

Claude Code

Add to your ~/.claude/mcp.json (or the project-local equivalent):

{
  "mcpServers": {
    "persistent-kb": {
      "command": "persistent-kb-mcp"
    }
  }
}

Restart Claude Code and the 5 kb_* tools become available.

Codex CLI / Cursor / other MCP-capable runtimes

Each runtime has its own way of registering MCP servers; the command is always persistent-kb-mcp. Refer to your runtime's MCP configuration documentation.

Quickstart

Once configured, try these in your agent:

"Remember that Stripe's standard payout schedule in Japan is 7 days, 
domestic card fee is 3.6% + ¥40."
→ agent calls kb_add(title=..., kind="reference", tags="stripe,japan", content=...)

(later, in a new session)
"What did we learn about Stripe payouts in Japan?"
→ agent calls kb_search(query="stripe payout japan")
→ retrieves the saved reference and uses it

Configuration

Env var	Default	Purpose
KB_DB	~/.persistent-kb/kb.sqlite	DB file location

Why not Letta / mem0 / OpenAI memory?

Concern	This server	Cloud memory
Network required	❌	✅
API key required	❌	✅
Data leaves your machine	❌	✅
Vendor lock-in	None (SQLite)	Service-specific
Cost	Free	Per-token / per-call

Use this when local-first matters. Use cloud memory when you actually want cross-device sync.

Development

git clone https://github.com/0x67108864/persistent-kb-mcp.git
cd persistent-kb-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .
python -m persistent_kb_mcp  # runs the server on stdio

Schema

The SQLite schema is created automatically on first use. It defines:

• entries — primary table (id, title, kind, content, timestamps, optional superseded_by)
• tags — many-to-many between entries and tag strings
• entries_fts — FTS5 virtual table for keyword search
• relations — typed links between entries

See src/persistent_kb_mcp/db.py for the DDL.

Roadmap

• v0.2 — optional vector embedding for semantic search
• v0.3 — export/import for cross-machine sync
• v0.4 — time-decay scoring for relevance

Related

• The original SKILL.md format version: canola_oil/skills/persistent-kb — instruction-based, drop-in folder for agentskills.io runtimes
• Agent Skills standard: agentskills.io
• Model Context Protocol: modelcontextprotocol.io

License

MIT — see LICENSE.

Author

canola_oil — https://0x67108864.github.io/