personal-knowledge — local memory MCP server

Status: personal project, not production-ready. This is shared for reference and informational purposes only. It's a local-first experiment I use and validate on my own machine — expect rough edges, breaking changes, and no support or stability guarantees. Use at your own risk.

A portable, AI-agnostic second brain. Stores typed memories (self / directive / state / knowledge / episode / inquiry) with semantic recall and self-learning re-ranking, exposed to any MCP-capable AI as a local server.

Built on AgentDB (vector store + bandit self-learning) and local bge-small-en-v1.5 embeddings via @huggingface/transformers. Pure local, no API keys, no network required after the first model download.

Quick start

npm install
npm run build

Smoke-test end-to-end (saves seven records, searches them, cites the top hit):

npm run smoke

Related MCP server: OmniHub

Wire it to Claude Code

The server runs as a long-lived HTTP daemon under launchd. Multiple Claude Code sessions all connect to the same daemon, which owns the single RVF writer lock — no more lock collisions across concurrent chats.

npm run build
./bin/install-agent.sh        # generates .env token, installs LaunchAgent, boots it

Then point Claude Code at the daemon (user scope so every project sees it):

TOKEN=$(grep '^MEMORY_AUTH_TOKEN=' .env | cut -d= -f2)
claude mcp add --transport http --scope user memory http://127.0.0.1:7345/mcp \
  -H "Authorization: Bearer $TOKEN"

Confirm:

claude mcp list | grep memory     # → memory: http://127.0.0.1:7345/mcp (HTTP) - ✓ Connected
curl -s http://127.0.0.1:7345/health

Logs: ~/Library/Logs/memory-mcp.{out,err}.log. The agent auto-restarts on crash and on login. Remove with ./bin/uninstall-agent.sh.

Stdio (legacy / smoke tests)

The original stdio transport is still supported when MEMORY_TRANSPORT is unset or stdio — used by npm run smoke and useful when you want a one-shot subprocess instead of a shared daemon:

claude mcp add memory -- node /Users/pcamarajr/Projects/pcamarajr/personal-knowledge/dist/src/server.js

Only one stdio instance can hold the RVF lock at a time, so don't mix it with the daemon.

The tools

The answer tool (and its privacy trade-off)

answer(question, scope?, k?) runs search → synthesize → cite: it retrieves the top-k memories, has a small Claude model (default claude-haiku-4-5) synthesize a grounded prose answer, and calls the internal cite path for every record the synthesis actually used. That citation stream is the genuine usage signal the self-learning re-rank needs — and the synthesized answer keeps raw record bodies out of the calling AI's context. If the memories don't cover the question, it refuses instead of fabricating.

Privacy: the matched record bodies are sent to the Anthropic API for synthesis. This is on by default; configure via .env:

How the schema works

See docs/instructions.md for the full schema, the "when to save" rules, and the retrieval guidance shipped to AI consumers. That file is the contract between this server and every AI that uses it.

Storage

• Vectors and metadata live in ./data/memory.rvf (AgentDB single-file format).

• Per-record metadata mirror lives in ./data/memory.rvf.meta.json (sidecar; the underlying RVF store uses u64 ids and flat metadata, so we keep the rich record state in JSON next to it).

• Both files are gitignored.

• Override the location via MEMORY_DATA_PATH=/some/other/path.rvf.

Self-learning

Signals are split into exposure vs use so the ranking can't feed on itself:

• being returned by a search bumps surface_count only (exposure);

• an explicit get_memory bumps access_count (use);

• cite_memory(id, weight) — called directly or via the answer tool — bumps cite_count/reward_total (the primary reward signal);

• supersede_memory(old, new) penalizes the older record.

Searches tagged source: 'dashboard' or source: 'eval' are exposure-only: they don't feed co-access/co-surface edges or the auto-cite tracker, so UI browsing and eval replays can't pollute the learning signals.

Consolidation

npm run consolidate

V1 just reports stats. V2 will add LLM-driven dedup, link inference, and TTL pruning.

Scope of v1

In: local-only MCP server, 6 typed memory types, semantic search with 1-hop linkage, bandit-based citation feedback.

Out (v2+): public hosting for Claude web, multi-hop Cypher graph queries via the AgentDB causal graph controller, scheduled consolidation, clustering, backfill from existing markdown.