sessionmem 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -5,6 +5,59 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.0] - 2026-10-18
+
+### Added
+
+- Multi-host transcript imports: `sessionmem scan` and `sessionmem watch` now
+  sweep Claude Code, Codex CLI, and Cursor histories by default, with a
+  separate parser per host and an explicit unsupported-format error when a
+  claimed host's records cannot be parsed. `--host` selects one host.
+  ([#52], [#53])
+- Codex CLI support: dated rollout discovery, project and session identity from
+  session metadata, resume-file grouping with cross-file deduplication,
+  sub-agent session separation, native tool-call events, and filtering of
+  encrypted agent payloads and injected machine blocks. ([#52])
+- Cursor support: chat history read from Cursor's SQLite storage through
+  private snapshot copies opened read-only, covering both composer index
+  layouts, with per-composer checkpoints and live-update handling. ([#53])
+- `sessionmem doctor` now checks transcript discovery for each supported
+  host. ([#52], [#53])
+
+## [1.5.0] - 2026-10-18
+
+### Added
+
+- `sessionmem scan` to import existing Claude Code transcripts into memory, and
+  `sessionmem watch` to capture new and updated sessions continuously. Both are
+  idempotent across reruns and restarts and work fully offline. ([#45])
+- Automatic host detection during `sessionmem install`, and a `sessionmem doctor`
+  command that checks the store, hooks, adapter wiring, and recall with fix
+  hints for each failure. ([#46])
+- Deterministic entity and relation extraction during capture and scan, a
+  `sessionmem entities` command, and entity overlap as a recall ranking
+  signal. ([#48])
+- Deterministic supersession handling: memories that replace an earlier fact are
+  linked with history, and recall prefers current facts while replaced ones stay
+  retrievable explicitly. ([#49])
+- `sessionmem ui`, a local read-only web viewer for memories, entities,
+  relations, and supersession history, served on localhost with no external
+  services. ([#50])
+- COMPARISON.md, a cited comparison with claude-mem, Mem0, and Zep, plus a draft
+  MCP registry listing. ([#51])
+- A reproducible offline LoCoMo evaluation: committed corpus with provenance and
+  checksums, and a runner reporting hit rate, precision, recall, and latency
+  with all network access blocked. ([#44])
+
+### Changed
+
+- Retrieval now ranks with SQLite FTS5 BM25 and Porter stemming over memory
+  content and summaries. Measured on the committed LoCoMo evaluation, top-5 hit
+  rate improved from 1.44% to 61.95%, and to 63.92% with entity overlap. ([#47], [#48])
+- The release workflow skips the npm publish when the version already exists on
+  the registry and creates the GitHub release with notes from this
+  changelog. ([#43])
+
 ## [1.4.0] - 2026-10-16
 
 ### Added
@@ -68,6 +121,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   errors and findings fail the job; added scanner dependency updates and
   Dependabot cooldowns. ([#32])
 
+[1.6.0]: https://github.com/catfish-1234/sessionmem/compare/v1.5.0...v1.6.0
+[1.5.0]: https://github.com/catfish-1234/sessionmem/compare/679b8954f0b49f197985c40da47f181c00060cd9...v1.5.0
+[#43]: https://github.com/catfish-1234/sessionmem/pull/43
+[#44]: https://github.com/catfish-1234/sessionmem/pull/44
+[#45]: https://github.com/catfish-1234/sessionmem/pull/45
+[#46]: https://github.com/catfish-1234/sessionmem/pull/46
+[#47]: https://github.com/catfish-1234/sessionmem/pull/47
+[#48]: https://github.com/catfish-1234/sessionmem/pull/48
+[#49]: https://github.com/catfish-1234/sessionmem/pull/49
+[#50]: https://github.com/catfish-1234/sessionmem/pull/50
+[#51]: https://github.com/catfish-1234/sessionmem/pull/51
+[#52]: https://github.com/catfish-1234/sessionmem/pull/52
+[#53]: https://github.com/catfish-1234/sessionmem/pull/53
 [1.4.0]: https://github.com/catfish-1234/sessionmem/compare/a73f503123b1d33c35407ce66403f281ba3451ac...679b8954f0b49f197985c40da47f181c00060cd9
 [#22]: https://github.com/catfish-1234/sessionmem/pull/22
 [#23]: https://github.com/catfish-1234/sessionmem/pull/23

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>
 
-**Project memory between sessions, stored on your machine. Startup context used 85.6% fewer tokens than full session history in the included benchmark.**
+**Project memory between sessions, stored on your machine.**
 
 ```
 New session. Claude starts fresh.
@@ -49,16 +49,25 @@ Run this in your project folder after configuring your AI tool (Claude Code, Cur
 
 ```bash
 sessionmem install
-# From a plain terminal, choose the host explicitly when needed:
+# Optional: select one host explicitly, including in automation:
 sessionmem install --adapter claude-code
 # Other names: cursor, cline, codex, windsurf, antigravity, qcoder, generic
 ```
 
-This initializes the database and, for supported adapters:
+`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.
+
+This initializes the database and, for each selected adapter:
 
 - 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
 
@@ -73,10 +82,12 @@ After restarting:
 - 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.
 
-Check that the local database is accessible:
+Check the installation offline:
 
 ```bash
-sessionmem ping
+sessionmem doctor
+# For an explicitly selected host:
+sessionmem doctor --adapter claude-code
 ```
 
 ---
@@ -139,36 +150,21 @@ The SQLite file is easy to inspect, back up, or delete, and you can use it acros
 
 ## Benchmark results
 
-These numbers come from `npm run benchmark` (`scripts/benchmark.mjs`). It runs the production retrieval and injection code against fixed, synthetic test data without network calls. See [`docs/benchmark.md`](docs/benchmark.md) for the full report and reproduction steps.
-
-### 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 this benchmark, about 1,600 tokens of session history become roughly 230 tokens of decisions, warnings, and facts for the next session.
-
-### Retrieval accuracy
+`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.
 
-> **100% hit-rate**: all 10 test queries retrieved the expected memory.
-
-| Metric | Result |
-|---|---|
-| Hit-rate (10 curated queries) | 100.0% |
-| Recall | 100.0% |
-| Precision | 33.3% |
-
-Each query returns 3 candidate memories, with one scored as the expected match. That gives 33.3% precision even when the expected memory is found every time. The other two candidates may provide context, but are not scored as matches. These results apply to the 10 curated queries; see the report for the embedding model's limits.
-
-The benchmark is deterministic and reproducible:
+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
 ```
 
 ---
@@ -213,16 +209,22 @@ See [`docs/architecture.md`](docs/architecture.md) for the technical overview.
 
 | Command | What it does |
 |---------|--------------|
-| `sessionmem install [--adapter <name>]` | Register sessionmem with the current MCP host and write default config. |
+| `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, transcript discovery, 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 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>]` | Search memories by semantic query (limit 1–100, default 10). |
+| `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 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 [--host <host>] [--transcripts-dir <path>]` | Import existing Claude Code, Codex CLI, and Cursor transcripts into local session memories. Reports files found, sessions imported, memories created, skips, and errors. |
+| `sessionmem watch [--once] [--interval <seconds>] [--host <host>] [--transcripts-dir <path>]` | Capture new or updated Claude Code, Codex CLI, and Cursor 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. |
@@ -253,9 +255,185 @@ for Windows paths. Imports accept CRLF and a UTF-8 BOM; convert other encodings
 
 `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/uninstall host unless `--adapter` is set.
+`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, Codex CLI, and Cursor sessions from before sessionmem was installed:
+
+```bash
+sessionmem scan
+sessionmem watch --once
+sessionmem watch --interval 10
+sessionmem scan --host cursor
+```
+
+Both commands sweep all detected transcript histories by default:
+
+- Claude Code: `~/.claude/projects/**/*.jsonl`.
+- Codex CLI: `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`.
+- Cursor: `User/globalStorage/state.vscdb` under
+  `~/Library/Application Support/Cursor` on macOS, `~/.config/Cursor` on Linux,
+  or `%APPDATA%/Cursor` on Windows.
+
+Missing history directories are allowed. Use `--transcripts-dir "/path/to/history"`
+to select another transcript tree; each JSONL file's host is detected from its records.
+For Cursor, the override accepts its `User` directory or a `state.vscdb` path.
+Use `--host cursor`, `--host codex`, or `--host claude-code` to select one host,
+including when using an override. A Cursor User directory or `.vscdb` file is
+also detected without `--host`. Files that do not match a supported format, or
+the selected host, produce an explicit `unsupported format` error.
+
+Both commands work offline without API keys and always use the local summarizer,
+even if cloud summarization is enabled elsewhere. `sessionmem doctor` checks
+transcript discovery for all three hosts, parses JSONL samples, and validates
+Cursor's composer indexes and message rows when history is present.
+
+Transcript user/assistant text, supported Claude tool uses (Bash, Edit, Write,
+MultiEdit), and Codex function calls pass through the existing event-ingestion,
+redaction, and session-summary pipeline. Codex tool events retain the native tool
+name and `call_id`. Encrypted `agent_message` payloads and obvious injected machine
+blocks, including plugin catalogues and environment context, are excluded. Each
+session gets one summary memory, including short sessions with only one event.
+Updated sessions refresh that summary. Project buckets come from
+each Claude transcript's `cwd`, Codex `session_meta.payload.cwd`, or Cursor's
+workspace path, using the 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 capturable events are skipped. Claude transcripts
+without a working directory are also skipped; Codex session metadata must contain
+an ID and working directory. Nested subagent files get separate session summaries.
+Summary memories record `sourceAdapter` as `claude-code`, `codex`, or `cursor`
+according to the transcript host. Cursor session IDs come from `composerId`.
+
+Cursor stores messages in `cursorDiskKV` bubble rows in its global SQLite
+database. The importer supports workspace `composer.composerData` indexes
+(Cursor 2.6 and earlier) and the central `composer.composerHeaders` index
+(Cursor 3.0 and later). It captures up to 4,000 characters of user/assistant text
+per bubble and excludes tool-only bubbles and internal tool/code fields. Missing
+tables, index keys, or required conversation data produce an explicit
+`unsupported format for cursor` error.
+
+Cursor databases are never written. Each sweep copies the database and its WAL
+to a private temporary directory, checking for concurrent changes during the
+copy. SQLite opens the copy read-only, using immutable mode when URI support is
+available and there is no WAL to replay. Cursor's live database is never opened by SQLite. Busy
+copies are reported and retried. Each sweep reads a fresh snapshot; per-composer
+checkpoints skip unchanged messages, and streamed bubble updates refresh the
+existing event without duplicating it.
+
+Codex resumes create new rollout files. Files with the same session ID are grouped,
+and replayed events are deduplicated across files, sweeps, and restarts. A Codex
+sub-agent keeps its own `session_meta.payload.id`, even when `parent_thread_id`
+points to a parent session.
+
+Re-running either command does not duplicate memories or transcript events.
+File and composer checkpoints live in the selected memory database, and unchanged
+files or composers are skipped across restarts. For Cursor, `files found` counts
+global databases, and `skipped` counts unchanged or empty composers.
+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, Codex, and Cursor 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
@@ -296,13 +474,13 @@ Old decisions and duplicate facts can accumulate in a memory store, causing the
    sessionmem retention prune --force  # actually deletes
    ```
 
-2. **Importance-weighted ranking**: retrieval ranks memories by semantic relevance, recency, and importance. Older, less important notes rank lower even before they are 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 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**: 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 benchmark above found every expected memory across its 10 queries (100% hit-rate and recall) with ranking and trimming enabled.
+The [conversational benchmark](benchmarks/README.md) measures retrieval quality separately from retention and startup token budgets.
 
 Export your memories before pruning if you want to keep a copy:
 
@@ -359,7 +537,7 @@ Other tools that implement the [Model Context Protocol](https://modelcontextprot
 ## 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.
@@ -372,13 +550,27 @@ Other tools that implement the [Model Context Protocol](https://modelcontextprot
 
 For install failures, adapter issues, missing session data, or `better-sqlite3` native-build problems, see [`docs/troubleshooting.md`](docs/troubleshooting.md).
 
-To refresh the installation and check for stored session data:
+Start with offline diagnostics:
 
 ```bash
-sessionmem install   # idempotent; Claude Code also installs 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, transcript
+discovery for Claude Code and Codex, 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.
 
 To check database access and memory counts:

package/dist/adapters/diagnostics.js

@@ -0,0 +1,109 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { IDEInstaller, isManagedClaudeHook } from "./ide/installer.js";
+import { resolveDbPath } from "../cli/context.js";
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+export function checkHooks(installation) {
+    const expected = installation.hooks;
+    if (!expected)
+        return "This host uses MCP tools; no lifecycle hooks are required";
+    const config = IDEInstaller.parseJsonc(readFileSync(expected.path, "utf8"));
+    if (config.disableAllHooks === true)
+        throw new Error("Claude Code has disableAllHooks enabled");
+    const hooks = object(config.hooks);
+    for (const spec of expected.entries) {
+        const entries = Array.isArray(hooks[spec.event]) ? hooks[spec.event] : [];
+        const managed = entries.flatMap((value) => {
+            const entry = object(value);
+            return Array.isArray(entry.hooks) ? entry.hooks.filter((value) => isManagedClaudeHook(object(value).command, spec.command)).map((hook) => ({ entry, hook: object(hook) })) : [];
+        });
+        const matches = managed.filter(({ entry, hook }) => {
+            if (entry.matcher !== spec.matcher || entry.async === true)
+                return false;
+            return hook.type === "command" && hook.command === spec.command && hook.async !== true;
+        });
+        if (managed.length !== 1 || matches.length !== 1)
+            throw new Error(`${spec.event} hook is missing, duplicated, or differs from the current definition`);
+    }
+    return `SessionStart, SessionEnd, PostToolUse match current hook definitions (${expected.path})`;
+}
+/** Check the installed launch entry before executing the known local command. */
+export function readMcpLaunch(installation) {
+    const expected = installation.mcp;
+    const content = readFileSync(expected.path, "utf8");
+    let entry;
+    if (expected.format === "toml") {
+        // The Codex installer writes this small TOML section with JSON-compatible
+        // quoted values. Refuse unfamiliar syntax rather than claiming it works.
+        const section = content.match(/^\s*\[mcp_servers\.sessionmem\][^\S\r\n]*\r?\n([\s\S]*?)(?=^\s*\[|$(?![\s\S]))/m)?.[1];
+        if (!section)
+            throw new Error("sessionmem MCP section is missing");
+        if (/^\s*\[mcp_servers\.sessionmem\./m.test(content) || /^\s*(?:env|env_vars|cwd|url)\s*=/m.test(section)) {
+            throw new Error("Custom Codex launch settings require manual verification; doctor supports the installer-generated command and args");
+        }
+        if (/^\s*enabled\s*=\s*false\s*$/m.test(section))
+            throw new Error("sessionmem MCP server is disabled");
+        entry = {
+            command: JSON.parse(section.match(/^\s*command\s*=\s*(.+)$/m)?.[1] ?? "null"),
+            args: JSON.parse(section.match(/^\s*args\s*=\s*(.+)$/m)?.[1] ?? "null"),
+        };
+    }
+    else {
+        const config = IDEInstaller.parseJsonc(content);
+        entry = object(object(config.mcpServers).sessionmem);
+    }
+    if (entry.disabled === true)
+        throw new Error("sessionmem MCP server is disabled");
+    if (entry.type !== undefined && entry.type !== "stdio")
+        throw new Error("sessionmem MCP server must use the local stdio transport");
+    if (entry.command !== expected.command || JSON.stringify(entry.args) !== JSON.stringify(expected.args)) {
+        throw new Error(`sessionmem MCP launch entry differs from the current definition (${expected.path})`);
+    }
+    if (entry.env !== undefined && (entry.env === null || typeof entry.env !== "object" || Array.isArray(entry.env))) {
+        throw new Error("sessionmem MCP environment must be an object");
+    }
+    const env = object(entry.env);
+    if (Object.values(env).some((value) => typeof value !== "string")) {
+        throw new Error("sessionmem MCP environment values must be strings");
+    }
+    return { command: expected.command, args: expected.args, env: env };
+}
+export async function probeMcpWiring(launch, dbPath, version) {
+    if (launch.env?.SESSIONMEM_DB_PATH && resolve(resolveDbPath(launch.env.SESSIONMEM_DB_PATH)) !== resolve(dbPath)) {
+        throw new Error("MCP configuration selects a different SESSIONMEM_DB_PATH; run doctor with that path");
+    }
+    const inherited = Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== undefined));
+    const client = new Client({ name: "sessionmem-doctor", version });
+    const transport = new StdioClientTransport({
+        command: launch.command,
+        args: launch.args,
+        env: { ...inherited, ...launch.env, SESSIONMEM_DB_PATH: dbPath },
+        stderr: "ignore",
+    });
+    try {
+        await client.connect(transport, { timeout: 5000 });
+        const server = client.getServerVersion();
+        if (server?.name !== "sessionmem" || server.version !== version) {
+            throw new Error(`MCP server version does not match sessionmem ${version}`);
+        }
+        const tools = await client.listTools({}, { timeout: 5000 });
+        for (const name of ["stats", "storeMemory", "retrieveMemories"]) {
+            if (!tools.tools.some((tool) => tool.name === name))
+                throw new Error(`MCP tool ${name} is missing`);
+        }
+        const result = await client.callTool({ name: "stats", arguments: {} }, undefined, { timeout: 5000 });
+        const payload = Array.isArray(result.content) ? object(result.content.find((part) => object(part).type === "text")) : {};
+        if (result.isError || typeof payload.text !== "string" || !JSON.parse(payload.text).ok) {
+            throw new Error("MCP stats tool failed");
+        }
+    }
+    finally {
+        await transport.close();
+    }
+}

package/dist/adapters/generic.js

@@ -69,6 +69,7 @@ const TOOL_DEFINITIONS = [
             mode: retrieveMemoriesRequestSchema.shape.mode.describe("'auto' for the standard startup context-load path. 'on-demand' for an explicit mid-session retrieval triggered by a specific task or question."),
             depth: retrieveMemoriesRequestSchema.shape.depth.describe("'default' for standard semantic search. 'deep' for a broader sweep that surfaces less-similar memories — use when the topic is new or unfamiliar."),
             tags: retrieveMemoriesRequestSchema.shape.tags.describe("Optional tag filter. When provided, only return memories that have ALL listed tags."),
+            includeHistory: retrieveMemoriesRequestSchema.shape.includeHistory.describe("Include superseded facts for historical questions. Omit for current facts only."),
         },
     },
     {
@@ -209,18 +210,21 @@ export class GenericMCPAdapter {
     guidanceTargets() {
         return [join(process.cwd(), "AGENTS.md")];
     }
+    installation() {
+        return { mcp: { path: join(process.cwd(), ".mcp.json"), command: "sessionmem", args: ["run"] } };
+    }
     /**
      * Fallback for hosts that aren't specifically detected: register sessionmem
      * in a project-local `.mcp.json` (the de-facto generic MCP config format).
      */
     async install() {
-        const configPath = join(process.cwd(), ".mcp.json");
+        const configPath = this.installation().mcp.path;
         return IDEInstaller.injectMcpConfig(configPath, "sessionmem", "sessionmem", [
             "run",
         ]);
     }
     async uninstall() {
-        const configPath = join(process.cwd(), ".mcp.json");
+        const configPath = this.installation().mcp.path;
         return IDEInstaller.removeMcpConfig(configPath, "sessionmem");
     }
     async call(_method, _request) {

package/dist/adapters/global/antigravity.js

@@ -11,13 +11,16 @@ import { IDEInstaller } from "../ide/installer.js";
 const ANTIGRAVITY_MCP_CONFIG = [".gemini", "config", "mcp_config.json"];
 export class AntigravityAdapter extends GenericMCPAdapter {
     name = "Antigravity";
+    installation() {
+        return { mcp: { path: join(homedir(), ...ANTIGRAVITY_MCP_CONFIG), command: "sessionmem", args: ["run"] } };
+    }
     // Capabilities inherited from GenericMCPAdapter (tools only).
     /** Antigravity reads AGENTS.md-style guidance from its global config dir. */
     guidanceTargets() {
         return [join(homedir(), ".antigravity", "AGENTS.md")];
     }
     async install() {
-        const configPath = join(homedir(), ...ANTIGRAVITY_MCP_CONFIG);
+        const configPath = this.installation().mcp.path;
         return IDEInstaller.injectMcpConfig(configPath, "sessionmem", "sessionmem", [
             "run",
         ]);

package/dist/adapters/global/claudeCode.js

@@ -21,15 +21,30 @@ export class ClaudeCodeAdapter extends GenericMCPAdapter {
     settingsPath() {
         return join(homedir(), ".claude", "settings.json");
     }
+    installation() {
+        const isWindows = process.platform === "win32";
+        return {
+            mcp: {
+                path: join(homedir(), ".claude.json"),
+                command: isWindows ? "cmd" : "sessionmem",
+                args: isWindows ? ["/c", "sessionmem", "run"] : ["run"],
+            },
+            hooks: {
+                path: this.settingsPath(),
+                entries: [
+                    { event: "SessionStart", command: SESSIONMEM_HOOK_COMMAND },
+                    { event: "SessionEnd", command: SESSIONMEM_SESSION_END_HOOK_COMMAND },
+                    { event: "PostToolUse", command: SESSIONMEM_POST_TOOL_HOOK_COMMAND, matcher: SESSIONMEM_POST_TOOL_MATCHER },
+                ],
+            },
+        };
+    }
     async install() {
-        const configPath = join(homedir(), ".claude.json");
         // On Windows, the globally-installed `sessionmem` bin is a `.cmd` shim.
         // Claude Code spawns MCP servers WITHOUT a shell, and `.cmd` shims require
         // cmd.exe to execute, so a bare `command: "sessionmem"` fails to start.
         // Route through `cmd /c sessionmem run` so the shim is resolved correctly.
-        const isWindows = process.platform === "win32";
-        const command = isWindows ? "cmd" : "sessionmem";
-        const args = isWindows ? ["/c", "sessionmem", "run"] : ["run"];
+        const { path: configPath, command, args } = this.installation().mcp;
         const mcpOk = await IDEInstaller.injectMcpConfig(configPath, "sessionmem", command, args);
         // Register a SessionStart hook so prior memories are injected automatically
         // at the start of EVERY Claude Code session. This is the deterministic