sessionmem 1.3.0 → 1.5.0

package/docs/REGISTRY_LISTING.md

@@ -0,0 +1,88 @@
+# Registry listing — draft for review
+
+**Status: DRAFT FOR REVIEW. This is proposed listing text only; it has not been
+submitted to any MCP or tool registry.**
+
+## Name
+
+sessionmem
+
+MCP identifier: `io.github.catfish-1234/sessionmem`
+
+## One-line description
+
+An offline MCP memory server that keeps coding-agent decisions, warnings, and
+project context in local SQLite across sessions.
+
+## Features
+
+- Persistent project memory through MCP tools for storing, retrieving, listing,
+  inspecting, and forgetting memories.
+- Claude Code hooks capture supported tool events, summarize sessions locally,
+  and load relevant prior context automatically. Other MCP hosts use memory
+  tools and installed guidance; automatic lifecycle capture depends on the host.
+- Adapters for Claude Code, Codex, Cursor, Cline, Windsurf, Antigravity, QCoder,
+  and generic MCP hosts.
+- Offline BM25 retrieval with English stemming, entity overlap, recency, and
+  importance; startup context is trimmed to a token budget.
+- Deterministic entity/relation extraction and supersession history. Fully
+  replaced memories are excluded from normal recall, with explicit history
+  lookup available. These language rules have limited coverage.
+- Offline `scan`/`watch` commands for existing and new Claude Code transcripts.
+- Local SQLite storage, default secret-pattern redaction, configurable retention,
+  JSON export/import, and offline installation diagnostics with `sessionmem doctor`.
+- A committed LoCoMo corpus and reproducible offline evidence-retrieval runner;
+  see the [comparison and evaluation limits](../COMPARISON.md#evaluation-and-measured-results).
+
+## Install and connect
+
+Requires Node.js `^20.19.0 || >=22.13.0`.
+
+```bash
+npm install -g sessionmem
+```
+
+From the project directory, register it with a configured host:
+
+```bash
+sessionmem install
+```
+
+Automatic discovery currently detects Claude Code. Select other adapters
+explicitly, for example:
+
+```bash
+sessionmem install --adapter codex
+```
+
+Restart the host after registration. The host launches the stdio server with
+`sessionmem run`; this is the server command for registries that request one.
+See the [quickstart](../README.md#quickstart) for host-specific setup.
+
+## Offline guarantee
+
+**The local memory pipeline requires no API keys and makes no network calls.**
+Capture, local summarization, entity/relation extraction, supersession, and
+retrieval run on the user's machine without downloading models. Memories are
+stored by default in `~/.sessionmem/memories.db`. No hosted memory account or
+service is needed. The coding agent's own model connection is separate.
+
+Package installation may require network access or an offline package cache.
+Explicitly enabling [cloud summarization](cloud-summarization.md) with both its
+configuration flag and an Anthropic API key sends a redacted transcript to
+Anthropic. Optional [team sharing](team-mode.md) uses a user-selected shared
+folder. These opt-in paths are outside the local-only guarantee. The optional
+read-only viewer uses loopback HTTP with locally bundled assets and no external
+services or CDNs.
+
+## Links and license
+
+- [Source and setup](https://github.com/catfish-1234/sessionmem)
+- [npm package](https://www.npmjs.com/package/sessionmem)
+- [Comparison](../COMPARISON.md)
+- [Privacy and retention](privacy-and-retention.md)
+- [MIT license](../LICENSE); the bundled LoCoMo dataset has a separate
+  [CC BY-NC 4.0 license](../benchmarks/data/LICENSE.txt).
+
+Review the wording and destination-specific registry fields before any future
+submission. This draft does not claim registry acceptance or verification.

package/docs/architecture.md

@@ -0,0 +1,77 @@
+# 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 BM25 lexical relevance, entity overlap, 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, extracted entities and relations, and feedback history in one local file. Database access uses `better-sqlite3`, with forward-only [migrations](migration.md). No hosted database is required.
+
+## Entity and relation extraction
+
+Capture, batch writes, imports, team pulls, and content rewrites derive a graph locally. Session-end summarization (including scan/watch) reads the same event text as the existing summarizer before summary line/token caps. Extraction always applies the built-in redaction rules, including when indexing legacy text. It never invokes a model or an external API.
+
+The rules recognize labeled speakers, explicit `person`, `project`, `tool`, `service`, and `file` names, common tools/services, and file paths with supported extensions. Short affirmative clauses such as `Alice works on project Atlas`, `Alice uses SQLite`, `Alice decided to use SQLite`, `Alice prefers Python`, and `Project Atlas is blocked by GitHub` yield `works_on`, `uses`, `decided`, `prefers`, and `blocked_by` edges. Decision clauses become decision entities. `Ran:` tool events yield `uses` for recognized executables; git commits also yield decisions, matching the existing local summarizer. Unlabeled first-person/imperative clauses use `user` (or `team` for `we`); labeled speakers resolve `I`. Questions, negation, hypothetical clauses, and unresolved third-person pronouns are skipped. These conservative rules are not general natural-language understanding and can miss or misclassify unfamiliar phrasing.
+
+Names use NFKC, lowercase, stripped quotes/possessives, and collapsed whitespace. This also folds file-path case. `memory_entities` stores unique `(memory_id, kind, name)` rows; `memory_relations` references both endpoints in the same memory. Updates replace derived rows atomically, and foreign keys cascade memory deletion and summary ID changes. Migration 014 backfills existing memories, using full events for summaries when available. Expired memories are excluded from graph reads and ranking. Export/import request and response formats are unchanged; graphs are rebuilt from imported content, so event-only details absent from an exported summary do not round-trip.
+
+`sessionmem entities --project <id>` lists entities and relations with source memory IDs; `--json` provides structured output. Omitting `--project` selects the current project.
+
+## Contradiction and supersession
+
+Migration 015 adds `memory_claims` and `memory_supersessions`. Claims use migration 014's canonical entity and typed-relation extractor, with a small grammar for `does not`, `no longer`, `stopped using`, `switched to/from`, and `replaced ... with`. A comparison requires the same entity and relation. Opposite polarity on the same value is a contradiction. Different positive values supersede one another when their lexical purpose overlaps (at least two words and Jaccard overlap 0.6, or an exact purpose), their tool category matches (editor, language, database, package manager, test runner), or a replacement explicitly names the old value. `now works on` also replaces a prior project. Different purposes, entities, or relation types remain independent. Questions, hypothetical statements, reported quotations, and unresolved pronouns are skipped. Rules are conservative heuristics and do not resolve arbitrary language or coreference.
+
+Each link records the old memory in `supersedes`, the replacement in `superseded_by`, both claim keys, the reason, the replacement assertion's `superseded_at`, and the wall-clock `detected_at`. Memory bodies, IDs, and importance are preserved. A derived `superseded_memories` view marks a memory fully superseded only when every extracted claim has a replacement. Independent claims in a mixed summary keep it searchable; its content can still contain stale claims, so inspect partial supersessions in history when auditing such summaries. No old memory is deleted by supersession; explicit deletion and retention keep their existing behavior.
+
+Writes reconcile only affected entity/relation groups within the same project, atomically with memory and graph updates. Assertions are ordered by their stored timestamp, then memory insertion rowid for equal timestamps. This gives pinned-clock captures a deterministic arrival order. The earliest later contradictory assertion supplies each link, permitting chains and later reaffirmations without cycles. Identical replay preserves links and detection timestamps; imports, content rewrites, summary ID changes, and deletion reconnect affected chains. Migration 015 backfills existing memories once, using full session events for summaries. Scan preserves valid original transcript timestamps, so filename order does not determine freshness. Without original timestamps, stored capture order is the fallback. An unrelated appended event does not change an earlier assertion's time.
+
+Recall filters fully superseded memories before the FTS candidate limit and fallback scan, giving current facts priority. The optional `includeHistory: true` request field, exposed as `sessionmem search --include-history`, restores normal relevance ranking across current and superseded memories. Existing requests and response shapes remain compatible. `getMemory`, list and export still expose earlier memories. `sessionmem history [--project <id>] [--json]` lists links with old/new values, timestamps, reasons, source IDs, and partial/full status. Export formats remain unchanged: importing rebuilds links from exported bodies and timestamps; event-only claims absent from a summary cannot round-trip.
+
+## Retrieval flow
+
+When an agent or `sessionmem search` submits a query, the core engine searches the SQLite FTS5 index over stored memory content, including summaries. It removes common English question words and matches any remaining term. SQLite's built-in Porter tokenizer matches English inflections such as “hike” and “hiking”. BM25 accounts for term rarity, frequency, and memory length; at most 50 lexical candidates are returned, ordered by BM25 and then ID.
+
+The ranker divides each positive BM25 score by the best score for that query. If the query contains known entity names in this project, relevance is `0.90 * base relevance + 0.10 * entity overlap`. Overlap is the fraction of distinct matched query names linked to the candidate memory; names are matched as literal token sequences (up to eight tokens), including lowercase questions. With no known query entities, relevance is unchanged. This reranks the existing candidates; it does not expand the FTS candidate pool or traverse relations. The outer relevance, recency, and importance weights stay 0.60, 0.25, and 0.15. Sparse lexical matches retain the recency/importance fallback union. If there are no lexical matches, base relevance uses the previous hash-vector ranking. Project scope and expiry checks apply to both paths. Automatic migrations preserve memory bodies and IDs.
+
+Existing public request fields and all response fields are unchanged; `includeHistory` is an optional addition. The `semantic` field still reports hash cosine similarity. The legacy `score.raw.semantic` and `score.weighted.semantic` fields carry the relevance component used for ranking, including entity overlap when query entities match. Scores are relative to the current query's candidates, not calibrated probabilities. Retrieval needs no API keys, downloaded models, or new dependencies.
+
+## 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,122 @@
+# Conversational retrieval benchmark
+
+`npm run benchmark` runs the committed LoCoMo corpus through the public
+`storeMemory` capture and `retrieveMemories` recall APIs. See
+[benchmarks/README.md](../benchmarks/README.md) for the corpus license, selection
+rules, metric definitions, and detailed reproduction instructions.
+
+## Entity overlap comparison
+
+The baseline was run first on current main at `81f987c`. A fixed 10% entity
+contribution inside the existing relevance component was then evaluated without
+a weight sweep. Both runs used Node v24.19.0, Linux x64, sessionmem 1.4.0, the
+same installed lockfile dependencies, top-5, fixed clocks, and the unchanged
+LoCoMo corpus and scoring rules. Each run scored 1,527 questions after capturing
+5,882 turns; both recorded zero network attempts.
+
+| Macro retrieval metric @5 | Main (BM25) | BM25 + entity overlap |
+| --- | ---: | ---: |
+| Hit rate | 61.95% | 63.92% |
+| Precision | 13.45% | 14.05% |
+| Recall | 55.96% | 57.45% |
+| All-evidence rate | 51.15% | 52.26% |
+
+| Recall latency | Main | Entity overlap |
+| --- | ---: | ---: |
+| Mean | 8.57 ms | 8.05 ms |
+| Median | 7.27 ms | 7.58 ms |
+| p95 | 21.04 ms | 14.94 ms |
+| Maximum | 35.81 ms | 28.38 ms |
+
+Entity overlap gained hits on 34 questions and lost hits on four, a net gain
+of 30. Precision and recall increased on 48 questions and decreased on five.
+The signal measurably improved retrieval on this corpus, so it is retained.
+Timing is one call per question without warmup and varies with load; the lower
+mean/p95 is not evidence that the added lookup makes retrieval faster. This
+does not establish generalization to other corpora or measure extraction accuracy.
+The rule vocabulary and fixed weight were not tuned against these results.
+
+[Recorded aggregate results](../benchmarks/entity-overlap-results.json) include
+the corpus checksum, shared configuration, runtime, category metrics, and paired
+question counts. To reproduce, run the commands below on `81f987c` with output
+`benchmarks/results/locomo-main.json`, then on this change with output
+`benchmarks/results/locomo-entities.json`. Full per-question reports remain ignored
+local artifacts.
+
+## Earlier BM25 comparison
+
+The baseline was run first on main at `c06857d`, before changing retrieval.
+Both runs used sessionmem 1.4.0, Node v24.19.0, Linux x64, top-5,
+and the same lockfile dependencies and fixed capture/retrieval clock.
+They captured 5,882 turns across 272 sessions in 10 conversations and scored
+1,527 questions. The same 446 adversarial, four missing-evidence, and nine
+invalid-evidence questions were excluded by fixed annotation rules.
+
+| Macro retrieval metric @5 | Main (hash ranking) | BM25 + stop words + stemming |
+| --- | ---: | ---: |
+| Hit rate | 1.44% | 61.95% |
+| Precision | 0.29% | 13.45% |
+| Recall | 0.88% | 55.96% |
+| All-evidence rate | 0.65% | 51.15% |
+
+| Recall latency | Main | Selected change |
+| --- | ---: | ---: |
+| Mean | 16.33 ms | 14.93 ms |
+| Median | 15.22 ms | 13.52 ms |
+| p95 | 28.80 ms | 28.81 ms |
+| Maximum | 133.49 ms | 56.73 ms |
+
+Latency includes the complete public service response, including startup-injection
+formatting, and excludes capture, process startup, and corpus loading. Each query
+is timed once without warmup. Timing depends on hardware and load.
+
+| Question category | Questions | Hit rate | Precision | Recall |
+| --- | ---: | ---: | ---: | ---: |
+| Multi-hop | 278 | 46.76% | 13.60% | 25.06% |
+| Temporal | 320 | 69.38% | 14.38% | 66.22% |
+| Open-domain | 89 | 38.20% | 8.09% | 28.25% |
+| Single-hop | 840 | 66.67% | 13.62% | 65.22% |
+
+## Candidate comparisons
+
+Each candidate was run with the existing offline evaluator on the same questions.
+Only additions that increased hit rate, precision, and recall were retained.
+
+| Candidate @5 | Hit rate | Precision | Recall |
+| --- | ---: | ---: | ---: |
+| BM25 with OR terms | 52.78% | 11.15% | 47.69% |
+| + English stop-word filtering | 57.69% | 12.39% | 52.62% |
+| + Porter stemming (selected) | 61.95% | 13.45% | 55.96% |
+| 90% BM25 / 10% hash cosine (discarded) | 61.76% | 13.43% | 55.78% |
+
+BM25 preserves lexical relevance instead of replacing it with hash-vector noise.
+Common question words no longer require a literal match, and SQLite's built-in
+Porter tokenizer matches English inflections. The existing recency, importance,
+expiry, project scope, and no-match vector fallback remain in place. There are
+no new dependencies, API keys, or model downloads. Migration 013 rebuilds the
+existing FTS index; memory content and IDs are preserved.
+
+These comparisons use the same corpus used to select the ranker; they are not
+a held-out generalization estimate. BM25 still needs lexical overlap, and a hit
+can leave evidence missing for multi-hop questions. These are annotated-evidence
+retrieval scores, not answer-generation accuracy or summarization quality.
+
+## Reproduce
+
+After installing the lockfile dependencies, run on main to record the baseline,
+then repeat on the change:
+
+```bash
+npm run build
+npm run benchmark -- --output benchmarks/results/locomo.json
+```
+
+The corpus is pinned to upstream commit
+`3eb6f2c585f5e1699204e3c3bdf7adc5c28cb376`, SHA-256
+`79fa87e90f04081343b8c8debecb80a9a6842b76a7aa537dc9fdf651ea698ff4`.
+The runner verifies this checksum and blocks network calls. No API keys are
+required. A second full run with an empty environment produced identical
+retrieved IDs and quality metrics for all 1,527 questions. JSON output includes
+every scored question, answer, evidence list, returned IDs, and exclusion reason
+so failures can be inspected. The report above is a recorded result; the command
+prints current results and writes JSON only when requested.

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,44 @@
+# 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.
+
+Migration `015_memory_supersessions.sql` adds derived fact claims, timestamped replacement links, and a view identifying fully superseded memories. It backfills existing records locally in the migration transaction, using full session events for summaries where available. Stored memory content and IDs are preserved. Recall then defaults to current facts; use `includeHistory: true` or `sessionmem search --include-history` to retrieve superseded facts, and `sessionmem history` to inspect their chains.
+
+### 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.