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

[![PyPI](https://img.shields.io/pypi/v/canola-persistent-kb-mcp)](https://pypi.org/project/canola-persistent-kb-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## 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+.

```bash
pip install canola-persistent-kb-mcp
```

Or from source:

```bash
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):

```json
{
  "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

```bash
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`](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`](https://github.com/0x67108864/skills/tree/main/persistent-kb) — instruction-based, drop-in folder for agentskills.io runtimes
- Agent Skills standard: [agentskills.io](https://agentskills.io)
- Model Context Protocol: [modelcontextprotocol.io](https://modelcontextprotocol.io)

## License

MIT — see [LICENSE](LICENSE).

## Author

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