somtum 3.0.0 → 3.1.0

package/README.md

@@ -1,909 +1,170 @@
-<img src="./assets/logo.png" width="500" alt="Somtum Logo">
+<img src="./assets/logo.png" width="420" alt="Somtum">
 
-**Local-first memory and prompt-cache layer for coding agents: Claude Code and Codex.**
+**Long-term memory for Claude Code and Codex that meters every token it spends.**
 
-[**Docs**](https://riz007.github.io/somtum/) · [**npm**](https://www.npmjs.com/package/somtum)
-
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm version](https://badge.fury.io/js/somtum.svg)](https://www.npmjs.com/package/somtum)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Somtum (Thai: ส้มตำ) is named after the vibrant, shredded green papaya salad. Just like its namesake, Somtum blends durable observations from your Claude Code and Codex sessions — decisions, bugfixes, learnings, file summaries — stores them in a local SQLite database, and injects the relevant ones back into context the next time you work on the same project.
-
-Zero-config: one `somtum init` and every session end is captured automatically. No server, no cloud account, no mandatory tuning.
-
----
-
-## Table of Contents
-
-- [Why Somtum?](#why-somtum)
-- [How it works](#how-it-works)
-- [Requirements](#requirements)
-- [Install](#install)
-- [Quickstart](#quickstart)
-- [Verifying the setup](#verifying-the-setup)
-- [Dashboard](#dashboard)
-- [CLI Reference](#cli-reference)
-- [MCP Server](#mcp-server)
-- [Storage Layout](#storage-layout)
-- [Configuration](#configuration)
-- [Privacy](#privacy)
-- [Token Accounting](#token-accounting)
-- [Performance](#performance)
-- [Development](#development)
-- [Troubleshooting](#troubleshooting)
-- [License](#license)
-
-> **v3.0.0** — Codex support (`somtum init --agent codex`) · selectable extraction backends incl. Codex CLI and GLM · fixes silently lost sessions and oversized extraction calls · [upgrade guide](https://riz007.github.io/somtum/guide/upgrading-v3)
->
-> **v2.0.0** — Global DB (`~/.somtum/global.db`) · cross-project workspace recall · memory deduplication (`superseded_by`) · `--show-superseded` on `somtum list` · stats instrumentation fix · dashboard dark-mode redesign
->
-> **v1.5.0** — Multi-page VitePress docs site · `somtum list` · `somtum reset` · `somtum forget --all` · embeddings timeout safety · config crash-resilience · `injection.max_chars` wired up · warm-start race fix · auth-error hints
->
-> **v1.3.0** — Auto-inject memories on every prompt · `update` MCP tool · warm-start after compaction · false-hit detection · workspace scope · `suggest-claude-md` · stale memory detection in `doctor`
-
----
-
-## Why Somtum?
-
-Coding agents like Claude Code and Codex start every session with a blank slate. That leads to:
-
-- **Repetitive context** — re-explaining the same architectural choices every session
-- **Regressions** — the agent suggests a fix you already tried and discarded
-- **Token waste** — reading large files just to "set the scene"
-
-**Somtum gives your coding agent a long-term memory.** Once a decision is made or a bug is fixed, it's remembered across all future sessions, in Claude Code and Codex alike, without bloating your context window.
-
-### What a session looks like with Somtum
-
-```
-Without Somtum                    With Somtum
-────────────────────              ──────────────────────────────────────
-Session 1: "We use pnpm           Session 1: same work
-           because of workspace
-           hoisting"
-
-Session 2: Claude suggests        Session 2: Claude already knows about
-           npm, you correct it       pnpm, the auth decisions, and the
-           again                     bugfixes from last week
-```
-
----
-
-## How it works
-
-At the end of each Claude Code or Codex session, Somtum reads the session transcript and asks a small model to extract the parts worth keeping — decisions, bug fixes, things learned. Those observations are stored locally in SQLite. **On every subsequent prompt**, Somtum automatically retrieves the most relevant memories and injects them into context — no manual recall needed.
-
-### Memory lifecycle
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│               Claude Code or Codex session                  │
-│                                                             │
-│       you code · debug · review · make decisions            │
-└──────────────────────────────┬──────────────────────────────┘
-                               │ SessionEnd / PreCompact
-                               ▼
-┌─────────────────────────────────────────────────────────────┐
-│                     Capture Pipeline                        │
-│                                                             │
-│  session transcript ──► Haiku extracts observations         │
-│                                                             │
-│      decisions · bug fixes · learnings · commands           │
-│                                                             │
-│  PreCompact ─── writes warm-start file ──► next session     │
-└──────────────────────────────┬──────────────────────────────┘
-                               │ persisted locally
-                               ▼
-                 ┌─────────────────────────┐
-                 │  ~/.somtum/projects/    │
-                 │     <project-hash>/     │
-                 │                         │
-                 │  db.sqlite              │
-                 │  index.md               │
-                 │  memories/YYYY-MM/      │
-                 └────────────┬────────────┘
-                              │ every prompt (UserPromptSubmit)
-                              ▼
-┌─────────────────────────────────────────────────────────────┐
-│                 Auto-Inject Pipeline (new)                  │
-│                                                             │
-│  1. Prompt cache lookup (exact + fuzzy match)               │
-│  2. BM25 recall — top-k relevant memories                   │
-│  3. Warm-start context (if session just compacted)          │
-│                                                             │
-│      all injected as additionalContext automatically        │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### What gets captured — a concrete example
-
-You work a session debugging an auth bug and refactoring a module. At session end, Somtum extracts something like:
-
-```json
-[
-  {
-    "kind": "bugfix",
-    "title": "JWT refresh loop caused by missing expiry check",
-    "body": "The refresh token loop was triggered because we checked token.exp < Date.now() instead of token.exp < Date.now() / 1000. Unix timestamps are in seconds, not milliseconds.",
-    "files": ["src/auth/refresh.ts"]
-  },
-  {
-    "kind": "decision",
-    "title": "Use pnpm workspaces — npm hoisting breaks shared types",
-    "body": "Switched from npm to pnpm because npm's hoisting puts shared type packages in the wrong node_modules scope, breaking type inference across packages.",
-    "files": ["package.json", "pnpm-workspace.yaml"]
-  }
-]
-```
-
-Next session, when you ask "why are we using pnpm?" or touch `src/auth/refresh.ts`, the agent gets these memories and already has the context.
-
-### Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                 Claude Code / Codex / MCP client            │
-└──────────┬──────────────────────────────┬───────────────────┘
-           │ hooks                        │ MCP tools
-           ▼                              ▼
-┌─────────────────────┐         ┌──────────────────────────┐
-│  Hooks              │         │   MCP Tools              │
-│                     │         │                          │
-│  UserPromptSubmit ──┼─cache──▶│ cache_lookup             │
-│                   ──┼─inject─▶│ recall / get             │
-│  SessionEnd ────────┼─capture▶│ remember / update        │
-│  PreCompact ────────┼─warmst─▶│ forget                   │
-│  PreToolUse (Read) ─┼─gate───▶│ stats                    │
-│                     │         │ report_false_hit          │
-└──────────┬──────────┘         └────────────┬─────────────┘
-           │                                 │
-           ▼                                 ▼
-┌─────────────────────────────────────────────────────────────┐
-│                      Core (TypeScript)                      │
-│                                                             │
-│  ┌──────────────┐  ┌─────────────────┐  ┌───────────────┐  │
-│  │ PromptCache  │  │  MemoryStore    │  │   Retriever   │  │
-│  │              │  │                 │  │               │  │
-│  │ exact hash   │  │ observations    │  │ bm25(default) │  │
-│  │ fuzzy embed  │  │ scope: project  │  │ embeddings    │  │
-│  │ fingerprint  │  │         global  │  │ index         │  │
-│  │ false_hits   │  │       workspace │  │ hybrid        │  │
-│  └──────────────┘  │ last_confirmed  │  └───────────────┘  │
-│                    └─────────────────┘                      │
-└─────────────────────────────────┬───────────────────────────┘
-                                  │
-                                  ▼
-                    ┌─────────────────────────────┐
-                    │  SQLite WAL + ~/.somtum/     │
-                    │  /projects/<hash>/           │
-                    │    db.sqlite                 │
-                    │    index.md                  │
-                    │    memories/YYYY-MM/<ulid>.md│
-                    │  /session/lh_<id>.json       │
-                    │  /warmstart/ws_<id>.json     │
-                    └─────────────────────────────┘
-```
-
-### Retrieval strategies
-
-| Strategy         | How it works                                                                             | Best for                                       | Cost                             |
-| ---------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------- | -------------------------------- |
-| **`bm25`**       | Keyword search over title + body + tags (SQLite FTS5 — no external dependencies)         | Exact terms, offline setups                    | Near-zero                        |
-| **`embeddings`** | Semantic similarity using a 30 MB local model (bge-small-en-v1.5, runs fully in-process) | "What did we decide about auth?" style queries | ~5 ms at 10k memories            |
-| **`index`**      | Sends a compact memory catalog to Haiku; the model picks relevant IDs                    | Paraphrased or fuzzy queries                   | 1 Haiku API call                 |
-| **`hybrid`**     | BM25 + embeddings results merged and re-ranked by Haiku                                  | General case (best recall)                     | BM25 + embeddings + 1 Haiku call |
-
-**Default is `bm25`** — works offline, no setup. Enable `hybrid` once you have embeddings downloaded.
-
-> **Caution:** Setting `strategy=hybrid` without enabling embeddings causes a silent fallback to BM25 while paying hybrid overhead. Run `somtum doctor` — if it shows `strategy=hybrid` alongside `embeddings: disabled`, fix it:
->
-> ```bash
-> somtum config set retrieval.strategy bm25       # match what's actually running
-> # or, to use real hybrid:
-> somtum config set retrieval.embeddings.enabled true && somtum reindex
-> ```
-
----
-
-## Requirements
+[Docs](https://riz007.github.io/somtum/) · [What it costs](https://riz007.github.io/somtum/guide/costs) · [CLI reference](https://riz007.github.io/somtum/reference/cli) · [Changelog](CHANGELOG.md)
 
-- **Node 20+**
-- **Claude Code or Codex** — Somtum hooks into their `SessionEnd`, `PreCompact` and `UserPromptSubmit` events. Both agents share one memory store per project.
-- **An extraction backend**, picked automatically in this order:
-  1. `ANTHROPIC_API_KEY`, or `ANTHROPIC_AUTH_TOKEN` + `ANTHROPIC_BASE_URL` for Anthropic-compatible providers such as GLM
-  2. the `claude` CLI (Claude Code subscribers need no separate key)
-  3. the `codex` CLI (ChatGPT/Codex subscribers need no separate key)
+Your coding agent forgets everything when a session ends or its context compacts. Somtum keeps the parts worth keeping (decisions, root causes, commands that finally worked) in a local SQLite database and hands the relevant ones back on later prompts. Claude Code and Codex share the same memory.
 
-  Override with `somtum config set extraction.backend anthropic|claude-cli|codex-cli`.
+Memory is paid for in tokens, so Somtum is built to never multiply your bill. It only sends what it hasn't sent before, skips work that can't pay off, caps everything it adds to a prompt, and writes every token it spends to a ledger you can read with `somtum stats`.
 
----
+Named after ส้มตำ, the Thai green papaya salad: shredded fine, only what's fresh.
 
-## Install
+## Quick start
 
 ```bash
 npm install -g somtum
+cd your-project           # the directory you launch your agent from
+somtum init               # Claude Code: capture + recall hooks, MCP server
+somtum init --agent codex # Codex (run both if you use both)
+somtum doctor             # every line should show ✓
 ```
 
-> **pnpm users:** `pnpm add -g somtum` works if you have run `pnpm setup` first (sets `PNPM_HOME`). If you haven't, use npm above.
->
-> **yarn users:** `yarn global add` is not supported in Yarn v2+ (Berry). Use npm above.
-
-### From source
-
-```bash
-git clone https://github.com/riz007/somtum
-cd somtum
-pnpm install
-pnpm build
-pnpm link --global
-```
-
-### Native module note
-
-Somtum uses [`better-sqlite3`](https://github.com/WiseLibs/better-sqlite3), which contains a native C++ addon. On most platforms (macOS, Linux x64/arm64, Windows x64) a prebuilt binary is downloaded automatically. On Alpine Linux / musl or unusual architectures, the addon compiles from source — `python`, `make`, and `gcc` must be available. If the install fails with a node-gyp error, install those build tools and retry.
-
----
-
-## Quickstart
-
-### Step 1 — Check your extraction backend
-
-At the end of each session Somtum asks a small model to pull out what's worth remembering. It uses the first backend available, so most people need to do nothing:
-
-| You have | Backend used |
-| --- | --- |
-| `ANTHROPIC_API_KEY` in your shell profile | Anthropic API (Haiku) |
-| `ANTHROPIC_AUTH_TOKEN` + `ANTHROPIC_BASE_URL` (GLM or another Anthropic-compatible provider) | that provider |
-| Claude Code installed (`which claude` prints a path) | `claude` CLI, on your subscription |
-| Codex installed (`which codex` prints a path) | `codex` CLI, on your ChatGPT plan |
-
-> Keys must be in your shell profile, not just exported in an open terminal tab. Hooks inherit the environment of the shell that _started_ the agent.
-
-### Step 2 — Install in your project
-
-Run from the **root of the project you open in your agent**.
-
-**Claude Code**
-
-```bash
-somtum init --all
-# Installs:
-#   - SessionEnd + PreCompact capture hooks  (memory extraction)
-#   - UserPromptSubmit hook                  (auto-inject + prompt cache)
-#   - PreToolUse file-gating hook            (large file summarization)
-#   - MCP server in .mcp.json                (recall/remember tools)
-```
-
-> Use `--all`. A plain `somtum init` installs only the capture hooks: memories are saved but not injected, and the agent sees them only if it calls the MCP `recall` tool.
-
-**Codex** (or both, on the same project; they share one memory store):
+Then use your agent as usual. Memories appear after your first substantial session ends or compacts:
 
 ```bash
-somtum init --agent codex
-# Installs:
-#   - .codex/hooks.json   SessionEnd + PreCompact capture, UserPromptSubmit injection
-#   - .codex/config.toml  [mcp_servers.somtum]
+somtum list               # what was remembered
+somtum stats              # what it cost
 ```
 
-Codex only loads project-level config for trusted projects. Sessions are read from `~/.codex/sessions` (or `$CODEX_HOME/sessions`).
+Requires Node 20+ and one way to run a small model for extraction. Somtum uses the first one it finds: `ANTHROPIC_API_KEY` (or an Anthropic-compatible provider through `ANTHROPIC_AUTH_TOKEN` + `ANTHROPIC_BASE_URL`), then the `claude` CLI, then the `codex` CLI. If you can run your agent, you already have one.
 
-### Step 3 — Verify your setup
+## What it does
 
-Run doctor immediately after init to confirm everything is connected:
+**Captures.** When a session ends or compacts, Somtum sends the turns it hasn't seen yet to a small model (Claude Haiku by default) and stores what comes back as short typed records:
 
-```bash
-somtum doctor
+```json
+{
+  "kind": "bugfix",
+  "title": "JWT refresh loop: exp is in seconds, not ms",
+  "body": "Compared token.exp against Date.now(); must divide by 1000.",
+  "files": ["src/auth/refresh.ts"]
+}
 ```
 
-All checks should show `✓`. The two most important are:
+**Recalls.** On each prompt, a local keyword search (SQLite FTS5, no network) picks up to 3 relevant memories and adds them to the agent's context, capped at 1,500 characters. Nothing is added when nothing matches, and a memory that's already in the session's context isn't added again.
 
-- **`extraction_backend`** — confirms Somtum has a model to extract memories with
-- **`hooks_installed`** — confirms hooks are registered for Claude Code, Codex, or both
+**Shares.** Claude Code and Codex read and write one memory per project. Any MCP client can use the `recall` and `remember` tools. Memories saved with `scope: "global"` follow you into every project.
 
-Do not start your first session until all checks pass. Each failing check shows an inline fix command.
+Everything is stored under `~/.somtum/`. Data leaves your machine only in model calls through the backend you chose: extraction, plus file summaries if you turn on file gating.
 
-### Step 4 — Use your agent normally
+## What it costs
 
-Open Claude Code or Codex **from the same directory** where you ran `somtum init`. Work as you normally would. When the session ends, the hook extracts observations automatically in the background (capped at 90 seconds).
+Somtum spends tokens in two places: on extraction, and on the context it adds to your prompts. Both are bounded, and both are metered.
 
-### Step 5 — Check your memory
+| Cost | When | Bound | Turn it down |
+| --- | --- | --- | --- |
+| Extraction | Session end or compaction | Only turns not yet extracted, at most 60k tokens. No call when fewer than 500 new tokens. | `extraction.min_new_tokens`, `extraction.max_observations_per_session` |
+| Injected memories | A prompt that matches stored memories | Up to 3 memories, 1,500 characters (about 375 tokens). A memory already in context is not re-sent. | `injection.k`, `injection.max_chars`, `injection.enabled` |
+| File summaries | Only if you enable file gating | One small-model call per large file that changed | `file_gating.enabled` (off by default) |
 
-```bash
-# How many observations were captured?
-somtum stats
-
-# Search memory
-somtum search "auth jwt rotation"
-somtum search "why we use pnpm" --strategy hybrid
+`somtum stats` reads the ledger. This is real output:
 
-# Open the visual dashboard
-somtum serve
 ```
-
-If `somtum stats` shows `memories 0` after a session, see [Troubleshooting](#troubleshooting).
-
----
-
-## Verifying the setup
-
-After your **first** session ends:
-
-**1. Check the hook log**
-
-```bash
-cat ~/.somtum/hook.log
+Somtum's own token use, metered (all time)
+  extraction            4 calls     54,785 tok   1 skipped
+  injected context   14 prompts      4,060 tok   added to your agent's input
+  total                             58,845 tok
 ```
 
-A successful run:
+Use `somtum stats --since 7d` for a window, or `--json` to feed it into something else. Extraction runs on whatever backend you configured. On the `claude` or `codex` CLI, it draws on your existing plan rather than a separate bill.
 
-```
-2026-04-30T10:15:42.123Z [post_session] starting
-2026-04-30T10:15:44.891Z [post_session] ok — inserted=4 superseded=1 cache=2 summaries=1
-```
+### Measured: not paying twice for the same transcript
 
-Each run also logs which backend it used:
+Through v3.0, a session that compacted and then ended was extracted twice, and the second call re-sent everything the first had already processed. Somtum now keeps a per-session cursor and sends only new turns. These numbers come from replaying three real Claude Code sessions through the pipeline with a stub model, each compacting once at 60% of its length. Tokens are counted over the exact extraction requests, using the same tokenizer approximation `somtum stats` uses:
 
-```
-2026-04-30T10:15:42.124Z [post_session] extraction backend: claude-cli
-```
+| Session | Turns | v3.0 extraction tokens | v3.1 extraction tokens | Saved |
+| --- | ---: | ---: | ---: | ---: |
+| Web app redesign | 309 | 64,577 | 41,756 | 35% |
+| API service | 36 | 47,892 | 25,498 | 47% |
+| Course assignment | 132 | 21,966 | 13,029 | 41% |
 
-Neither backend available:
+### What Somtum cannot measure
 
-```
-2026-04-30T10:15:42.123Z [post_session] ERROR: No extraction backend: set ANTHROPIC_API_KEY (or ANTHROPIC_AUTH_TOKEN + ANTHROPIC_BASE_URL), or install the claude or codex CLI.
-```
+The tokens you save because the agent already knew something (the npm-vs-pnpm argument you didn't have again) never show up in any transcript, so Somtum can't count them. `somtum stats` shows a heuristic estimate for this and labels it as one. Somtum also only sees what's in transcripts: model calls your agent makes that never appear there are invisible to it. For whole-agent spend, use your agent's own usage reporting, such as Claude Code's OpenTelemetry export.
 
-**2. Check stats**
+## File gating (opt-in)
 
-```bash
-somtum stats
-```
+With file gating on, the first time the agent tries to read a whole large file in a session, Somtum answers with a summary of it, generated earlier, as long as the file hasn't changed since. If the agent needs the actual contents, it reads the file again and that read goes through. Partial reads (with an offset or limit) are never gated.
 
-You should see `memories > 0` after a substantive session. Short or trivial sessions (no decisions, no bug fixes) correctly return 0 — the extractor only keeps durable observations.
-
-**3. Run doctor**
+Whether this saves anything depends on how often a summary is enough, so it's metered on both sides. `somtum stats` shows full reads avoided, summary tokens shown, and files read anyway, plus the net. After 10 gated reads, `somtum doctor` tells you to turn it off if the net is negative.
 
 ```bash
-somtum doctor
+somtum init --file-gating   # installs the hook and turns it on for this project
 ```
 
-All checks should show `✓`. The `api_key` and `hooks_installed` checks are the two most commonly failing.
-
----
+Claude Code only.
 
-## Dashboard
+## Everyday commands
 
-```bash
-somtum serve
-# Opens http://localhost:3000
-```
-
-The dashboard has four views:
-
-- **Memory browser** — searchable, filterable list of all captured observations. Switch between BM25, hybrid, and embeddings strategies live. Click any memory to see its full body, files, and tags.
-- **Knowledge graph** — nodes are memories, edges connect memories that share files or tags. Click a node to open it in the detail panel.
-- **Analytics** — kind breakdown, cache hit rate, retrieval strategy usage, top-referenced files.
-- **Forget button** — soft-delete any memory directly from the browser.
-
-| Flag         | Default | Description                              |
-| ------------ | ------- | ---------------------------------------- |
-| `--port <n>` | 3000    | Listen on a custom port                  |
-| `--no-open`  | —       | Start server without opening the browser |
-
-Press `Ctrl-C` to stop.
-
----
-
-## CLI Reference
-
-### Setup
-
-| Command                     | Description                                                  |
-| --------------------------- | ------------------------------------------------------------ |
-| `somtum init`               | Install the SessionEnd capture hook                                           |
-| `somtum init --cache`       | Also install the UserPromptSubmit cache + auto-inject hook                    |
-| `somtum init --file-gating` | Also install the PreToolUse file-gating hook                                  |
-| `somtum init --all`         | Install all hooks + MCP server                                                |
-| `somtum init --force`       | Reinstall even if hooks already present                                       |
-| `somtum doctor`             | Check DB health, migrations, hooks, API key, breakeven ratio, stale memories  |
-
-### Memory
-
-| Command                                      | Description                                                                   |
-| -------------------------------------------- | ----------------------------------------------------------------------------- |
-| `somtum list`                                | List stored memories (most recent first, superseded hidden by default)        |
-| `somtum list --kind decision`                | Filter by kind: `decision \| learning \| bugfix \| command \| file_summary`   |
-| `somtum list --limit 20`                     | Limit to 20 results                                                           |
-| `somtum list --json`                         | Machine-readable JSON output                                                  |
-| `somtum list --show-superseded`              | Include memories that have been superseded by a newer duplicate               |
-| `somtum search <query>`                      | Search observations (default: `bm25` strategy)                                |
-| `somtum search <query> --strategy hybrid`    | Force a specific retrieval strategy                                           |
-| `somtum search <query> -k 16`                | Return more results                                                           |
-| `somtum show <id>`                           | Print the full body of an observation                                         |
-| `somtum remember`                            | Manually store an observation                                                 |
-| `somtum forget <id>`                         | Soft-delete an observation by id                                              |
-| `somtum forget --all`                        | Soft-delete **all** observations in the current project                       |
-| `somtum edit <id>`                           | Open an observation body in `$EDITOR`                                         |
-| `somtum rebuild`                             | Regenerate `index.md` from all observations                                   |
-| `somtum reindex`                             | Recompute embeddings (after enabling embeddings or changing model)            |
-| `somtum suggest-claude-md`                   | Suggest CLAUDE.md additions from accumulated observations (interactive)       |
-| `somtum suggest-claude-md --dry-run`         | Preview suggestions without writing                                           |
-| `somtum suggest-claude-md --yes --limit 20`  | Auto-confirm, limit to top 20 by tokens saved                                 |
-
-### Stats & Visibility
-
-| Command                   | Description                                       |
-| ------------------------- | ------------------------------------------------- |
-| `somtum stats`            | Tokens saved, cache hit rate, retrieval breakdown |
-| `somtum stats --json`     | Machine-readable JSON output                      |
-| `somtum serve`            | Open the visual dashboard in the browser          |
-| `somtum serve --port <n>` | Use a custom port (default 3000)                  |
-| `somtum serve --no-open`  | Start server without opening the browser          |
-
-### Data Management
-
-| Command                                           | Description                                                               |
-| ------------------------------------------------- | ------------------------------------------------------------------------- |
-| `somtum export`                                   | Export observations to stdout as JSON                                     |
-| `somtum export --format jsonl --output obs.jsonl` | Export as JSONL file                                                      |
-| `somtum export --format markdown`                 | Export as readable Markdown                                               |
-| `somtum export --include-deleted`                 | Include soft-deleted entries                                              |
-| `somtum import <file>`                            | Import observations from JSON or JSONL                                    |
-| `somtum purge --older-than 30d`                   | Hard-delete soft-deleted entries older than 30 days                       |
-| `somtum purge --older-than 30d --dry-run`         | Preview without deleting                                                  |
-| `somtum reset`                                    | **Permanently** wipe all memories for the current project (asks to confirm) |
-| `somtum reset --yes`                              | Skip confirmation (useful in CI or scripts)                               |
-
-### Configuration
-
-| Command                                                        | Description                       |
-| -------------------------------------------------------------- | --------------------------------- |
-| `somtum config get`                                            | Print the full resolved config    |
-| `somtum config get retrieval.strategy`                         | Read a single key (dot-separated) |
-| `somtum config set retrieval.strategy hybrid`                  | Write to `.somtum/config.json`    |
-| `somtum config set retrieval.embeddings.enabled true --global` | Write to `~/.somtum/config.json`  |
-
-### Sync
-
-| Command              | Description                               |
-| -------------------- | ----------------------------------------- |
-| `somtum sync status` | Compare local vs remote observation count |
-| `somtum sync push`   | Export and scp observations to remote     |
-| `somtum sync pull`   | scp from remote and merge into local DB   |
-
-Set your remote: `somtum config set sync.remote "user@host:/path/.somtum/projects/<id>"`
-
-Somtum uses hostname-aware syncing — merging observations from multiple machines without data loss.
-
----
-
-## MCP Server
-
-When you run `somtum init --all` (Claude Code) or `somtum init --agent codex`, Somtum registers an MCP server the agent can call on its own during a session. Any other MCP client can use it too: point it at `somtum mcp` over stdio.
-
-| Tool                | What the agent does with it                                                                                        |
-| ------------------- | --------------------------------------------------------------------------------------------------------------- |
-| `recall`            | Searches memories when unsure about a project detail. Merges project + global DB results. Accepts `strategy`    |
-| `get`               | Retrieves full observation bodies by ID. Checks global DB if not found in project DB. Bumps `last_confirmed_at` |
-| `remember`          | Stores an observation manually. `scope='global'` routes to `~/.somtum/global.db`; returns `stored_in` field     |
-| `update`            | Updates an existing observation's title, body, tags, or files. Redaction applied                                |
-| `cache_lookup`      | Checks the prompt cache directly                                                                                 |
-| `report_false_hit`  | Reports that a cached response didn't answer the question (tunes fuzzy threshold data)                          |
-| `forget`            | Soft-deletes an observation                                                                                      |
-| `stats`             | Reports tokens saved, cache hit rate, false-hit count, corpus size, and `global_memories` count                 |
-
-Every MCP response includes a `tokens` field so the agent can account for retrieval cost.
-
-### Memory scope
-
-Observations now carry a `scope` field:
-
-| Scope       | Meaning                                                         | Use it when                                          |
-| ----------- | --------------------------------------------------------------- | ---------------------------------------------------- |
-| `project`   | Default. Visible only in this project.                          | Most decisions, bugfixes, and learnings.             |
-| `workspace` | Shared across projects via the `recall` MCP tool.               | Team conventions, preferred libraries, global rules. |
-| `global`    | Same as workspace; reserved for personal preferences that span all your projects. | Your personal coding preferences.   |
-
-```
-# Store a workspace-scoped observation from within a session:
-remember("Always use pnpm for Node projects", body="...", scope="workspace")
-```
+| Command | What it does |
+| --- | --- |
+| `somtum doctor` | Checks setup: backend, hooks, database, and whether file gating pays off |
+| `somtum stats` | Metered token use, memory counts, cache stats |
+| `somtum list` / `somtum search <query>` | Browse or search memories |
+| `somtum show <id>` / `somtum edit <id>` / `somtum forget <id>` | Read, fix or delete one memory |
+| `somtum serve` | Local dashboard: memory browser, graph, analytics |
+| `somtum suggest-claude-md` | Suggest `CLAUDE.md` additions from your memories |
+| `somtum export` / `somtum import` | Move memories as JSON, JSONL or Markdown |
 
----
+Full list: [CLI reference](https://riz007.github.io/somtum/reference/cli). Settings: [configuration](https://riz007.github.io/somtum/reference/configuration).
 
-## Storage Layout
+## How it works
 
 ```
-~/.somtum/
-├── config.json                         ← global config (merged with project config)
-├── hook.log                            ← timestamped log of every hook execution
-├── global.db                           ← global-scope memories (scope='global'), queried
-│                                         alongside every project DB on recall + auto-inject
-├── session/
-│   └── lh_<id>.json                    ← last cache-hit state per project (false-hit detection)
-│                                         files older than 24 h are evicted automatically
-├── warmstart/
-│   └── ws_<id>_<timestamp>.json        ← warm-start context written after PreCompact (30 min TTL)
-│                                         timestamped so concurrent windows don't clobber each other
-└── projects/
-    └── <project_id>/
-        ├── db.sqlite                   ← source of truth (SQLite WAL)
-        ├── index.md                    ← human-readable mirror (regenerated)
-        └── memories/
-            └── YYYY-MM/
-                └── <ulid>.md           ← per-observation markdown files
+ Claude Code / Codex
+   │  SessionEnd, PreCompact        ─────► extract new turns ─► small model ─► observations
+   │                                                                              │
+   │  UserPromptSubmit              ◄───── top memories (FTS5/BM25, local) ◄──────┤
+   │                                                                              │
+   │  PreToolUse Read (opt-in)      ◄───── file summary instead of full read ◄────┤
+   │                                                                              ▼
+   │  MCP: recall · remember · get · update · forget · stats      ~/.somtum/projects/<id>/db.sqlite
+   │                                                               ~/.somtum/global.db
+   │                                                              token ledger (every event above)
 ```
 
-The project ID is derived from the git remote URL (or directory path if no remote). The same project maps to the same ID across machines as long as the remote URL matches.
-
-SQLite is the source of truth. Edit observations with `somtum edit <id>`, not by hand.
-
----
-
-## Configuration
+Details, including retrieval strategies, deduplication and warm starts after compaction: [How it works](https://riz007.github.io/somtum/guide/how-it-works).
 
-Global config lives at `~/.somtum/config.json`. Per-project config at `.somtum/config.json` overrides it (deep merge).
-
-### Most common settings
-
-```bash
-# Enable semantic (embedding-based) search — downloads a 30 MB model once
-somtum config set retrieval.embeddings.enabled true
-somtum reindex
+## Upgrading from 3.0
 
-# Switch to hybrid retrieval (BM25 + embeddings + rerank) for best recall
-somtum config set retrieval.strategy hybrid
-
-# Use LLM-based retrieval (no embeddings required, costs one Haiku call per query)
-somtum config set retrieval.index.enabled true
-somtum config set retrieval.strategy index
-
-# Disable file-gating (on by default — intercepts large file reads and serves cached summary)
-somtum config set file_gating.enabled false
-
-# Limit observations extracted per session (default: 10)
-somtum config set extraction.max_observations_per_session 5
-
-# Pin the extraction backend (default: auto) and the model codex exec uses
-somtum config set extraction.backend codex-cli
-somtum config set extraction.codex_model <model>
-
-# Control automatic memory injection on every prompt (default: on)
-somtum config set injection.enabled false          # turn off auto-inject
-somtum config set injection.k 5                    # inject more memories (default: 3)
-somtum config set injection.max_chars 3000         # raise injection size cap (default: 1500)
-```
-
-### Full config reference
-
-```jsonc
-{
-  "extraction": {
-    "model": "claude-haiku-4-5-20251001",
-    "trigger": ["SessionEnd", "PreCompact"],
-    "max_observations_per_session": 10,
-  },
-  "cache": {
-    "enabled": true,
-    "fuzzy_match": true,
-    "fuzzy_threshold": 0.92, // raise to 0.95 once you have false-hit signal
-    "max_entries": 10000,
-    "ttl_days": 90,
-  },
-  "retrieval": {
-    "strategy": "bm25", // bm25 | embeddings | index | hybrid
-    "k": 8,
-    "rerank_model": "claude-haiku-4-5-20251001",
-    "bm25": { "enabled": true },
-    "embeddings": {
-      "enabled": false, // set true to download the 30 MB ONNX model
-      "model": "Xenova/bge-small-en-v1.5",
-    },
-    "index": {
-      "enabled": false, // set true to use Haiku as the retriever
-      "model": "claude-haiku-4-5-20251001",
-    },
-  },
-  // Auto-inject: BM25-retrieved memories prepended to every UserPromptSubmit.
-  // Uses the hot path (< 2 ms at 1k memories). Disable if you prefer pull-only.
-  "injection": {
-    "enabled": true,
-    "k": 3,                   // max memories injected per prompt
-    "max_chars": 1500,        // hard cap on injected text
-    "min_relevance_score": 0, // raise (e.g. 1.0) to only inject high-scoring matches
-    "show_budget": true,      // prepend "[somtum] injected N/M memories (~X tokens)" line
-  },
-  "file_gating": {
-    "enabled": true,          // intercepts large file reads; serves cached summary instead
-    "min_file_size_tokens": 300,
-    "exclude_globs": ["**/*.env", "**/secrets/**"],
-  },
-  "privacy": {
-    "telemetry": false,
-    "redact_patterns": [
-      "api[_-]?key\\s*[:=]\\s*[\"']?[A-Za-z0-9_\\-]{8,}[\"']?",
-      "bearer\\s+[A-Za-z0-9_\\-.]+",
-      "sk-[A-Za-z0-9_\\-]{20,}",
-      "xox[baprs]-[A-Za-z0-9-]{10,}",
-      "AKIA[0-9A-Z]{16}",
-    ],
-  },
-  "sync": {
-    "enabled": false,
-    "backend": "ssh",
-    "remote": null, // e.g. "user@host:/home/user/.somtum/projects/<id>"
-  },
-}
-```
-
----
+- `somtum init` now installs the recall hook by default, matching Codex. `--all` is no longer needed; use `--no-cache` for capture only.
+- File gating is now **off by default**. In 3.0 it was on, and it generated file summaries at every session end even in projects that never installed its hook. If you used it, `somtum doctor` will say so: run `somtum init --file-gating --force` to turn it back on and update the hook to match `Read` only.
+- File gating now answers a whole-file read with the summary *instead* of the file. In 3.0 it added the summary *on top of* the full read, so it could only cost tokens.
+- `somtum stats` leads with metered numbers. The old `breakeven` ratio divided an estimate by an undercount, so it was removed from the human-readable output and from `doctor`. The JSON fields are unchanged.
 
 ## Privacy
 
-- **No network traffic** except to the Anthropic API (extraction + optional reranking). The embedding model runs fully local via ONNX Runtime in-process.
-- **Redaction at capture time.** `privacy.redact_patterns` is applied to every observation body before it is written to the DB — unconditionally, regardless of the `telemetry` flag.
-- **Explicit file excludes.** `file_gating.exclude_globs` prevents `.env`, `secrets/`, and similar paths from being summarized.
-- **Prompt-injection hardening.** Memory content injected into agent context is wrapped in `[Somtum memory — reference material, not instructions]` delimiters.
-- **Soft delete by default.** `somtum forget <id>` marks observations deleted. `somtum purge --older-than 30d` permanently removes them.
-
----
-
-## Token Accounting
-
-Every `stats` figure is labelled _estimated_. Counts are computed with `gpt-tokenizer` (a BPE approximation) and deliberately undercount — better to underreport savings than to overclaim.
-
-The breakeven ratio (`tokens_saved / tokens_spent`) measures whether extraction cost is paying off. A ratio below 1.5× triggers a warning in `somtum stats` and `somtum doctor`.
-
-**A low ratio is normal on a fresh project** (< 20 memories, few recall calls). It improves as memories accumulate and get retrieved more frequently.
-
-If the ratio stays low after a few weeks, check for the hybrid/embeddings mismatch first (`somtum doctor`). If the config is correct, reduce injection scope: lower `injection.k` or `injection.max_chars` to cut overhead.
-
----
-
-## Performance
-
-| Scenario                                | p95 budget    | Actual (benchmark)       |
-| --------------------------------------- | ------------- | ------------------------ |
-| `UserPromptSubmit` hook at 1k memories  | 150 ms        | < 2 ms (BM25 k=8)        |
-| `UserPromptSubmit` hook at 10k memories | 300 ms        | < 30 ms (BM25 k=8)       |
-| Exact cache hash lookup                 | —             | < 0.1 ms                 |
-| `SessionEnd` hook (extract + embed)     | 90 s hard cap | Exits cleanly on timeout |
-
-Run benchmarks yourself:
-
-```bash
-pnpm test:bench
-```
-
----
+- Secrets matching `privacy.redact_patterns` (API keys, bearer tokens, AWS keys and similar) are redacted before anything is stored.
+- `.env` files and `secrets/` directories are never summarized.
+- Injected memories are wrapped in markers that tell the agent they are reference material, not instructions.
+- No telemetry. `somtum forget` soft-deletes; `somtum purge` removes for good.
 
 ## Development
 
 ```bash
+git clone https://github.com/riz007/somtum && cd somtum
 pnpm install
-pnpm typecheck        # strict TypeScript check
-pnpm test             # vitest unit + golden tests
-pnpm test:golden      # retrieval recall@k per strategy
-pnpm test:bench       # hot-path latency benchmarks
-pnpm lint             # eslint
-pnpm fmt              # prettier
-pnpm build            # tsc + copy migrations + copy dashboard → dist/
+pnpm test          # unit, integration and golden retrieval tests
+pnpm typecheck && pnpm lint
+pnpm build         # dist/, then `pnpm link --global` to try your build
 ```
 
-### Project layout
-
-```
-src/
-  cli/
-    index.ts          # commander CLI entry point
-    init.ts           # somtum init — installs hooks + MCP config
-    serve.ts          # somtum serve — local dashboard server
-    stats.ts          # somtum stats
-    doctor.ts         # somtum doctor — health checks
-    hook.ts           # internal: dispatches hook events by name
-    search.ts / show.ts / forget.ts / edit.ts
-    list.ts               # somtum list
-    reset.ts              # somtum reset — wipe project DB
-    export.ts / import.ts / purge.ts / sync.ts / rebuild.ts / reindex.ts
-    config_cmd.ts
-    suggest_claude_md.ts  # somtum suggest-claude-md
-  core/
-    db.ts             # SQLite setup, migration runner
-    store.ts          # MemoryStore — CRUD for observations
-    cache.ts          # PromptCache — exact + fuzzy lookup
-    retriever/        # bm25, embeddings, hybrid, index, factory
-    extractor.ts      # session transcript → observations
-    llm_backend.ts    # picks the extraction backend
-    index_gen.ts      # renders index.md (incremental past 1k obs)
-    memory_files.ts   # writes memories/<YYYY-MM>/<ulid>.md
-    retrieval_stats.ts
-    embeddings.ts     # Embedder interface + encode/decode utils
-    privacy.ts        # redact() — runs on every capture
-    tokens.ts         # gpt-tokenizer wrapper
-  hooks/
-    post_session.ts   # SessionEnd/PreCompact: extract → store → index → warm-start
-    pre_prompt.ts     # UserPromptSubmit: cache lookup + auto-inject + false-hit detection
-    pre_read.ts       # PreToolUse: file gating
-  mcp/               # MCP server + tool implementations
-  dashboard/
-    index.html        # single-page dashboard (served by somtum serve)
-  config.ts          # global + project config merge
-  index.ts           # public API for embedding Somtum
-src/db/migrations/   # NNN_name.sql migration files
-test/
-  golden/            # per-strategy retrieval golden sets
-  bench/             # hot-path latency benchmarks
-  fixtures/          # synthetic session transcripts
-```
-
-### Adding a new observation kind
-
-1. Extend the zod enum in `src/core/schema.ts`
-2. Update the extractor prompt in `src/core/extractor.ts`
-3. Add a fixture in `test/fixtures/` and an assertion
-4. Update `src/core/index_gen.ts` to render the new section
-
-### Adding a new MCP tool
-
-1. Define args + response with zod in `src/mcp/tools.ts`
-2. Register it in `src/mcp/server.ts`
-3. Response **must** include a `tokens` field
-4. Add an integration test in `src/mcp/server.test.ts`
+Where things live:
 
----
-
-## Troubleshooting
-
-### `somtum stats` shows `memories 0` after a session
-
-Check the hook log first:
-
-```bash
-cat ~/.somtum/hook.log
-```
-
-**No extraction backend**
-
-- Claude Code users: run `which claude`. Codex users: run `which codex`. If nothing prints, install the CLI or add it to your `PATH`.
-- API users: add `export ANTHROPIC_API_KEY="sk-ant-..."` to `~/.zshrc` and `source ~/.zshrc`. It must be in your profile, not just exported in the current terminal tab.
-
-Run `somtum doctor`: the `extraction_backend` check shows which backend will be used.
-
-**Hook not installed in the right directory**
-
-`somtum init` writes hooks into the directory where you ran it (`.claude/settings.json` or `.codex/hooks.json`). If you launch the agent from a different directory, it reads different settings.
-
-Fix: run `somtum init` from the same directory you launch the agent from.
-
-```bash
-cd ~/my-project
-somtum init
-claude   # must be launched from ~/my-project
-```
-
-**Short or trivial session**
-
-If the session had no decisions, bug fixes, or learnings (e.g. you just asked Claude to say hello), the extractor correctly returns 0 observations.
-
----
-
-### `somtum serve` opens the browser but shows "Connection refused"
-
-This was a bug fixed in v1.1.0. Upgrade:
-
-```bash
-npm install -g somtum@latest
-```
-
-If you installed from source, rebuild:
-
-```bash
-pnpm build
-```
-
----
-
-### `somtum serve` — port already in use
-
-```bash
-somtum serve --port 3001
-```
-
----
-
-### Agent appears to keep running after session ends
-
-The `SessionEnd` hook has a hard 90-second timeout. If sessions appear stuck, verify you are on v1.1.0+:
-
-```bash
-somtum --version
-tail -20 ~/.somtum/hook.log
-```
-
----
-
-### Installation fails (node-gyp / better-sqlite3)
-
-Ensure build tools are installed:
-
-- **macOS:** `xcode-select --install`
-- **Ubuntu/Debian:** `sudo apt-get install build-essential python3`
-- **Windows:** `npm install --global --production windows-build-tools`
-
----
-
-### Embeddings are slow or the model won't download
-
-The first `somtum reindex` downloads a ~30 MB ONNX model from Hugging Face. This requires internet access and may be slow. Subsequent runs use the cached model.
-
-On an air-gapped machine or if you prefer not to use embeddings:
-
-```bash
-somtum config set retrieval.embeddings.enabled false
-somtum config set retrieval.strategy bm25
-```
-
-BM25 works fully offline and is fast at any corpus size.
-
----
-
-### Claude doesn't seem to have context from previous sessions
-
-**Auto-inject is the first thing to check.** Since v1.3.0, Somtum automatically injects top-k memories into every `UserPromptSubmit` via the cache hook — no manual recall step needed.
-
-1. Confirm the cache hook is installed: `somtum doctor` → look for `hooks_installed ✓`
-2. If not installed: `somtum init --cache` (or `somtum init --all`)
-3. Confirm injection is enabled: `somtum config get injection.enabled` → should be `true`
-4. Check that memories actually exist: `somtum stats` → `memories > 0`
-
-**Using the MCP server** (`somtum init --all`), Claude can also call `recall` directly when uncertain. If it's not happening:
-
-1. Confirm `.mcp.json` exists: `cat .mcp.json`
-2. Restart Claude Code to pick up the MCP config
-
-### Stale memory warning in `somtum doctor`
-
-`doctor` warns when memories are older than 90 days with no confirmed retrievals. These are observations that have never come up in a search. Options:
-
-```bash
-# Review them before deciding
-somtum search "old topic"
-
-# Promote useful ones to workspace scope via MCP
-remember("...", scope="workspace")
-
-# Remove irrelevant ones
-somtum purge --older-than 90d
-```
-
----
-
-### Starting fresh — wiping all memories
-
-To hard-reset a project's memory (irreversible):
-
-```bash
-somtum reset
-# Permanently delete all memories for this project? [y/N] y
-# somtum: reset complete — project <id> wiped.
-```
-
-To just clear everything softly (recoverable via `somtum export --include-deleted`):
-
-```bash
-somtum forget --all
-```
-
----
-
-## Contributing
-
-Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for the guide.
-
-**Important:** This project uses `changesets` for versioning. Every PR must include a changeset file generated by running `pnpm changeset`.
+| Path | What |
+| --- | --- |
+| `src/hooks/` | The three hook handlers: `post_session` (capture), `pre_prompt` (recall), `pre_read` (file gating) |
+| `src/core/` | Store, retrieval, extraction, token ledger, transcript parsing |
+| `src/agents/` | One adapter per agent transcript format. Add an agent here |
+| `src/cli/` | One file per command |
+| `src/db/migrations/` | Numbered, additive SQL migrations |
 
----
+Two rules for changes: a hook must never break or block the agent's session, and any new token spend must be bounded and recorded in the ledger. Every PR needs a changeset (`pnpm changeset`). See [CONTRIBUTING.md](CONTRIBUTING.md) and [SPEC.md](SPEC.md) for what's planned.
 
 ## License
 
-Licensed under the [MIT License](LICENSE).
+[MIT](LICENSE)