# Second Brain (Public)

A persistent, **semantically-searchable memory** for AI agents (Claude, Codex, or any
[MCP](https://modelcontextprotocol.io) 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.

![Second Brain architecture](docs/architecture.svg)

## 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](https://www.docker.com/) — for PostgreSQL + pgvector
- [Node.js](https://nodejs.org/) ≥ 20
- [Ollama](https://ollama.com/) running locally, with the models pulled:
  ```bash
  ollama pull nomic-embed-text   # embeddings (768-dim)
  ollama pull qwen3:8b           # distillation / reflect / dream / forget / rerank
  ```

## Deploy
```bash
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`):
```bash
# 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):
```json
{
  "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
```bash
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](LICENSE)