Second Brain (Public)

A persistent, semantically-searchable memory for AI agents (Claude, Codex, or any MCP client). Memories live in local PostgreSQL + pgvector, are embedded locally with Ollama, and are exposed over the Model Context Protocol plus an optional auto-recall hook. A web UI is included for search, browsing, and a knowledge graph.

Everything runs locally and offline — no API keys, nothing leaves your machine.

Architecture

One store, three loops: Recall reads (hybrid search injects memories into prompts), Capture → Promote grows the store (sessions/imports → review queue → approved memories), and Maintenance curates it (scheduled consolidation, forgetting, and snapshots). Ollama provides local embeddings and the chat model.

Features

• Hybrid retrieval — vector similarity (pgvector HNSW) fused with full-text keyword search via Reciprocal Rank Fusion, then signal-boosted by importance, recency, and access frequency; optional 1-hop graph boost and local-LLM rerank.
• Knowledge graph — typed links between memories, with an interactive 3D view in the UI.
• Capture → promote — optionally log agent sessions, mine them into a review queue, and approve durable facts into long-term memory (nothing is promoted automatically).
• Self-maintenance — scheduled consolidation ("dreaming"), reversible decay + contradiction archival ("forgetting"), and point-in-time database snapshots.
• Import — seed the brain from a ChatGPT data export.

Requirements

• Docker — for PostgreSQL + pgvector
• Node.js ≥ 20
• Ollama running locally, with the models pulled:

  ollama pull nomic-embed-text   # embeddings (768-dim)
  ollama pull qwen3:8b           # distillation / reflect / dream / forget / rerank
  

Deploy

git clone <this-repo-url> second-brain && cd second-brain
cp .env.example .env             # defaults work out of the box; adjust if needed
npm install
npm run db:up                    # start PostgreSQL + pgvector (schema auto-applied)
npm run db:migrate               # idempotently (re)apply the schema
npm run build                    # compile TypeScript -> dist/
npm run api                      # web UI + REST API at http://localhost:8088

Open http://localhost:8088 to search, browse, add, and visualize memories.

Scheduled jobs (dream / forget / reflect / snapshots) run from an in-app scheduler inside the API process, so keep npm run api running if you want them to fire.

Connect an MCP client

Register the compiled MCP server with your agent (use an absolute path to dist/mcp/server.js):

# Claude Code
claude mcp add --scope user second-brain -- node /absolute/path/to/second-brain/dist/mcp/server.js

# Codex
codex mcp add second-brain -- node /absolute/path/to/second-brain/dist/mcp/server.js

Tools exposed: save_memory, search_memory, list_memories, get_memory, update_memory, delete_memory, find_duplicates, distill_text, memory_stats, plus the graph and maintenance tools (link_memories, related_memories, dream, freeze, reflect, forget, review_candidates, promote_candidate, reject_candidate).

Optional: auto-recall hook

Automatically inject the most relevant memories into every prompt. Add a UserPromptSubmit hook that runs the compiled recall CLI (it fails open — any error or timeout simply injects nothing):

{
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [ { "type": "command", "command": "node /absolute/path/to/second-brain/dist/cli/recall.js", "timeout": 15 } ] }
    ]
  }
}

Claude Code reads ~/.claude/settings.json; Codex reads ~/.codex/hooks.json. Remove the entry to disable.

Configuration

Sensible defaults live in .env.example (PostgreSQL on localhost:5432, Ollama on localhost:11434, API on :8088). Key variables: DATABASE_URL, OLLAMA_URL, EMBED_MODEL / EMBED_DIM, DISTILL_MODEL, API_PORT, and the RANK_* ranking weights. Schedules and ranking weights are also editable live in the web UI's Settings tab.

Data & privacy

Memories live only in your local PostgreSQL volume (pgdata). Database snapshots are written to a git-ignored snapshots/ folder, and ChatGPT imports stay in a git-ignored ingest/ folder. Nothing is sent off-machine.

Operations

npm run db:down          # stop the database (data persists in the pgdata volume)
docker compose down -v   # stop AND delete all memories (drops the volume)

License

MIT