sessionmem 1.2.0 → 1.4.0

package/dist/core/summarize/summaryShape.js

@@ -1,3 +1,12 @@
+/** Max distinct lines rendered per section. */
+const MAX_SECTION_LINES = 5;
+/** Max `- [type] text` fact lines in the facts section. */
+const MAX_FACT_LINES = 8;
+/**
+ * Human-readable text for an event. The auto-ingest hook writes a `text` field
+ * carrying a one-line description ("Ran: npm test", "Edited src/foo.ts"); fall
+ * back to the raw payload for events written by other producers.
+ */
 function extractEventText(event) {
     try {
         const parsed = JSON.parse(event.payload_json);
@@ -10,34 +19,55 @@ function extractEventText(event) {
     }
     return event.payload_json.trim();
 }
-function sectionLines(events, fallback) {
-    const lines = events.map(extractEventText).filter((line) => line.length > 0);
-    if (lines.length === 0) {
-        return [fallback];
+/** Distinct, non-empty lines, preserving first-seen order. */
+function distinctLines(events) {
+    const seen = new Set();
+    const lines = [];
+    for (const event of events) {
+        const line = extractEventText(event);
+        if (line.length === 0 || seen.has(line))
+            continue;
+        seen.add(line);
+        lines.push(line);
     }
-    return lines.slice(0, 3);
+    return lines;
 }
+function section(title, lines, fallback) {
+    const body = lines.length > 0 ? lines : [fallback];
+    return [title, ...body.map((line) => `- ${line}`)];
+}
+/**
+ * Render the session's events as a structured summary.
+ *
+ * Sections carry DIFFERENT slices of the session rather than the same lines
+ * repeated under every heading: `actions` is what happened in order, `outcomes`
+ * is where the session ended up, and `decisions` surfaces the events that
+ * recorded a choice (git commits). Repeating one slice under all five headings
+ * produced a summary that cost five times the tokens and carried no extra
+ * signal — and, once stored, was what every later session got injected with.
+ */
 export function buildStructuredSummary(events, options) {
-    const sharedLines = sectionLines(events, "No relevant events captured.");
+    const lines = distinctLines(events);
+    // Ordered narrative of the session, capped from the front.
+    const actions = lines.slice(0, MAX_SECTION_LINES);
+    // Where the session ended up: the tail, which is the most recent state.
+    const outcomes = lines.length > MAX_SECTION_LINES
+        ? lines.slice(-Math.min(MAX_SECTION_LINES, lines.length - MAX_SECTION_LINES))
+        : lines.slice(-1);
+    // Commits are the durable decisions a session leaves behind.
+    const decisions = lines
+        .filter((line) => /\bgit\s+commit\b/i.test(line))
+        .slice(0, MAX_SECTION_LINES);
     const summarySection = [
-        "goals",
-        ...sharedLines.map((line) => `- ${line}`),
-        "",
-        "actions",
-        ...sharedLines.map((line) => `- ${line}`),
-        "",
-        "decisions",
-        ...sharedLines.map((line) => `- ${line}`),
+        ...section("actions", actions, "No relevant events captured."),
         "",
-        "blockers",
-        ...sharedLines.map((line) => `- ${line}`),
+        ...section("decisions", decisions, "No explicit decisions recorded."),
         "",
-        "outcomes",
-        ...sharedLines.map((line) => `- ${line}`),
+        ...section("outcomes", outcomes, "No outcomes captured."),
     ].join("\n");
     const facts = events
-        .map((event) => `- [${event.event_type}] ${extractEventText(event)}`)
-        .slice(0, 5);
+        .slice(0, MAX_FACT_LINES)
+        .map((event) => `- [${event.event_type}] ${extractEventText(event)}`);
     const factSection = ["facts", ...facts].join("\n");
     if (options.factMode === "summary-only") {
         return summarySection;

package/docs/architecture.md

@@ -0,0 +1,53 @@
+# Architecture
+
+`sessionmem` connects a coding agent's MCP host to a local SQLite memory database. This overview covers its four subsystems and the retrieval and injection flows. It runs locally by default, with settings in `~/.sessionmem/config.json`.
+
+## Subsystems
+
+```
+        ┌──────────────────────────────────────────────┐
+        │                  MCP host                     │
+        │   (Claude Code, Cursor, Codex, Cline, ...)    │
+        └───────────────────────┬──────────────────────┘
+                                │ MCP / hooks
+                    ┌───────────▼───────────┐        ┌──────────────┐
+                    │       adapters        │        │     CLI      │
+                    │ (host-specific glue)  │        │ (sessionmem) │
+                    └───────────┬───────────┘        └──────┬───────┘
+                                │                           │
+                                ▼                           ▼
+                    ┌──────────────────────────────────────────────┐
+                    │                 core engine                   │
+                    │   capture · summarize · retrieval · injection │
+                    └───────────────────────┬──────────────────────┘
+                                            │
+                                            ▼
+                    ┌──────────────────────────────────────────────┐
+                    │             SQLite storage (local)            │
+                    │     memories · session events · feedback      │
+                    └──────────────────────────────────────────────┘
+```
+
+### Core engine
+
+The core engine captures session events, summarizes them into stored memories at session end, ranks those memories, and selects which to inject. It uses the adapter layer for all communication with specific tools. Retrieval combines semantic similarity, recency, and importance into a relevance score.
+
+### Adapters
+
+Adapters translate between each MCP host's hooks or runtime and the core engine's API. There are adapters for Claude Code, Cursor, Codex, Cline, Windsurf, Antigravity, QCoder, and generic MCP hosts. They connect host lifecycle events to the engine's capture, summarize, and inject calls. A new platform needs an adapter; the core engine stays the same.
+
+### CLI
+
+The CLI (`sessionmem`) registers the server with a host and runs the MCP server. It also has commands to search, list, show, forget, export, import, prune, and configure memories. These commands call the same core engine as the adapters.
+
+### SQLite storage
+
+SQLite stores memories, embeddings for vector search, raw session events, and feedback history in one local file. Database access uses `better-sqlite3`, with forward-only [migrations](migration.md). No hosted database is required.
+
+## Retrieval flow
+
+When an agent or `sessionmem search` submits a query, the core engine embeds it and runs a vector search over the `memories` table. It ranks candidates by semantic similarity, recency, and importance, then returns the memories with their scores.
+
+## Injection flow
+
+At session start, the engine retrieves relevant memories and trims them to a token budget, a few hundred tokens by default. It keeps critical warnings and high-importance decisions first, dropping lower-priority content as needed. The adapter adds the result to the host's context. Claude Code's installed SessionStart hook does this automatically. Other hosts need an agent or lifecycle integration to call the corresponding MCP tools; MCP registration alone does not install hooks in those hosts.

package/docs/benchmark.md

@@ -0,0 +1,50 @@
+# Benchmark
+
+`npm run benchmark` (`scripts/benchmark.mjs`) generates this report using the production functions `retrieveMemories`, `formatStartupInjection`, and `countTokens`. It measures token reduction against full session history and retrieval relevance using curated, synthetic fixtures. It runs offline with a hash-based embedding function, `deterministicEmbed`, and a fixed clock, so repeated runs produce identical output.
+
+Startup injection used **~85.6% fewer tokens** than full session history. Retrieval had a **100.0% hit-rate** across 10 curated queries.
+
+## Token reduction
+
+Token counts use the production `countTokens` function (js-tiktoken `o200k_base`). The table compares a single startup injection and average per-query context with the same full-history baseline. The result above uses startup injection.
+
+| Framing | Baseline tokens (full history) | Injected tokens | Reduction |
+|---------|-------------------------------|-----------------|-----------|
+| (a) Top-3 startup injection vs full history | 1587 | 228 | 85.6% |
+| (b) Per-query injected context (avg) vs full history | 1587 | 232 | 85.4% |
+
+Row (a) measures one startup injection of the top-ranked memories. Row (b) averages the injected context across the curated queries to model per-turn retrieval.
+
+## Retrieval relevance
+
+Each query runs through `retrieveMemories` with a limit of 3 results. The returned ids are compared with the expected memory ids. A query counts as a hit if at least one expected memory is returned.
+
+- **Hit-rate:** 100.0% (10 queries)
+- **Overall recall:** 100.0%
+- **Overall precision:** 33.3%
+
+| Query (memory content) | Expected memory | Recall | Precision |
+|------------------------|-----------------|--------|-----------|
+| We chose JWT access tokens with a 15-minute expiry and ro... | mem-auth-decision | 100.0% | 33.3% |
+| The persistence layer uses better-sqlite3 with WAL mode; ... | mem-db-decision | 100.0% | 33.3% |
+| Embeddings are computed offline with a deterministic sha2... | mem-embed-fact | 100.0% | 33.3% |
+| Retrieval ranks candidates by a weighted blend of semanti... | mem-retrieval-fact | 100.0% | 33.3% |
+| Startup injection formats the top-ranked memories under a... | mem-injection-fact | 100.0% | 33.3% |
+| Never edit an already-shipped migration file in place; ad... | mem-migration-warning | 100.0% | 33.3% |
+| Redaction must run on every memory-write path before stor... | mem-secret-warning | 100.0% | 33.3% |
+| The CLI exposes remember, retention prune, redact-scan, a... | mem-cli-fact | 100.0% | 33.3% |
+| Tests use vitest; integration specs seed an in-memory dat... | mem-testing-fact | 100.0% | 33.3% |
+| The MCP server runs over stdio and exposes memory retriev... | mem-mcp-decision | 100.0% | 33.3% |
+
+### Relevance interpretation
+
+`deterministicEmbed` uses a hash-based fingerprint. Identical text has a cosine similarity of 1.0; wording changes produce noisy scores. It supports exact or near-exact recall rather than semantic matching of paraphrases. These queries contain the target memory's content, so the hit-rate measures whether ranking retrieves that memory in that case. Matching paraphrases requires a semantic embedding model. Replacing the embedding model leaves the retrieval and scoring code unchanged, so the benchmark can still exercise those paths.
+
+## Reproducing
+
+```bash
+npm run build      # benchmark imports built functions from dist/
+npm run benchmark  # regenerates this file deterministically
+```
+
+_Fixtures are synthetic; the report contains only aggregate metrics and synthetic example content. Generated by `scripts/benchmark.mjs`._

package/docs/cloud-summarization.md

@@ -0,0 +1,57 @@
+# Cloud Summarization
+
+## Default Mode
+
+`sessionmem` defaults to local summarization. Local mode runs without external API calls.
+
+## How to Enable Cloud Mode
+
+Cloud mode activates only when both conditions are true:
+
+1. `allowCloudSummarization=true`
+2. `ANTHROPIC_API_KEY` is present (mapped to `anthropicApiKey` in runtime config)
+
+If either condition is missing, summarization stays local.
+
+## How It Works
+
+Cloud summarization runs in two steps:
+
+1. **Local preprocessing** - the local summarizer extracts and structures session events
+   into a short transcript, with secret redaction applied before it leaves the machine.
+
+2. **Cloud compression** - the transcript is sent to the Anthropic Messages API with
+   instructions to compress it into a short list of facts, decisions, and context.
+
+### Model Configuration
+
+The default model is `claude-sonnet-4-6`, defined as `DEFAULT_SUMMARIZER_MODEL` in
+`src/core/config/policyConfig.ts`. Callers can override the model via the `model` field
+in `CloudSummarizeInput`.
+
+### Token Limits
+
+The API's `max_tokens` parameter is `Math.min(Math.floor((summaryTokenCap ?? 4000) * 1.5), 8192)`.
+The response is then trimmed to `summaryTokenCap`.
+
+## Runtime Warning Signals
+
+When cloud mode is active, lifecycle responses include:
+
+- warning code: `cloud_summarization_enabled`
+- warning message: `Cloud summarization active: allowCloudSummarization=true and ANTHROPIC_API_KEY present`
+
+Use these warnings to check whether cloud summarization is active.
+
+## Failure Fallback Behavior
+
+Cloud summarization retries 2 times. If the retries fail, it falls back to local summarization automatically.
+
+Cloud failures are saved in `summarization_failures`. If local fallback succeeds,
+the response includes a warning about the cloud failure. If fallback also fails,
+an additional failure record is saved.
+
+## Manual Summarization When Auto Is Disabled
+
+Setting `autoSummarize=false` disables automatic `session_end` summarization only.
+You can still call `summarizeSessionToMemory` manually.

package/docs/migration.md

@@ -0,0 +1,42 @@
+# Migration and Upgrade Policy
+
+This guide explains SQLite migrations and what to expect when upgrading sessionmem. Configuration and the default database live under `~/.sessionmem/`.
+
+## Migration system
+
+`sessionmem` updates its SQLite schema with forward-only migrations. Each migration is a `.sql` file under `src/core/schema/migrations/`. Zero-padded numeric prefixes determine the order:
+
+```
+src/core/schema/migrations/
+  001_initial.sql
+  002_indexes.sql
+  003_summarization_failures.sql
+  004_memory_feedback.sql
+  005_team_provenance.sql
+```
+
+### How migrations run
+
+At startup, the runner creates the `_migrations` tracking table if needed and sorts the `.sql` files by name. It applies each migration in its own transaction, skipping any already recorded in `_migrations`. Starting sessionmem again does not reapply completed migrations. There are no down-migrations.
+
+### Build-time copy: `copy-migrations`
+
+The TypeScript compiler does not copy `.sql` files. The build step `copy-migrations` runs `scripts/copy-migrations.mjs` to copy them from `src/core/schema/migrations/` to `dist/core/schema/migrations/`. This includes the migrations in the published package alongside the compiled code.
+
+At runtime, sessionmem loads migrations relative to the installed module, using the packaged `dist` copy. It does not search the working directory, where an attacker could place a malicious `migrations/` folder (Phase 5 Decision #15). After adding or editing a migration, re-run the build so `copy-migrations` updates `dist`.
+
+### Adding a migration (contributors)
+
+1. Add a new `NNN_description.sql` file with the next ordinal in `src/core/schema/migrations/`.
+2. Keep it forward-only and idempotent where practical.
+3. Re-run the build so `copy-migrations` copies it into `dist/core/schema/migrations/`.
+
+## Version-upgrade policy
+
+`sessionmem` follows **semantic versioning** (semver): `MAJOR.MINOR.PATCH`.
+
+- **Patch / minor upgrades** work with your existing database. Additive, forward-only migrations run automatically when the upgraded version first opens it. Stored memories are preserved and no manual migration is needed.
+- **Major-version upgrades** may introduce breaking changes. The release notes will describe behavior changes and any manual migration steps.
+- **Downgrades after migration are unsupported.** Before a major upgrade, run `sessionmem export` to keep a portable JSON copy of your memories that you can re-import if needed.
+
+This policy applies to upgrades between published v1 releases. Each release opens existing databases through the same forward-only migration runner.

package/docs/privacy-and-retention.md

@@ -0,0 +1,139 @@
+# Privacy and Retention
+
+`sessionmem` stores memories locally, redacts secrets before saving, and prunes old memories according to a retention policy. Configure both in `~/.sessionmem/config.json` or with the CLI commands below.
+
+## Secret Redaction
+
+Redaction replaces common secret patterns with `REDACTED` before saving memory content. It runs during:
+
+- automatic summarization at session end,
+- manual memory storage (`storeMemory` or `batchStoreMemory`),
+- import.
+
+The `redactionEnabled` flag controls all of these operations and defaults to `true`.
+
+### Redacted categories
+
+| Category | Examples |
+|----------|----------|
+| Email addresses | `user@example.com` |
+| `sk-` API keys | OpenAI-style `sk-...` keys |
+| AWS access keys | `AKIA...` |
+| GitHub tokens | `ghp_...`, `gho_...`, and related prefixes |
+| Bearer tokens | `Authorization: Bearer ...` |
+| Private key blocks | `-----BEGIN ... PRIVATE KEY-----` private key blocks |
+| Connection-string assignments | `password=...`, `secret=...` |
+| JWTs | three-part `xxxxx.yyyyy.zzzzz` tokens |
+
+The project's CI secret scanning checks for similar categories.
+
+### Partial-failure warnings
+
+If redaction partly fails, the response includes a `redaction_partial_failure` warning through the usual lifecycle warning mechanism. The write still completes. Review the affected memory when you see this warning.
+
+### Disabling redaction
+
+Setting `redactionEnabled` to `false` disables redaction for all memory writes. Leave it enabled to keep these checks.
+
+## Retention Policy
+
+Retention pruning limits growth of the local store by deleting memories older than a configured age.
+
+- **Scope:** the `memories` table only. Session events and feedback history are never touched.
+- **Age basis:** a memory's `created_at` timestamp.
+- **Default window:** `90` days (`retentionDays`).
+- **Disabling:** set `retentionDays` to `0` to disable pruning. Negative values are rejected by the config schema.
+- **Hard delete:** pruned memories are permanently deleted from SQLite. There is no archive or soft-delete.
+
+> Pruning is permanent. Run `sessionmem export` first if you want to keep a copy of the memories.
+
+## Automatic vs Manual Pruning
+
+**Automatic (session-end):** a lightweight prune check runs alongside summarization without blocking or delaying it.
+
+**Manual:** the prune command previews deletions by default. It only deletes memories when you pass `--force`:
+
+```bash
+sessionmem retention prune
+```
+
+Dry-run output:
+
+```
+Would delete N memories older than {retentionDays} days. Pass --force to confirm.
+```
+
+To delete eligible memories:
+
+```bash
+sessionmem retention prune --force
+```
+
+Use `--days <n>` to set the retention window for one run, overriding `config.json` and the built-in default:
+
+```bash
+sessionmem retention prune --days 30
+```
+
+## One-time Redaction Scrub
+
+Normal memory writes do not recheck older memories. To check memories saved before redaction coverage was expanded, run `redact-scan`. It previews changes by default:
+
+```bash
+sessionmem redact-scan
+```
+
+The preview shows matching memories and a count. To redact and update them in place:
+
+```bash
+sessionmem redact-scan --apply
+```
+
+`--apply` rewrites matching memories with `REDACTED` placeholders and prints a summary count.
+
+## Policy Config
+
+Policy settings live in `~/.sessionmem/config.json`:
+
+```json
+{
+  "retentionDays": 90,
+  "redactionEnabled": true
+}
+```
+
+### Precedence
+
+Settings take precedence in this order, highest first:
+
+1. **CLI flag** (e.g. `retention prune --days 30`)
+2. **`config.json`** value
+3. **built-in default**
+
+If `config.json` is missing or invalid, sessionmem uses the built-in defaults unless a CLI flag overrides them.
+
+### Reading and writing config
+
+Use `config get` and `config set` to read and change settings:
+
+```bash
+sessionmem config get retentionDays
+sessionmem config set retention.days 30
+sessionmem config set redactionEnabled false
+```
+
+You can use either the dotted key `retention.days` or the field name `retentionDays`. Invalid values, such as a non-integer for `retentionDays` or a value other than `true`/`false` for `redactionEnabled`, produce an error without changing the file.
+
+### Install and uninstall behavior
+
+- `sessionmem install` creates `config.json` with defaults (`retentionDays: 90`, `redactionEnabled: true`) if the file is missing. It leaves an existing file unchanged.
+- `sessionmem uninstall` keeps `config.json` and the database unless you pass `--purge`.
+
+## Stats Visibility
+
+`sessionmem stats` shows the current retention and redaction settings, for example:
+
+```
+Retention: 90 days (12 memories eligible for pruning)
+Redaction: enabled
+```

package/docs/team-mode.md

@@ -0,0 +1,117 @@
+# Team Mode (Shared Memory)
+
+Team mode shares `sessionmem` memories through a directory everyone on the team can read and write, such as a network drive or synced folder. With team mode enabled, `sessionmem sync` writes your local memories there and reads teammates' memories into your database. Your agent can then use decisions, warnings, and facts recorded by the team.
+
+Team mode is off by default. Enable it to start sharing.
+
+## Setup
+
+Enable team mode by pointing it at a shared directory:
+
+```
+sessionmem team enable <shared-path>
+```
+
+`<shared-path>` must be a directory that all teammates can read and write, typically a network share or a folder synced across machines. The path is recorded in `~/.sessionmem/config.json` under the `team` section (`team.enabled` / `team.sharedPath`).
+
+Inside the shared path, `sessionmem` uses a per-project, per-user file layout:
+
+```
+{sharedPath}/{project_id}/{username}.json
+```
+
+Each teammate writes one snapshot file named after their OS username. Each project has its own subdirectory to keep snapshots separate.
+
+To check the current state:
+
+```
+sessionmem team status
+```
+
+This reports whether team mode is enabled and whether the shared path is reachable.
+
+## Usage: syncing
+
+Once team mode is enabled, run:
+
+```
+sessionmem sync
+```
+
+Each `sync` runs two steps:
+
+1. **Push**: writes a full snapshot of this project's local memories to
+   `{sharedPath}/{project_id}/{username}.json`. The write is atomic (a temp file
+   is written in the same directory and then renamed) so teammates don't read a
+   partly written snapshot.
+2. **Pull**: reads every other `*.json` snapshot in the project directory and
+   merges those memories into your local database.
+
+When it finishes, `sync` prints a summary:
+
+```
+Pushed N memories, pulled M new + updated K from teammates.
+```
+
+`N` is the number of local memories shared, `M` is the number of new teammate memories added, and `K` is the number of existing memories updated from teammate snapshots.
+
+If team mode is disabled, `sync` makes no changes and tells you to run `team enable` first.
+
+## Provenance and author annotation
+
+Each memory records its source:
+
+- **`author`**: the OS username of whoever created the memory.
+- **`created_at`**: when it was first created.
+
+In the agent's startup context, teammate memories have an `author:` prefix showing their recorded author, for example:
+
+```
+- [decision] alice: decided to use X (...)
+```
+
+Your own memories have no prefix. Older memories with an empty author also have no prefix. The prefix appears when the recorded author differs from your local username.
+
+## Conflict behavior
+
+When the same memory id exists locally and in a teammate's snapshot, `sync` resolves it as follows:
+
+- **Content**: sync uses last-write-wins by id, keeping the most recent content.
+- **Importance**: a teammate's snapshot cannot lower your local copy's importance score.
+- **Cross-project id collisions**: records whose ids already belong to a different project are skipped.
+- **Redaction**: every pulled record is checked again using your secret redaction policy.
+
+## Disable and recovery
+
+To stop syncing and keep memories already pulled from teammates:
+
+```
+sessionmem team disable
+```
+
+To also delete teammate-authored memories:
+
+```
+sessionmem team disable --remove-team-memories
+```
+
+This deletes the teammate-authored memories for this project, leaving only the memories you authored locally.
+
+## Trust boundary and security
+
+Anyone with write access to the shared path can add memories that your agent may use. Control access through the shared directory's filesystem permissions:
+
+- Restrict write access with OS filesystem permissions (ACLs) to the people you intend to share memories with.
+- The `author` field is advisory. A person with write access can change it, so the `author:` prefix does not verify identity.
+- `sessionmem` does not authenticate teammates, sign snapshots, or verify authorship. Enforce any additional access controls through the filesystem or file share.
+
+## Failure recovery
+
+When `sync` encounters filesystem or snapshot errors:
+
+- **Missing or unwritable shared path**: `sync` reports the error to stderr and
+  exits with a non-zero status. Your local memories are untouched.
+- **A corrupt or truncated teammate file**: the file is skipped with a warning,
+  and the rest of the pull continues.
+- **An invalid record inside an otherwise-valid file**: the record is skipped
+  with a warning; the remaining records still merge.

package/docs/troubleshooting.md

@@ -0,0 +1,78 @@
+# Troubleshooting
+
+This guide covers install failures, adapter (MCP host) issues, and `better-sqlite3` native-build failures. Configuration lives in `~/.sessionmem/config.json`.
+
+## Install failures
+
+### `config.json` not written
+
+`sessionmem install` creates `~/.sessionmem/config.json` only if the file is missing. It leaves an existing config unchanged. To restore defaults, move or delete the old file and re-run `sessionmem install`. To change individual settings, use `sessionmem config set`.
+
+### Adapter not detected
+
+`install` registers sessionmem with the MCP host in the current directory. If install reports that it could not find a host, you are likely running it outside a project the host recognizes. `cd` into your project root (where the host's config lives) and re-run `sessionmem install`. Use `sessionmem install --adapter <name>` from a plain terminal (for example `--adapter cline` or `--adapter windsurf`, which cannot be reliably auto-detected). Run `sessionmem ping` afterward to check local database access; it does not probe the host's MCP connection.
+
+### Command not found
+
+If `sessionmem` is not on your `PATH` after `npm install -g sessionmem`, your npm global bin directory is not on `PATH`. Add npm's global prefix `bin` to your shell `PATH`, or invoke via `npx sessionmem`.
+
+## Adapter issues
+
+Each MCP host uses its own adapter. If the server starts but memories are missing, check the host's configuration:
+
+- **Claude Code**: if memories are not injected at session start, confirm `sessionmem install` was run inside the project and that the MCP server entry exists in the host config. Use `sessionmem ping` to verify local database access, then check MCP connectivity in the host.
+- **Cursor**: Cursor must be pointed at the registered MCP server. Re-run `install` from the project root and restart Cursor so it reloads MCP servers.
+- **Generic MCP host**: for any other MCP-compatible host, ensure the host is configured to launch `sessionmem run` as the MCP server command. If the host starts but no memory appears, check that the working directory matches the project whose memories you expect.
+
+If commands hang after the host loads, run `sessionmem ping` to check local database access, then check the host's MCP connection.
+
+## "0 sessions" / no session data recorded
+
+If `sessionmem savings` reports no session data or `sessionmem stats` shows `sessions: 0`, check the following.
+
+### The hooks are not installed
+
+Session events are captured by a `PostToolUse` hook that `sessionmem install` registers in `~/.claude/settings.json`. If you installed sessionmem before the auto-ingest hook existed, that hook is missing. Re-run `sessionmem install` (it is idempotent) and restart your editor, then confirm the entry exists:
+
+```bash
+sessionmem install
+sessionmem stats   # check the session_events counter after a few tool calls
+```
+
+To watch the hook work in real time, run your host with `SESSIONMEM_DEBUG=1`; the hook then reports each ingest to stderr, including the project id it wrote to.
+
+### Memory is keyed to the repository
+
+A project's memories are keyed by its **repository root**, the nearest directory containing `.git`. All subdirectories in one repository share the same memory bucket.
+
+Outside a repository, the id falls back to the exact working directory. Two different directories that are not in a repository are two different projects, so running `sessionmem stats` from a different folder than the one your host session used will show an empty store. Either run from inside the repository, or pin the id explicitly:
+
+```bash
+export SESSIONMEM_PROJECT_ID=my-project
+```
+
+Use `sessionmem browse` to list every project that has memories along with its id; the current project is marked.
+
+### Not enough events to summarize
+
+`handleSessionEnd` only writes a session summary once at least 3 events were captured. A very short session is skipped by design and reports `not enough session events to summarize`.
+
+## `better-sqlite3` native-build failures
+
+`sessionmem` stores memories in SQLite via `better-sqlite3`, which is a **native** module compiled for your platform and Node version. Most install-time crashes come from this native build.
+
+### node-gyp build errors
+
+If `npm install` fails compiling `better-sqlite3` with `node-gyp` errors, your toolchain is incomplete:
+
+- **Windows**: install the Visual Studio Build Tools (MSVC C++ workload). `node-gyp` needs an MSVC compiler; without it the native build fails.
+- **macOS**: install the Xcode Command Line Tools (`xcode-select --install`).
+- **Linux**: install `build-essential` (or your distro's equivalent: a C/C++ compiler, `make`, and `python3`).
+
+### ABI mismatch (Node 20 vs 22)
+
+`better-sqlite3` is compiled against a specific Node ABI. If you switch Node versions (for example from Node 20 to Node 22), a prebuilt or previously compiled binary can fail to load with a module-version / ABI mismatch error. Rebuild the native module against your current Node by reinstalling, or run `npm rebuild better-sqlite3`. If you use a Node version manager, make sure you reinstall after switching versions.
+
+### Confirming the build
+
+After a successful build, `sessionmem stats` (or any command that touches the database) will run without a native-load error. A native-build failure typically surfaces immediately as a "cannot find module" or "was compiled against a different Node.js version" error the first time the database is opened.