sessionmem 1.3.0 → 1.4.0

package/dist/cli/commands/run.js

@@ -1,19 +1,15 @@
 import { AdapterFactory } from "../../adapters/factory.js";
 import { mkdirSync, writeFileSync } from "fs";
-import { join } from "path";
-import { homedir } from "os";
+import { join, dirname } from "path";
 import { deriveProjectId } from "../projectId.js";
-import { expandTilde } from "../context.js";
+import { resolveDbPath } from "../context.js";
 export async function runMcpServer() {
     const adapter = AdapterFactory.detectAdapter();
-    // Startup diagnostics: written to ~/.sessionmem/logs/mcp.log
-    const logDir = join(homedir(), ".sessionmem", "logs");
+    // Keep diagnostics beside the selected database so an override never
+    // creates the default home directory just to write a log.
+    const dbPath = resolveDbPath();
+    const logDir = join(dirname(dbPath), "logs");
     const logPath = join(logDir, "mcp.log");
-    // Derive db path for diagnostics (mirrors context.ts defaultDbPath)
-    const envDbPath = process.env.SESSIONMEM_DB_PATH;
-    const dbPath = envDbPath && envDbPath.trim() !== ""
-        ? expandTilde(envDbPath)
-        : join(homedir(), ".sessionmem", "memories.db");
     // Derive project ID for diagnostics. Shares the exact derivation the server
     // uses (createCliContext → deriveProjectId) so the logged id never diverges
     // from the bucket the server actually serves.
@@ -21,8 +17,10 @@ export async function runMcpServer() {
     const adapterName = adapter.name;
     const logMessage = `[${new Date().toISOString()}] Started sessionmem | adapter=${adapterName} db=${dbPath} project=${projectId}\n`;
     try {
-        mkdirSync(logDir, { recursive: true });
-        writeFileSync(logPath, logMessage, { flag: "a" });
+        if (dbPath !== ":memory:") {
+            mkdirSync(logDir, { recursive: true });
+            writeFileSync(logPath, logMessage, { flag: "a" });
+        }
     }
     catch {
         // best-effort logging; ignore failures

package/dist/cli/commands/search.js

@@ -1,18 +1,22 @@
 import { createCliContext } from "../context.js";
 import { formatTable } from "../output.js";
-const DEFAULT_LIMIT = 20;
+const DEFAULT_LIMIT = 10;
 function coerceLimit(value) {
     if (value === undefined)
         return DEFAULT_LIMIT;
-    const parsed = Number.parseInt(String(value), 10);
-    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_LIMIT;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 100) {
+        throw new Error(`Invalid --limit "${value}": expected an integer from 1 to 100.`);
+    }
+    return parsed;
 }
 export async function searchCommand(query, options = {}, ctx) {
+    const limit = coerceLimit(options.limit);
     const context = ctx ?? createCliContext();
     const result = await context.service.call("retrieveMemories", {
         projectId: context.projectId,
         query,
-        limit: coerceLimit(options.limit),
+        limit,
         mode: "auto",
         depth: "default",
     });

package/dist/cli/commands/uninstall.js

@@ -1,6 +1,7 @@
 import { existsSync, rmSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
+import { resolveDbPath } from "../context.js";
 import { AdapterFactory } from "../../adapters/factory.js";
 import { removeClaudeMdBlock } from "../../adapters/claudeMdInjector.js";
 /**
@@ -51,7 +52,7 @@ export async function uninstallCommand(options = {}) {
         }
     }
     // Resolve dbPath: use injected override (for tests) or the default location
-    const dbPath = options.dbPath ?? join(homedir(), ".sessionmem", "memories.db");
+    const dbPath = resolveDbPath(options.dbPath);
     if (options.purge) {
         // --purge: delete only memories.db, not logs or the ~/.sessionmem directory
         if (existsSync(dbPath)) {

package/dist/cli/context.js

@@ -42,19 +42,21 @@ export function expandTilde(p) {
     }
     return p;
 }
-function defaultDbPath(dir) {
+export function resolveDbPath(override) {
+    if (override !== undefined)
+        return expandTilde(override);
     // Env override seam (see deriveProjectId). Defaults to ~/.sessionmem/memories.db.
     const envDbPath = process.env.SESSIONMEM_DB_PATH;
     if (envDbPath && envDbPath.trim() !== "")
         return expandTilde(envDbPath);
-    // `dir` is the fixed ~/.sessionmem dir computed above, not user input.
     // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
-    return join(dir, "memories.db");
+    return join(homedir(), ".sessionmem", "memories.db");
 }
 export function createCliContext(overrides = {}) {
-    const dir = join(homedir(), ".sessionmem");
-    mkdirSync(dir, { recursive: true });
-    const dbPath = overrides.dbPath ?? defaultDbPath(dir);
+    const dbPath = resolveDbPath(overrides.dbPath);
+    if (!overrides.db && dbPath !== ":memory:") {
+        mkdirSync(dirname(dbPath), { recursive: true });
+    }
     const here = dirname(fileURLToPath(import.meta.url));
     const migrationsDir = overrides.migrationsDir ?? join(here, "..", "core", "schema", "migrations");
     const username = overrides.username ?? localUsername();

package/dist/cli/index.js

@@ -30,7 +30,7 @@ import { browseCommand } from "./commands/browse.js";
 // "../../package.json" specifier resolves to the package root.
 const pkg = createRequire(import.meta.url)("../../package.json");
 const program = new Command();
-program.name("sessionmem").version(pkg.version);
+program.name("sessionmem").description("Local-first memory for MCP coding agents").version(pkg.version);
 program
     .command("run")
     .description("Start the sessionmem MCP server")
@@ -74,15 +74,15 @@ program
 program
     .command("search <query>")
     .description("Search memories by semantic query")
-    .option("--limit <n>", "Maximum number of results", "10")
+    .option("--limit <n>", "Maximum number of results (1-100)", "10")
     .action((query, options) => searchCommand(query, options));
 program
     .command("list")
-    .description("List all memories for the current project")
+    .description("List up to 200 recent memories for the current project")
     .action(() => listCommand());
 program
     .command("show <id>")
-    .description("Show full details of a memory by ID")
+    .description("Show memory details by ID (content capped at 2000 characters)")
     .action((id) => showCommand(id));
 program
     .command("forget <id>")
@@ -96,7 +96,7 @@ program
 program
     .command("import <path>")
     .description("Import memories from a JSON file")
-    .option("--merge", "Overwrite existing memories with imported data")
+    .option("--merge", "Merge new records; existing IDs are preserved")
     .action((path, options) => importCommand(path, options));
 program
     .command("stats")
@@ -171,7 +171,7 @@ program
     .command("dedupe")
     .description("Find and optionally remove near-duplicate memories")
     .option("--apply", "Delete the lower-importance duplicate in each pair (default: dry-run)")
-    .option("--threshold <n>", "Cosine similarity threshold 0-1 (default: 0.85)")
+    .option("--threshold <n>", "Cosine similarity threshold >0 to 1 (default: 0.85)")
     .action((options) => dedupeCommand({ dry: !options.apply, threshold: options.threshold }));
 // browse — cross-project memory viewer.
 program

package/dist/core/config/policyConfig.js

@@ -88,7 +88,11 @@ export function readPolicyConfig(filePath) {
     let obj;
     try {
         raw = readFileSync(filePath, "utf8");
-        obj = JSON.parse(raw);
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return { ...DEFAULT_POLICY_CONFIG };
+        }
+        obj = parsed;
     }
     catch {
         return { ...DEFAULT_POLICY_CONFIG };

package/dist/core/injection/tokenBudget.js

@@ -10,8 +10,16 @@ export function capTokens(text, cap) {
     if (tokens.length <= cap) {
         return text;
     }
-    const trimmed = encoding.decode(tokens.slice(0, cap)).trimEnd();
-    return `${trimmed} ...`;
+    // Reserve room for the truncation marker, then verify the re-encoded text:
+    // token boundaries can change when a decoded prefix and suffix are joined.
+    const suffix = " ...";
+    for (let keep = Math.max(0, Math.floor(cap) - countTokens(suffix)); keep >= 0; keep--) {
+        const trimmed = encoding.decode(tokens.slice(0, keep)).trimEnd();
+        const result = trimmed ? `${trimmed}${suffix}` : suffix.trim();
+        if (countTokens(result) <= cap)
+            return result;
+    }
+    return "";
 }
 export function trimLowestPriorityContent(included, options = {}) {
     const minContentTokens = options.minContentTokens ?? DEFAULT_MIN_CONTENT_TOKENS;

package/dist/core/schema/runMigrations.js

@@ -57,18 +57,19 @@ export function runMigrations(db, migrationsDir = DEFAULT_MIGRATIONS_DIR) {
     const hasMigrationStmt = db.prepare("SELECT name FROM _migrations WHERE name = ? LIMIT 1");
     const insertMigrationStmt = db.prepare("INSERT INTO _migrations(name) VALUES (?)");
     const runMigration = db.transaction((fileName) => {
+        if (hasMigrationStmt.get(fileName))
+            return;
         const filePath = path.join(migrationsDir, fileName);
         const sql = fs.readFileSync(filePath, "utf8");
         db.exec(sql);
         insertMigrationStmt.run(fileName);
     });
     for (const fileName of files) {
-        const existing = hasMigrationStmt.get(fileName);
-        if (existing) {
+        if (hasMigrationStmt.get(fileName))
             continue;
-        }
         try {
-            runMigration(fileName);
+            // Serialize the check and apply across processes opening the same DB.
+            runMigration.immediate(fileName);
         }
         catch (err) {
             // Idempotency guard for ALTER TABLE ADD COLUMN migrations (005/006).
@@ -90,7 +91,10 @@ export function runMigrations(db, migrationsDir = DEFAULT_MIGRATIONS_DIR) {
                 const filePath = path.join(migrationsDir, fileName);
                 const sql = fs.readFileSync(filePath, "utf8");
                 if (allAddedColumnsExist(db, sql)) {
-                    insertMigrationStmt.run(fileName);
+                    db.transaction(() => {
+                        if (!hasMigrationStmt.get(fileName))
+                            insertMigrationStmt.run(fileName);
+                    }).immediate();
                     continue;
                 }
             }

package/dist/core/storage/db.js

@@ -2,13 +2,35 @@ import BetterSqlite3 from "better-sqlite3";
 import { runMigrations } from "../schema/runMigrations.js";
 export function openDb(options = {}) {
     const db = new BetterSqlite3(options.dbPath ?? ":memory:");
-    // Performance pragmas — WAL enables concurrent reads during writes;
-    // busy_timeout prevents SQLITE_BUSY under concurrent MCP tool calls.
-    db.pragma("journal_mode = WAL");
-    db.pragma("synchronous = NORMAL");
-    db.pragma("foreign_keys = ON");
-    db.pragma("busy_timeout = 5000");
-    db.pragma("cache_size = -32000");
-    runMigrations(db, options.migrationsDir);
-    return db;
+    try {
+        // Performance pragmas — WAL enables concurrent reads during writes;
+        // busy_timeout prevents SQLITE_BUSY under concurrent MCP tool calls.
+        // Concurrent first opens can race while switching to WAL. SQLite may
+        // bypass the busy handler for this lock upgrade, so retry within the same
+        // five-second budget used for normal writes.
+        const deadline = Date.now() + 5000;
+        const pause = new Int32Array(new SharedArrayBuffer(4));
+        for (;;) {
+            try {
+                db.pragma("journal_mode = WAL");
+                break;
+            }
+            catch (err) {
+                if (!(err instanceof Error) || !("code" in err) || err.code !== "SQLITE_BUSY" || Date.now() >= deadline) {
+                    throw err;
+                }
+                Atomics.wait(pause, 0, 0, 10);
+            }
+        }
+        db.pragma("synchronous = NORMAL");
+        db.pragma("foreign_keys = ON");
+        db.pragma("busy_timeout = 5000");
+        db.pragma("cache_size = -32000");
+        runMigrations(db, options.migrationsDir);
+        return db;
+    }
+    catch (err) {
+        db.close();
+        throw err;
+    }
 }

package/dist/core/summarize/cloudSummarizer.js

@@ -1,4 +1,5 @@
 import Anthropic from "@anthropic-ai/sdk";
+import { capTokens } from "../injection/tokenBudget.js";
 import { summarizeLocalSessionEvents } from "./localSummarizer.js";
 import { DEFAULT_SUMMARIZER_MODEL } from "../config/policyConfig.js";
 const CLOUD_SYSTEM_PROMPT = "You are a memory compressor for AI coding sessions. Given this session transcript summary, produce a compact, high-signal list of facts, decisions, and context that should be remembered. Be extremely concise.";
@@ -26,7 +27,7 @@ export async function summarizeWithCloud(input) {
         messages: [{ role: "user", content: localResult.summary }],
     });
     // Extract text from response content blocks
-    let text = response.content
+    const text = response.content
         .filter((block) => block.type === "text")
         .map((block) => block.text)
         .join("\n");
@@ -35,14 +36,8 @@ export async function summarizeWithCloud(input) {
     if (!text || text.trim().length === 0) {
         throw new Error("Cloud summarizer returned empty response");
     }
-    // Cap cloud output to summaryTokenCap (rough token→char ratio) for parity
-    // with the local summarizer, so a verbose cloud response cannot blow past the
-    // configured budget.
-    if (input.summaryTokenCap && text.length > input.summaryTokenCap * 4) {
-        text = text.slice(0, input.summaryTokenCap * 4);
-    }
     return {
-        summary: text,
+        summary: capTokens(text, input.summaryTokenCap),
         warningCodes: localResult.warningCodes,
     };
 }

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
+```