sessionmem 1.3.0 → 1.5.0

package/README.md

@@ -9,7 +9,7 @@
   <a href="https://github.com/catfish-1234/sessionmem/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
 </p>
 
-**85.6% fewer tokens. Every session starts knowing your codebase. Stored entirely on your machine.**
+**Project memory between sessions, stored on your machine.**
 
 ```
 New session. Claude starts fresh.
@@ -27,15 +27,15 @@ WITH sessionmem:
   Claude: "Looks like you're mid-Stripe migration. Where do you want to pick up?"
 ```
 
-`sessionmem` is an MCP server that watches your coding sessions and stores what actually mattered -- decisions, warnings, things that would bite you if Claude forgot them. At the start of each new session it injects the relevant bits automatically. Works with Claude Code, Cursor, Cline, Codex, Windsurf, and anything that speaks [MCP](https://modelcontextprotocol.io).
+`sessionmem` is an MCP server that stores decisions, warnings, and project context across sessions. Claude Code hooks capture supported tool events and load relevant memories automatically. Other hosts use its MCP tools and installed instructions; session automation depends on the host. It works with Claude Code, Cursor, Cline, Codex, Windsurf, and other [MCP](https://modelcontextprotocol.io) hosts.
 
-Everything stays on your machine. No account, no cloud, no data leaving your computer unless you explicitly turn that on.
+By default, everything stays on your machine. You don't need an account or a cloud service. Data only leaves your computer if you enable sharing or cloud summarization.
 
 ---
 
 ## Quickstart
 
-No programming experience needed. You just need a terminal (Command Prompt, Terminal, or PowerShell) and [Node.js](https://nodejs.org) installed.
+You need a terminal (Command Prompt, Terminal, or PowerShell) and [Node.js](https://nodejs.org), version 20.19+ on the Node 20 line, or 22.13+. Node 22 LTS is recommended. No programming experience is required.
 
 ### 1. Install sessionmem
 
@@ -45,34 +45,49 @@ npm install -g sessionmem
 
 ### 2. Register it with your AI tool
 
-Run this inside the project folder you're working on, with your AI tool (Claude Code, Cursor, etc.) configured:
+Run this in your project folder after configuring your AI tool (Claude Code, Cursor, etc.):
 
 ```bash
 sessionmem install
+# Optional: select one host explicitly, including in automation:
+sessionmem install --adapter claude-code
+# Other names: cursor, cline, codex, windsurf, antigravity, qcoder, generic
 ```
 
-This does three things:
-- Tells your AI tool's MCP host about `sessionmem` so it can be launched automatically.
-- Creates a config file at `~/.sessionmem/config.json` with safe, privacy-respecting defaults, but only if one doesn't already exist.
-- Injects instructions into `~/.claude/CLAUDE.md` so Claude Code knows about sessionmem's tools and uses them proactively (idempotent, so safe to re-run).
+`install` detects installed hosts from local executables, including from a plain
+terminal, and configures every host found. Automatic discovery currently supports
+Claude Code on `PATH` or in its standard native install locations. Use
+`--adapter <name>` for the other adapters or to override discovery. The existing
+`SESSIONMEM_ADAPTER` environment override also works; the flag takes precedence.
+If no supported host is found, the command says so and exits nonzero before
+creating files. Discovery and configuration work fully offline.
 
-### 3. Start using your AI tool as normal
+This initializes the database and, for each selected adapter:
 
-```bash
-sessionmem run
-```
+- Registers `sessionmem` with your AI tool's MCP host so the host can start it automatically.
+- Creates `~/.sessionmem/config.json` with secret redaction enabled and a 90-day retention window, if the file doesn't already exist.
+- Adds instructions to the selected host's guidance file, such as `~/.claude/CLAUDE.md` for Claude Code or `~/.codex/AGENTS.md` for Codex. You can re-run the command without duplicating those instructions.
+- Installs Claude Code's SessionStart, SessionEnd, and PostToolUse hooks and prints what was configured per host. If a host fails, the remaining hosts are still attempted and the command exits nonzero.
+
+### 3. Restart your AI tool
+
+Restart your editor or agent so it loads the MCP registration. Your host starts
+`sessionmem run` automatically; running it directly starts a stdio server that
+waits for MCP messages, so it can appear to hang in a terminal. For an unknown
+host (`generic`), install writes a project-local `.mcp.json`; if your host uses
+another format or location, copy its server entry into that host’s MCP config.
 
-(Most of the time you won't run this yourself. Your AI tool's host starts it automatically once it's registered.)
+After restarting:
 
-That's it. From here:
-- `sessionmem` watches your sessions in the background.
-- At the end of each session, it writes down a short summary of what mattered.
-- At the start of your next session, it quietly reminds your assistant of the relevant bits.
+- In Claude Code, the installed PostToolUse, SessionEnd, and SessionStart hooks capture supported tool events, summarize them, and load prior memories automatically.
+- Other MCP hosts use sessionmem's tools and installed instructions. Automatic capture and session lifecycle calls depend on the host or agent. MCP registration alone does not install Claude Code hooks there.
 
-You can verify everything is working with:
+Check the installation offline:
 
 ```bash
-sessionmem ping
+sessionmem doctor
+# For an explicitly selected host:
+sessionmem doctor --adapter claude-code
 ```
 
 ---
@@ -92,6 +107,7 @@ sessionmem ping
 - [Further documentation](#further-documentation)
 - [Troubleshooting](#troubleshooting)
 - [FAQ](#faq)
+- [Security](#security)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -99,73 +115,56 @@ sessionmem ping
 
 ## What problem does this solve?
 
-If you've used an AI coding assistant for more than a day, you've probably hit this:
+Most AI coding assistants rely on the current conversation for context. Start a new session and you may need to explain the project's setup, libraries, fixed bugs, and design decisions again.
 
-> You spend twenty minutes explaining your project's setup, the libraries you use, a tricky bug you already fixed, and a decision you made about how authentication should work. The assistant nods along, helps you out... and then in your **next session**, it has forgotten all of it. You explain everything again.
+`sessionmem` keeps short notes between sessions:
 
-This happens because most AI assistants only "know" what's inside the current conversation. Once that conversation ends, the context is gone.
+1. While you work, it captures session events.
+2. At session end, it summarizes decisions, warnings, and useful facts into stored memories.
+3. At the next session start, it loads the most relevant memories within a small token budget.
 
-`sessionmem` fixes this by sitting quietly between your assistant and your project:
-
-1. While you work, it **captures** what happens in the session.
-2. When the session ends, it **summarizes** the important parts (decisions made, warnings, useful facts) into short, durable notes.
-3. The next time you start a session, it **reminds** the assistant of the most relevant notes, automatically, in a small amount of text.
-
-You don't run any of these steps yourself. Once installed, it just works in the background.
+Claude Code runs these steps through the installed hooks. Other hosts need their
+agent to call the MCP memory and lifecycle tools; the installed guidance explains
+how to do that.
 
 ---
 
 ## How is sessionmem different?
 
-There are other "memory for Claude" projects out there (for example, tools like *claude-mem* and similar community projects). Here's what sets `sessionmem` apart:
+Compared with projects such as *claude-mem* and other cloud or Claude-only memory tools, `sessionmem` focuses on local storage and support for multiple MCP hosts:
 
 | | **sessionmem** | Typical cloud/Claude-only memory tools |
 |---|---|---|
 | **Where is data stored?** | A single SQLite file on your computer (`~/.sessionmem/memories.db`) | Often a hosted service, a cloud vector database, or a separate server process you have to run |
-| **Account / sign-up required?** | No, never | Sometimes |
+| **Account / sign-up required?** | No | Sometimes |
 | **Which AI tools does it work with?** | Claude Code, Cursor, Codex, Cline, Windsurf, Antigravity, QCoder, and any other MCP-compatible host | Usually just one specific tool (commonly Claude Code only) |
 | **Secret redaction** | Built in, on by default. API keys, tokens, passwords, and private keys are scrubbed before anything is saved. | Often not handled, or left to the user |
-| **Token budget control** | Injected memories are trimmed to a small, fixed token budget so they don't bloat every conversation (see benchmarks below) | Varies, often unbounded |
-| **Old/stale memory cleanup** | Built-in retention policy automatically prunes old memories (configurable, on by default) | Often grows forever ("memory rot") |
+| **Token budget control** | Injected memories are trimmed to a small, fixed token budget (see benchmarks below) | Varies, often unbounded |
+| **Old/stale memory cleanup** | Built-in retention policy automatically prunes old memories (configurable, on by default) | Often no automatic cleanup ("memory rot") |
 | **Team sharing** | Optional, via a shared folder you already control (network drive, synced directory). No server needed. | Usually requires a shared hosted backend |
-| **Offline-capable** | Yes, fully. Works with no network connection by default. | Usually requires network access to the memory service |
+| **Offline-capable** | Yes. Works with no network connection by default. | Usually requires network access to the memory service |
 
-In short: `sessionmem` is the **boring, local, "just a SQLite file" option**: easy to inspect, back up, and delete, with no lock-in to any one vendor's AI tool.
+The SQLite file is easy to inspect, back up, or delete, and you can use it across AI tools from different vendors.
 
 ---
 
 ## Benchmark results
 
-These numbers come from `npm run benchmark` (`scripts/benchmark.mjs`), which runs the real production retrieval and injection code over a fixed, synthetic set of test data with no network calls. The results are fully reproducible. See [`docs/benchmark.md`](docs/benchmark.md) for the full report and how to regenerate it.
-
-### Token savings
-
-> **~85.6% reduction** in tokens compared to carrying full session history.
-
-| | Tokens |
-|---|---|
-| Full session history (baseline) | 1,587 |
-| What sessionmem injects at the start of your next session | 228 |
-
-In practice: instead of re-reading (or re-explaining) about 1,600 tokens of past context every session, the assistant gets a 230-token summary of just the things that matter: decisions, warnings, and key facts.
-
-### Retrieval accuracy
-
-> **100% hit-rate**: every one of the 10 test queries successfully retrieved the memory it was supposed to.
-
-| Metric | Result |
-|---|---|
-| Hit-rate (10 curated queries) | 100.0% |
-| Recall | 100.0% |
-| Precision | 33.3% |
+`npm run benchmark` evaluates conversational retrieval on the committed LoCoMo
+corpus: 10 conversations, 272 sessions, 5,882 turns, and 1,527 scored questions.
+It captures dialogue through the public `storeMemory` API and asks the original
+questions through `retrieveMemories`, fully offline with no API keys.
 
-Precision of 33.3% is expected here: each query retrieves the top 3 candidate memories, and only one of those three is the "expected" match for a given test query. The other two are still relevant context for the agent, just not the one being scored. The important number is recall/hit-rate: **the right memory is never missed.**
-
-These benchmarks are deterministic and reproducible. Run them yourself:
+The evaluation reports hit rate, precision, recall, complete-evidence retrieval,
+and latency. Production retrieval uses offline BM25 ranking with English stemming;
+conversational questions test recall beyond exact copies of memory text.
+See [benchmark results](docs/benchmark.md) and the
+[methodology, dataset license, and metric definitions](benchmarks/README.md).
 
 ```bash
-npm run build      # benchmark imports the compiled code from dist/
-npm run benchmark  # regenerates docs/benchmark.md
+npm run build
+npm run benchmark
+npm run benchmark -- --output benchmarks/results/locomo.json
 ```
 
 ---
@@ -198,11 +197,11 @@ npm run benchmark  # regenerates docs/benchmark.md
                      └──────────────────────────────────────────────┘
 ```
 
-- **Adapters** are small pieces that know how to talk to each specific AI tool. This is why sessionmem can support many tools: adding a new one doesn't change how memory itself works.
-- **The core engine** is the same no matter which tool you use. It decides what's worth remembering, how relevant it is later, and how much of it fits in a small "reminder" at the start of your next session.
-- **The database** is just a file. You can back it up, move it, inspect it, or delete it like any other file on your computer.
+- **Adapters** connect each AI tool to sessionmem. Supporting another tool doesn't require changing the memory engine.
+- **The core engine** stores memories, ranks their relevance, and selects what fits in the next session's context budget. Every adapter uses the same engine.
+- **The database** is a local file. You can back it up, move it, inspect it, or delete it.
 
-For a deeper technical dive, see [`docs/architecture.md`](docs/architecture.md).
+See [`docs/architecture.md`](docs/architecture.md) for the technical overview.
 
 ---
 
@@ -210,33 +209,194 @@ For a deeper technical dive, see [`docs/architecture.md`](docs/architecture.md).
 
 | Command | What it does |
 |---------|--------------|
-| `sessionmem install` | Register sessionmem with the current MCP host and write default config. |
-| `sessionmem uninstall [--purge]` | Remove sessionmem from the host. `--purge` also deletes the local database. |
+| `sessionmem install [--adapter <name>]` | Detect installed hosts, register sessionmem with each, and write default config; the flag selects one host. |
+| `sessionmem doctor [--adapter <name>]` | Check the store, schema, hooks, MCP wiring, and canary recall offline; print PASS/FAIL and repair hints. |
+| `sessionmem uninstall [--adapter <name>] [--purge]` | Remove sessionmem from the host. `--purge` also deletes the local database. |
 | `sessionmem run` | Start the MCP server. |
-| `sessionmem ping` | Check server connectivity. |
-| `sessionmem search <query> [--limit <n>]` | Search memories by semantic query. |
-| `sessionmem list` | List all memories for the current project. |
-| `sessionmem show <id>` | Show full details of a memory. |
+| `sessionmem ui [--port N]` | Open the local read-only web viewer (default port 3777). |
+| `sessionmem ping` | Check the local version and database reachability. |
+| `sessionmem search <query> [--limit <n>] [--include-history]` | Search current memories by text query (limit 1–100, default 10). Include superseded facts with `--include-history`. |
+| `sessionmem list` | List up to 200 recent memories for the current project; warns when truncated. |
+| `sessionmem entities [--project <id>] [--json]` | List extracted entities, typed relations, and their source memory IDs. Defaults to the current project. |
+| `sessionmem history [--project <id>] [--json]` | List supersession chains with old/new values, source memory IDs, reasons, and timestamps. |
+| `sessionmem show <id>` | Show memory details (content capped at 2000 characters; use export for full content). |
 | `sessionmem forget <id> [--force]` | Delete a memory by ID. |
-| `sessionmem export [path]` | Export memories to a JSON file. |
-| `sessionmem import <path> [--merge]` | Import memories from a JSON file. |
+| `sessionmem export [path]` | Export all current-project memories to JSON (default `~/.sessionmem/export-YYYY-MM-DD.json`). |
+| `sessionmem import <path> [--merge]` | Import up to 1000 valid records from UTF-8 JSON into the current project. Existing IDs are preserved, including with `--merge`; invalid records are skipped with warnings. |
+| `sessionmem scan [--transcripts-dir <path>]` | Import existing Claude Code JSONL transcripts into local session memories. Reports files found, sessions imported, memories created, skipped files, and errors. |
+| `sessionmem watch [--once] [--interval <seconds>] [--transcripts-dir <path>]` | Capture new or updated Claude Code transcripts. Polls every 5 seconds by default; `--once` runs a single sweep. |
 | `sessionmem stats` | Show memory statistics for the current project. |
 | `sessionmem savings [--json]` | Show token savings from compression and injection, with percentage. |
 | `sessionmem redact-scan [--apply]` | Scan stored memories for secrets; `--apply` redacts in place. |
 | `sessionmem retention prune [--force] [--days <n>]` | Prune old memories (dry-run by default). |
 | `sessionmem config get <key>` / `config set <key> <value>` | Read and write policy config. |
-| `sessionmem team enable <path>` / `team disable` / `team status` | Manage shared-path team memory mode. |
+| `sessionmem team enable <path>` / `team disable [--remove-team-memories]` / `team status` | Manage shared-path team memory mode. |
 | `sessionmem sync` | Push local memories and pull teammate memories via the shared path. |
+| `sessionmem browse [--project <id>]` | List projects or preview up to 50 recent memories from one project. |
+| `sessionmem dedupe [--apply] [--threshold <n>]` | Preview duplicate memories; `--apply` deletes them (threshold >0–1, default 0.85). |
+| `sessionmem re-embed` | Refresh memories with stale embedding versions. |
+| `sessionmem session-start` | Print prior context as Claude Code SessionStart hook JSON. |
+| `sessionmem ingest-hook` | Read a Claude Code PostToolUse JSON payload from stdin and capture supported tool events. |
+| `sessionmem session-end` | Summarize ingested events and apply retention pruning; reads the hook session ID from stdin. |
+
+Use `sessionmem --help` or `sessionmem <command> --help` for options, and
+`sessionmem --version` for the installed version. Destructive commands require
+`--force`, `--apply`, or `--purge` as shown above. `team disable` preserves
+teammate memories unless `--remove-team-memories` is passed.
+
+The default database is `~/.sessionmem/memories.db`. Set `SESSIONMEM_DB_PATH`
+to use another file; its parent directories are created automatically and the
+default directory is not created by database commands. Server logs are written
+to `logs/mcp.log` beside the selected database (disabled for `:memory:`). Config remains at
+`~/.sessionmem/config.json`. `uninstall --purge` deletes the selected database.
+Quote paths containing spaces (for example `"C:\Users\Ada Lovelace\memory.db"`
+on Windows). In JSON config files, use forward slashes or escaped backslashes
+for Windows paths. Imports accept CRLF and a UTF-8 BOM; convert other encodings to UTF-8.
+
+`SESSIONMEM_PROJECT_ID` pins the project bucket (useful when moving a repository);
+otherwise it is derived from the repository root or working directory.
+`SESSIONMEM_ADAPTER` selects the install/doctor/uninstall host unless `--adapter` is set.
+`SESSIONMEM_DEBUG=1` enables ingest-hook diagnostics on stderr.
+
+### Inspect memories in your browser
+
+```bash
+sessionmem ui
+sessionmem ui --port 8080
+sessionmem ui --port 0  # Pick an available port
+```
+
+The command prints its URL and opens your default browser. It binds only to
+`127.0.0.1`, needs no authentication, and serves all assets locally using Node's
+built-in HTTP server. No external services, CDNs, or additional runtime dependencies
+are used. If browser launch is unavailable, open the printed URL manually. Press
+Ctrl-C to stop the server and close its database connection.
+
+The viewer starts on the current project, with a selector for other projects in
+the same store. Browse saved memories, search through the existing recall path,
+inspect extracted entities and relations with their source memories, and follow
+supersession chains with old/new values, source IDs, assertion times, detection
+times, and partial/full status. Search returns up to 50 results and defaults to
+current facts; select **Include superseded facts in search** to recall history.
+Browsing lists all saved records, including superseded and expired ones, in pages
+of 50. Source IDs open full memory details. Entity visibility and history links
+use the same rules as `sessionmem entities` and `sessionmem history`.
+
+The database is opened read-only. Browsing and on-demand search do not increment
+access counts, migrate the schema, or change memories. Only HTTP GET and HEAD are
+accepted; no write, delete, or edit routes are exposed. Responses are not cached,
+and cross-origin browser requests and unexpected Host headers are rejected. Run
+`sessionmem ping` first to initialize a missing store or upgrade an older schema.
+The usual `SESSIONMEM_DB_PATH` and `SESSIONMEM_PROJECT_ID` overrides
+apply. Anyone with access to this computer can read the local viewer while it is
+running; stop it when finished inspecting private memories.
+
+### Import existing sessions and watch for new ones
+
+When a fact changes, sessionmem can link its replacement locally. For example, “I use VS Code” followed by “I switched to Neovim” supersedes the earlier editor choice. Recall excludes fully superseded memories by default. `retrieveMemories` accepts the optional `includeHistory: true`; `sessionmem search --include-history` searches earlier facts too. `sessionmem history` shows what replaced what. The old memory stays available through show, list, and export.
+
+Detection uses deterministic entity/relation rules, shared purpose words, a small tool-category vocabulary, and explicit negation or replacement phrases. It needs no API or model. Unfamiliar wording can be missed, and ambiguous changes can be misclassified. A memory with independent claims remains searchable while any claim is current; history labels these partial supersessions. See [supersession details](docs/architecture.md#contradiction-and-supersession).
+
+Run a scan to capture Claude Code sessions from before sessionmem was installed:
+
+```bash
+sessionmem scan
+sessionmem watch --once
+sessionmem watch --interval 10
+```
+
+Both commands recursively read `~/.claude/projects/**/*.jsonl`. Use
+`--transcripts-dir "/path/to/projects"` to select another transcript tree. They
+work fully offline without API keys and always use the local summarizer, even
+if cloud summarization is enabled elsewhere.
+
+Transcript user/assistant text and supported tool uses (Bash, Edit, Write,
+MultiEdit) pass through the existing event-ingestion, redaction, and session-summary
+pipeline. Each session gets one summary memory, including short sessions with
+only one event. Updated sessions refresh that summary. Project buckets come from
+each transcript's `cwd`, using its repository root when available; the directory
+where you run scan/watch does not select the project. `SESSIONMEM_PROJECT_ID`
+can explicitly pin all imports to one bucket. Transcripts without a working
+directory or capturable events are skipped; nested subagent files get separate
+session summaries.
+
+Re-running either command does not duplicate memories or transcript events.
+File checkpoints live in the selected memory database, and unchanged files are
+skipped across restarts. Stable event IDs also make interrupted imports safe to
+retry. Partial or malformed JSONL lines are reported and retried on later sweeps;
+valid events in the same file can still be captured. A single sweep exits with
+status 1 if it encounters errors. The daemon keeps running and retries errors.
+
+`watch` prints its first sweep and subsequent imports or errors. It runs in the
+foreground until SIGINT or SIGTERM. For a background process:
+
+```bash
+nohup sessionmem watch > sessionmem-watch.log 2>&1 &
+```
+
+For macOS launchd, save this as
+`~/Library/LaunchAgents/io.sessionmem.watch.plist`. Replace the executable path
+with the output of `command -v sessionmem`, and adjust PATH for your Node install:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>io.sessionmem.watch</string>
+  <key>ProgramArguments</key>
+  <array><string>/opt/homebrew/bin/sessionmem</string><string>watch</string></array>
+  <key>EnvironmentVariables</key>
+  <dict><key>PATH</key><string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string></dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+</dict>
+</plist>
+```
+
+```bash
+launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/io.sessionmem.watch.plist
+# Stop and unload:
+launchctl bootout "gui/$(id -u)/io.sessionmem.watch"
+```
+
+For a Linux systemd user service, save this as
+`~/.config/systemd/user/sessionmem-watch.service`. Replace the executable path
+and adjust PATH for your Node install:
+
+```ini
+[Unit]
+Description=Capture Claude Code transcripts with sessionmem
+
+[Service]
+ExecStart=/usr/local/bin/sessionmem watch
+Environment=PATH=/usr/local/bin:/usr/bin:/bin
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+```
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now sessionmem-watch.service
+journalctl --user -u sessionmem-watch.service -f
+# Stop and disable:
+systemctl --user disable --now sessionmem-watch.service
+```
+
+These are optional examples; `sessionmem install` does not register a daemon.
 
 ---
 
 ## Privacy, secrets, and your data
 
-**Everything stays on your machine by default.** No account, no telemetry, no hosted memory service. Storage, retrieval, and summarization all run locally, governed by `~/.sessionmem/config.json`.
+Storage, retrieval, and summarization run locally by default. There is no account, telemetry, or hosted memory service. Settings live in `~/.sessionmem/config.json`.
 
 ### Secrets are scrubbed automatically
 
-Before anything is saved, `sessionmem` automatically removes common secret patterns and replaces them with `REDACTED`:
+Before saving memory content, `sessionmem` replaces common secret patterns with `REDACTED`:
 
 - Email addresses
 - API keys (`sk-...`, AWS `AKIA...`, GitHub `ghp_...`/`gho_...`, etc.)
@@ -244,7 +404,7 @@ Before anything is saved, `sessionmem` automatically removes common secret patte
 - Private key blocks (`-----BEGIN ... PRIVATE KEY-----`)
 - Connection-string style secrets (`password=...`, `secret=...`)
 
-This is **on by default**. You can scan and clean up older memories at any time:
+Redaction is on by default. To scan and clean up older memories:
 
 ```bash
 sessionmem redact-scan          # see what would be redacted
@@ -257,26 +417,26 @@ Full details: [`docs/privacy-and-retention.md`](docs/privacy-and-retention.md).
 
 ## Memory rot: keeping memory accurate over time
 
-"Memory rot" is what happens when a memory system keeps accumulating notes forever. Eventually it fills up with outdated decisions, duplicate facts, and noise, and the assistant starts surfacing stale information instead of helpful information.
+Old decisions and duplicate facts can accumulate in a memory store, causing the assistant to use outdated information. This is sometimes called "memory rot."
 
-`sessionmem` is designed to avoid this in a few ways:
+`sessionmem` handles it through retention, ranking, and sync rules:
 
-1. **Retention pruning**: memories older than a configurable window (default 90 days) are automatically eligible for cleanup. This runs as a light check at the end of every session, and can also be run manually:
+1. **Retention pruning**: memories older than a configurable window (90 days by default) are eligible for deletion. A lightweight check runs at session end. You can also run it manually:
 
    ```bash
    sessionmem retention prune          # dry run - shows what *would* be deleted
    sessionmem retention prune --force  # actually deletes
    ```
 
-2. **Importance-weighted ranking**: when memories are retrieved, they're ranked by a blend of semantic relevance, recency, and importance. Old, low-importance notes naturally sink to the bottom and stop being surfaced even before they're pruned.
+2. **Importance-weighted ranking**: retrieval ranks memories by offline BM25 lexical relevance, entity overlap, recency, and importance. Older, less important notes rank lower even before they are pruned.
 
-3. **Token-budgeted injection**: only the top-ranked, most relevant memories are injected (trimmed to a small token budget, see [benchmarks](#benchmark-results)), so even a large memory store doesn't produce bloated, noisy context.
+3. **Token-budgeted injection**: only the highest-ranked memories are loaded, trimmed to a small token budget (see [benchmarks](#benchmark-results)). The context stays within that budget as the store grows.
 
-4. **Conflict resolution in team mode**: when memories are merged from teammates, the system uses last-write-wins by id (so stale duplicates don't pile up) while preserving the higher importance score (so a critical warning doesn't get silently downgraded).
+4. **Conflict resolution in team mode**: merging teammate memories uses last-write-wins by id to avoid stale duplicates and keeps the higher importance score so a warning isn't downgraded.
 
-The retrieval benchmark above (100% hit-rate / 100% recall) demonstrates that even with the ranking and trimming in place, the right memory still surfaces. Accuracy is not traded away for compactness.
+The [conversational benchmark](benchmarks/README.md) measures retrieval quality separately from retention and startup token budgets.
 
-You're always in control: export everything first if you want a permanent record before pruning:
+Export your memories before pruning if you want to keep a copy:
 
 ```bash
 sessionmem export
@@ -286,17 +446,17 @@ sessionmem export
 
 ## Team mode (optional)
 
-Want your whole team's AI assistants to share decisions and warnings? Point `sessionmem` at a shared folder (a network drive, a synced directory, or any location everyone can read and write):
+To share decisions and warnings across your team's AI assistants, point `sessionmem` at a folder everyone can read and write, such as a network drive or synced directory:
 
 ```bash
 sessionmem team enable <shared-path>
 sessionmem sync
 ```
 
-- **Off by default**: nothing is shared until you turn it on.
-- No server needed. It's just files in a folder you already control.
-- Teammates' memories show up with an `author:` prefix so you know where they came from.
-- Secrets are re-redacted on every pulled memory, so a teammate's snapshot can't reintroduce something your redaction policy would have stripped.
+- Team mode is off by default. Nothing is shared until you enable it.
+- Memories are shared as files in that folder; no server is needed.
+- Teammate memories appear with an `author:` prefix identifying their source.
+- Redaction runs on every pulled memory using your redaction policy.
 
 Full details, including the trust model: [`docs/team-mode.md`](docs/team-mode.md).
 
@@ -304,9 +464,9 @@ Full details, including the trust model: [`docs/team-mode.md`](docs/team-mode.md
 
 ## Cloud summarization (optional, off by default)
 
-By default, summarization (turning a session into a short memory) happens entirely locally, with no API calls.
+By default, session summaries are created locally, with no API calls.
 
-If you explicitly opt in (`allowCloudSummarization=true`) and provide an `ANTHROPIC_API_KEY`, summarization can use Claude's API for higher-quality summaries. If that ever fails, it automatically falls back to local summarization. Your sessions are never left unsummarized.
+To use Claude's API for higher-quality summaries, set `allowCloudSummarization=true` and provide an `ANTHROPIC_API_KEY`. If cloud summarization fails after retries, sessionmem uses local summarization. Failures are recorded for diagnosis; see the configuration guide below.
 
 Details: [`docs/cloud-summarization.md`](docs/cloud-summarization.md).
 
@@ -324,14 +484,14 @@ Details: [`docs/cloud-summarization.md`](docs/cloud-summarization.md).
 - Antigravity
 - QCoder
 
-...and any other tool that implements the [Model Context Protocol](https://modelcontextprotocol.io).
+Other tools that implement the [Model Context Protocol](https://modelcontextprotocol.io) can connect too.
 
 ---
 
 ## Further documentation
 
 - [Architecture](docs/architecture.md): how the core engine, adapters, CLI, and SQLite storage fit together.
-- [Benchmark](docs/benchmark.md): full token-reduction and retrieval-accuracy report, and how to reproduce it.
+- [Benchmark](docs/benchmark.md): conversational retrieval results and reproduction steps.
 - [Privacy and retention](docs/privacy-and-retention.md): secret redaction, retention pruning, and config.
 - [Team mode](docs/team-mode.md): shared-path team memory.
 - [Cloud summarization](docs/cloud-summarization.md): the opt-in cloud summarization path.
@@ -342,21 +502,34 @@ Details: [`docs/cloud-summarization.md`](docs/cloud-summarization.md).
 
 ## Troubleshooting
 
-Run into trouble installing or running `sessionmem`? Start with [`docs/troubleshooting.md`](docs/troubleshooting.md). It covers install failures, adapter-specific issues, missing session data, and native module (`better-sqlite3`) build problems on different platforms.
+For install failures, adapter issues, missing session data, or `better-sqlite3` native-build problems, see [`docs/troubleshooting.md`](docs/troubleshooting.md).
 
-Two quick checks that resolve most reports:
+Start with offline diagnostics:
 
 ```bash
-sessionmem install   # idempotent — re-registers the MCP server and all three hooks
-sessionmem stats     # memories, sessions, and session_events for the current project
+sessionmem doctor
+sessionmem doctor --adapter claude-code  # explicit host override
 ```
 
+`doctor` reports a separate PASS or FAIL for the memory store, schema, hook
+definitions shipped with the current version, configured MCP command, and a
+canary write/recall. It exits nonzero if any check fails and prints fix hints,
+including exact commands for safe repairs. It does not create a missing store or
+apply migrations. Its temporary canary is isolated from your projects and rolled
+back even on failure. The MCP check starts the installed local command and verifies
+its version, tools, and a stats response; it does not require a running agent.
+
+Use `sessionmem ping` to initialize a missing store or apply pending schema
+migrations, or `sessionmem install --adapter claude-code` to refresh Claude Code's
+MCP registration and hooks. Run repairs with the same `SESSIONMEM_DB_PATH` as
+doctor when using a custom store.
+
 If `stats` shows `sessions: 0` after real work, see [“0 sessions” / no session data recorded](docs/troubleshooting.md#0-sessions--no-session-data-recorded). Memories are keyed to the **repository root**, so every directory inside one repo shares a bucket; outside a repo the working directory itself is the key.
 
-Quick checks:
+To check database access and memory counts:
 
 ```bash
-sessionmem ping     # is the server reachable?
+sessionmem ping     # can the local database be opened?
 sessionmem stats    # is data being stored?
 ```
 
@@ -365,16 +538,16 @@ sessionmem stats    # is data being stored?
 ## FAQ
 
 **How do I give Cursor, Cline, or Windsurf memory between sessions?**
-Install sessionmem (`npm i -g sessionmem`), then run `sessionmem install` in your project. It registers as an MCP server with any supported host automatically.
+Install sessionmem (`npm i -g sessionmem`), then run `sessionmem install` in your project. Use `--adapter cursor`, `--adapter cline`, or `--adapter windsurf` when auto-detection cannot identify your host.
 
 **How do I give Claude Code persistent memory?**
-Same install. sessionmem also ships as a Claude Code plugin (the `.claude-plugin` file in the repo), so it works with Claude Code's native plugin system too.
+Use the same install steps above. sessionmem also ships as a Claude Code plugin (the `.claude-plugin` directory in the repo) for Claude Code's native plugin system.
 
 **Is there a local MCP memory server that works offline with no API key?**
-Yes. sessionmem stores everything in a single SQLite file at `~/.sessionmem/memories.db` and works fully offline by default. Nothing leaves your machine unless you explicitly enable the optional cloud summarization path.
+Yes. sessionmem stores memories in a single SQLite file at `~/.sessionmem/memories.db` and works offline by default. Sharing and cloud summarization are optional and off by default.
 
 **How is sessionmem different from claude-mem?**
-sessionmem is not Claude-only. It works with Cursor, Cline, Codex, Windsurf, Antigravity, QCoder, and any other MCP host, not just Claude Code. It also redacts secrets (API keys, tokens, JWTs) by default, prunes stale memory automatically, and ships reproducible benchmarks you can run yourself.
+sessionmem works with Claude Code, Cursor, Cline, Codex, Windsurf, Antigravity, QCoder, and other MCP hosts. It redacts secrets (API keys, tokens, JWTs) by default, prunes old memories automatically, and includes reproducible benchmarks.
 
 **Does sessionmem send my code to the cloud?**
 No. Nothing leaves your machine by default. The optional cloud summarization path is opt-in and off by default.
@@ -384,18 +557,29 @@ Run `sessionmem savings` to see a breakdown of storage compression (raw session
 
 ---
 
+## Security
+
+See the [security policy](SECURITY.md) for supported versions, private vulnerability
+reporting through GitHub security advisories, and response expectations.
+
+---
+
 ## Contributing
 
 Issues and pull requests are welcome. The codebase is TypeScript, tested with [Vitest](https://vitest.dev), and linted with ESLint:
 
 ```bash
-npm install
+npm ci
 npm run build
+npm run typecheck
 npm test
 npm run lint
 ```
 
-**MCP config for local development:** Copy `.mcp.json.example` to `.mcp.json` for local dev, or use `sessionmem install` to auto-configure. The `.mcp.json` file is gitignored because it contains machine-specific paths.
+**MCP config for local development:** Clone the repository, build it, copy
+`.mcp.json.example` to `.mcp.json`, and replace the example path with the absolute
+path to your checkout’s `dist/cli/index.js`. This runs your local build.
+`sessionmem install` registers the `sessionmem` executable on PATH instead. The `.mcp.json` file is gitignored because it contains machine-specific paths.
 
 ---