sessionmem 1.5.0 → 1.7.0

package/dist/core/api/memoryCoreService.js

@@ -1,6 +1,8 @@
 import { userInfo } from "node:os";
 import { ZodError } from "zod";
 import { deterministicEmbed } from "../embed/deterministicEmbed.js";
+import { loadLocalSemanticEmbedder } from "../embed/localSemanticEmbedder.js";
+import { indexSemanticMemories, searchSemanticMemories } from "../storage/semanticSearchRepo.js";
 import { retrieveMemories } from "../retrieve/retrieveMemories.js";
 import { computeEffectiveImportance } from "../retrieve/score.js";
 import { formatStartupInjection } from "../injection/formatStartupInjection.js";
@@ -150,6 +152,21 @@ export function createMemoryCoreService(deps) {
     // Resolve the local author identity once per service instance.
     const localAuthor = resolveServiceUsername(deps.username);
     const policyConfigPath = deps.policyConfigPath ?? configFilePath();
+    let semanticWarningShown = false;
+    async function semanticEmbedder() {
+        if (!readPolicyConfig(policyConfigPath).semanticSearch)
+            return null;
+        const embedder = deps.semanticEmbedder === undefined ? await loadLocalSemanticEmbedder() : deps.semanticEmbedder;
+        if (!embedder)
+            semanticWarning();
+        return embedder;
+    }
+    function semanticWarning() {
+        if (!semanticWarningShown) {
+            console.error("Local semantic retrieval unavailable; using BM25.");
+            semanticWarningShown = true;
+        }
+    }
     /**
      * Resolve the effective redactionEnabled flag using precedence
      * override (explicit per-request value) > config.json > default,
@@ -208,7 +225,7 @@ export function createMemoryCoreService(deps) {
                         event_type: event.eventType,
                         payload_json: redactedPayload,
                         created_at: event.createdAt,
-                    });
+                    }, parsed.replaceExisting);
                 }
                 return written;
             });
@@ -299,6 +316,15 @@ export function createMemoryCoreService(deps) {
             if (!inserted) {
                 throw new DomainError("INTERNAL", "Memory insert did not persist");
             }
+            // Optional indexing never turns a successful durable capture into a failure.
+            try {
+                const embedder = await semanticEmbedder();
+                if (embedder)
+                    await indexSemanticMemories(db, parsed.projectId, embedder, parsed.memoryId);
+            }
+            catch {
+                semanticWarning();
+            }
             return {
                 ok: true,
                 // Single-record write echo-back: return the FULL stored body (uncapped),
@@ -314,6 +340,15 @@ export function createMemoryCoreService(deps) {
         async retrieveMemories(request) {
             const parsed = parseRequest(retrieveMemoriesRequestSchema, request);
             const limit = parsed.depth === "deep" ? Math.min(parsed.limit * 2, DEEP_MODE_RETRIEVAL_CAP) : parsed.limit;
+            let semanticCandidates;
+            try {
+                const embedder = await semanticEmbedder();
+                if (embedder)
+                    semanticCandidates = await searchSemanticMemories(db, parsed.projectId, parsed.query, deps.now?.() ?? new Date(), parsed.includeHistory ?? false, embedder);
+            }
+            catch {
+                semanticWarning();
+            }
             const rankedAll = retrieveMemories({
                 db,
                 projectId: parsed.projectId,
@@ -321,6 +356,7 @@ export function createMemoryCoreService(deps) {
                 includeHistory: parsed.includeHistory,
                 limit,
                 now: deps.now?.(),
+                semanticCandidates,
             });
             // Optional tag filter: keep a memory only when its stored tags contain ALL
             // requested tags. The semantic candidate projection omits tags, so re-read

package/dist/core/capture/toolEvent.js

@@ -61,16 +61,17 @@ function describeToolUse(toolName, input) {
  * structured input and keep only the human-readable summary rather than
  * emitting truncated — and therefore unparseable — JSON.
  */
-function buildPayloadJson(toolName, text, input, cwd) {
+function buildPayloadJson(toolName, text, input, cwd, callId) {
     const full = JSON.stringify({
         tool: toolName,
         text,
         input: shrinkValue(input),
         cwd,
+        ...(callId ? { call_id: callId } : {}),
     });
     if (full.length <= MAX_HOOK_PAYLOAD_CHARS)
         return full;
-    return JSON.stringify({ tool: toolName, text, cwd, truncated: true });
+    return JSON.stringify({ tool: toolName, text, cwd, ...(callId ? { call_id: callId } : {}), truncated: true });
 }
 export function buildToolEvent(toolName, input, cwd) {
     if (!CAPTURED_TOOL_TYPES.has(toolName))
@@ -80,3 +81,14 @@ export function buildToolEvent(toolName, input, cwd) {
         payloadJson: buildPayloadJson(toolName, describeToolUse(toolName, input), input, cwd),
     };
 }
+/** Codex function calls retain their native name and call ID. */
+export function buildFunctionCallEvent(name, input, callId, cwd) {
+    const command = input.command ?? input.cmd;
+    const text = ["exec_command", "shell_command", "shell"].includes(name)
+        ? describeToolUse("Bash", { command: Array.isArray(command) ? command.join(" ") : command })
+        : CAPTURED_TOOL_TYPES.has(name) ? describeToolUse(name, input) : truncate(`Called ${name}`, MAX_TEXT_CHARS);
+    return {
+        eventType: `tool_use:${name.toLowerCase()}`,
+        payloadJson: buildPayloadJson(name, text, input, cwd, callId),
+    };
+}

package/dist/core/config/policyConfig.js

@@ -53,6 +53,7 @@ const policyConfigShape = {
     // built-in DEFAULT_INJECTION_CAP used by formatStartupInjection and the
     // `savings` analytics. Omitted by default so existing configs keep the default.
     injectionCap: z.number().int().min(100).max(10000).optional(),
+    semanticSearch: z.boolean().optional(),
     team: teamConfigShape.default({ enabled: false }),
 };
 /**
@@ -107,11 +108,13 @@ export function readPolicyConfig(filePath) {
     const rd = s.retentionDays.safeParse(obj.retentionDays);
     const re = s.redactionEnabled.safeParse(obj.redactionEnabled);
     const ic = s.injectionCap.safeParse(obj.injectionCap);
+    const ss = s.semanticSearch.safeParse(obj.semanticSearch);
     const tm = s.team.safeParse(obj.team);
     return {
         retentionDays: rd.success ? rd.data : DEFAULT_POLICY_CONFIG.retentionDays,
         redactionEnabled: re.success ? re.data : DEFAULT_POLICY_CONFIG.redactionEnabled,
         injectionCap: ic.success ? ic.data : undefined,
+        semanticSearch: ss.success ? ss.data : undefined,
         team: tm.success ? tm.data : { ...DEFAULT_POLICY_CONFIG.team },
     };
 }

package/dist/core/embed/localSemanticEmbedder.js

@@ -0,0 +1,62 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+const MODEL_SHA = "6fd5d72fe4589f189f8ebc006442dbb529bb7ce38f8082112682524616046452";
+const TOKENIZER_SHA = "be50c3628f2bf5bb5e3a7f17b1f74611b2561a3a27eeab05e5aa30f411572037";
+export const LOCAL_SEMANTIC_MODEL = `minilm-l6-v2:${MODEL_SHA}:${TOKENIZER_SHA}:mean256-v1`;
+let loaded;
+/** Only local package files are opened. No download or remote provider path. */
+export function loadLocalSemanticEmbedder() {
+    return loaded ??= load().catch(() => null);
+}
+async function load() {
+    const require = createRequire(import.meta.url);
+    const model = require.resolve("@xcidos/genesis-memory-model/onnx/model.onnx");
+    const tokenizerPath = require.resolve("@xcidos/genesis-memory-model/tokenizer.json");
+    for (const [file, expected] of [[model, MODEL_SHA], [tokenizerPath, TOKENIZER_SHA]]) {
+        if (createHash("sha256").update(readFileSync(file)).digest("hex") !== expected) {
+            throw new Error("Local semantic model checksum mismatch");
+        }
+    }
+    // ORT 1.30 can initialize a native HTTP telemetry uploader on POSIX.
+    // Its full opt-out must be set before the native environment is created;
+    // JavaScript network guards cannot intercept native library sockets.
+    process.env.ORT_DISABLE_TELEMETRY = "1";
+    const ort = await import("onnxruntime-node");
+    const { Tokenizer } = await import("@huggingface/tokenizers");
+    const tokenizer = new Tokenizer(JSON.parse(readFileSync(tokenizerPath, "utf8")), {});
+    const session = await ort.InferenceSession.create(model, {
+        executionProviders: ["cpu"], intraOpNumThreads: 1, interOpNumThreads: 1,
+        logSeverityLevel: 3,
+    });
+    return {
+        id: LOCAL_SEMANTIC_MODEL, dimension: 384,
+        async embed(text) {
+            let ids = tokenizer.encode(text).ids;
+            if (ids.length > 256)
+                ids = [...ids.slice(0, 255), 102]; // retain BERT's SEP
+            const input = new ort.Tensor("int64", BigInt64Array.from(ids, BigInt), [1, ids.length]);
+            const ones = new ort.Tensor("int64", new BigInt64Array(ids.length).fill(1n), [1, ids.length]);
+            const zeros = new ort.Tensor("int64", new BigInt64Array(ids.length), [1, ids.length]);
+            let output;
+            try {
+                output = await session.run({ input_ids: input, attention_mask: ones, token_type_ids: zeros });
+                const hidden = output.last_hidden_state.data;
+                const vector = new Array(384).fill(0);
+                for (let token = 0; token < ids.length; token++) {
+                    for (let dim = 0; dim < 384; dim++)
+                        vector[dim] += hidden[token * 384 + dim] / ids.length;
+                }
+                const norm = Math.hypot(...vector);
+                return vector.map(v => v / (norm || 1));
+            }
+            finally {
+                input.dispose();
+                ones.dispose();
+                zeros.dispose();
+                for (const tensor of Object.values(output ?? {}))
+                    tensor.dispose();
+            }
+        },
+    };
+}

package/dist/core/retrieve/retrieveMemories.js

@@ -47,7 +47,16 @@ export function retrieveMemories(input) {
     const now = input.now ?? new Date();
     // FTS5 retrieves up to 50 BM25 matches; sparse matches retain the existing
     // recency/importance fallback. The public request schema validates queryText.
-    const candidates = searchMemoryCandidatesFTS(input.db, input.projectId, queryText, now, input.includeHistory);
+    const lexicalCandidates = searchMemoryCandidatesFTS(input.db, input.projectId, queryText, now, input.includeHistory);
+    const candidates = [...lexicalCandidates];
+    const ids = new Set(candidates.map(c => c.id));
+    for (const { candidate } of input.semanticCandidates ?? []) {
+        if (!ids.has(candidate.id)) {
+            candidates.push(candidate);
+            ids.add(candidate.id);
+        }
+    }
+    const dense = new Map(input.semanticCandidates?.map(c => [c.candidate.id, c.similarity]));
     const decayedCandidates = decayOldBoosts(candidates, now);
     const dimension = resolveEmbeddingDimension(candidates);
     const queryVector = deterministicEmbed(queryText, dimension).vector;
@@ -68,9 +77,16 @@ export function retrieveMemories(input) {
             : cosineSimilarity(queryVector, candidate.embedding);
         // Hash cosine is useful for identical text, but adds noise to lexical
         // matches. Keep it as a diagnostic and as the no-match fallback only.
-        const baseRelevance = maxLexicalScore > 0
+        const lexicalRelevance = maxLexicalScore > 0
             ? candidate.lexical_score / maxLexicalScore
             : semantic;
+        // The local dense variant was weaker alone. Preserve lexical dominance
+        // while admitting candidates absent from FTS, using a fixed 2:1 blend.
+        const baseRelevance = input.semanticCandidates?.length
+            ? maxLexicalScore > 0
+                ? (2 * lexicalRelevance + Math.max(0, dense.get(candidate.id) ?? 0)) / 3
+                : Math.max(0, dense.get(candidate.id) ?? 0)
+            : lexicalRelevance;
         const relevance = overlap.size > 0
             ? (1 - ENTITY_RELEVANCE_WEIGHT) * baseRelevance + ENTITY_RELEVANCE_WEIGHT * (overlap.get(candidate.id) ?? 0)
             : baseRelevance;

package/dist/core/schema/migrations/016_semantic_embeddings.sql

@@ -0,0 +1,12 @@
+-- Separate learned vectors from legacy hash embeddings. Models never mix.
+CREATE TABLE semantic_embeddings (
+  memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE ON UPDATE CASCADE,
+  model TEXT NOT NULL,
+  dimension INTEGER NOT NULL CHECK (dimension > 0),
+  vector BLOB NOT NULL,
+  PRIMARY KEY (memory_id, model)
+);
+CREATE TRIGGER semantic_embeddings_content_update AFTER UPDATE OF content ON memories
+WHEN old.content IS NOT new.content BEGIN
+  DELETE FROM semantic_embeddings WHERE memory_id = new.id;
+END;

package/dist/core/storage/memorySearchRepo.js

@@ -91,6 +91,17 @@ function mapRows(rows) {
         };
     });
 }
+/** Hydrate a bounded semantic candidate list under the same visibility rules. */
+export function searchMemoryCandidatesByIds(db, projectId, ids, now, includeHistory = false) {
+    if (!ids.length)
+        return [];
+    const rows = db.prepare(`SELECT * FROM memories WHERE project_id = ?
+    AND id IN (${ids.map(() => "?").join(",")})
+    AND (expires_at IS NULL OR expires_at > ?)
+    AND (? = 1 OR id NOT IN (SELECT memory_id FROM superseded_memories))`)
+        .all(projectId, ...ids, now.toISOString(), Number(includeHistory));
+    return mapRows(rows);
+}
 export function searchMemoryCandidates(db, projectId, now = new Date(), includeHistory = false) {
     const rows = getSearchStatements(db).searchCandidates.all({
         projectId,

package/dist/core/storage/semanticSearchRepo.js

@@ -0,0 +1,56 @@
+import { searchMemoryCandidatesByIds } from "./memorySearchRepo.js";
+function normalize(vector, dimension) {
+    if (vector.length !== dimension || !vector.every(Number.isFinite))
+        throw new Error("Invalid local embedding");
+    const norm = Math.hypot(...vector);
+    if (!norm)
+        throw new Error("Empty local embedding");
+    return vector.map(v => v / norm);
+}
+/** Backfill from stored text after normal capture policy; never raw capture input. */
+export async function indexSemanticMemories(db, projectId, embedder, memoryId) {
+    const rows = db.prepare(`SELECT m.id, m.content FROM memories m
+    WHERE m.project_id = ? AND (? IS NULL OR m.id = ?) AND NOT EXISTS (SELECT 1 FROM semantic_embeddings s
+      WHERE s.memory_id = m.id AND s.model = ? AND s.dimension = ?)`)
+        .all(projectId, memoryId ?? null, memoryId ?? null, embedder.id, embedder.dimension);
+    const insert = db.prepare(`INSERT OR REPLACE INTO semantic_embeddings(memory_id, model, dimension, vector)
+    SELECT id, @model, @dimension, @vector FROM memories
+    WHERE id = @id AND project_id = @project AND content = @content`);
+    for (const row of rows) {
+        const vector = normalize(await embedder.embed(row.content), embedder.dimension);
+        const bytes = Buffer.alloc(vector.length * 4);
+        vector.forEach((v, i) => bytes.writeFloatLE(v, i * 4));
+        // A concurrent edit/delete during inference must not install stale vectors.
+        insert.run({ ...row, model: embedder.id, dimension: embedder.dimension, vector: bytes, project: projectId });
+    }
+}
+/** Exact local cosine scan. Appropriate to small project stores; no ANN service. */
+export async function searchSemanticMemories(db, projectId, query, now, includeHistory, embedder) {
+    await indexSemanticMemories(db, projectId, embedder);
+    const vector = normalize(await embedder.embed(query), embedder.dimension);
+    const rows = db.prepare(`SELECT s.memory_id, s.vector FROM semantic_embeddings s JOIN memories m ON m.id = s.memory_id
+    WHERE m.project_id = @project AND s.model = @model AND s.dimension = @dimension
+      AND (m.expires_at IS NULL OR m.expires_at > @now)
+      AND (@history = 1 OR m.id NOT IN (SELECT memory_id FROM superseded_memories))`)
+        .all({ project: projectId, model: embedder.id, dimension: embedder.dimension, now: now.toISOString(), history: Number(includeHistory) });
+    const scored = [];
+    for (const row of rows) {
+        if (row.vector.length !== vector.length * 4)
+            continue;
+        let similarity = 0, norm = 0;
+        for (let i = 0; i < vector.length; i++) {
+            const value = row.vector.readFloatLE(i * 4);
+            similarity += value * vector[i];
+            norm += value * value;
+        }
+        if (Number.isFinite(similarity) && norm > 0)
+            scored.push({ id: row.memory_id, similarity: Math.max(-1, Math.min(1, similarity / Math.sqrt(norm))) });
+    }
+    scored.sort((a, b) => b.similarity - a.similarity || a.id.localeCompare(b.id));
+    const top = scored.slice(0, 50);
+    const candidates = new Map(searchMemoryCandidatesByIds(db, projectId, top.map(r => r.id), now, includeHistory).map(c => [c.id, c]));
+    return top.flatMap(row => {
+        const candidate = candidates.get(row.id);
+        return candidate ? [{ candidate, similarity: row.similarity }] : [];
+    });
+}

package/dist/core/storage/sessionEventsRepo.js

@@ -4,6 +4,11 @@ function getSessionEventsStatements(db) {
     if (stmts)
         return stmts;
     stmts = {
+        updateEvent: db.prepare(`
+      UPDATE session_events SET event_type = @event_type, payload_json = @payload_json
+      WHERE id = @id AND project_id = @project_id AND session_id = @session_id
+        AND (event_type != @event_type OR payload_json != @payload_json)
+    `),
         // INSERT OR IGNORE so re-ingesting an event with the same logical key
         // (project_id, session_id, event_index) — now a UNIQUE index, migration 009
         // — is a no-op rather than a duplicate row or a PK error.
@@ -34,10 +39,14 @@ function getSessionEventsStatements(db) {
 /**
  * Insert a session event. Returns the number of rows written (1, or 0 when the
  * (project_id, session_id, event_index) key already exists and the insert was
- * ignored).
+ * ignored). Mutable transcript imports can opt in to refreshing the content of
+ * an existing ID in the same project/session, preserving its index and date.
+ * Returns 1 for either an insertion or a content update; unchanged replays are 0.
  */
-export function insertSessionEvent(db, input) {
-    return getSessionEventsStatements(db).insertEvent.run(input).changes;
+export function insertSessionEvent(db, input, replaceExisting = false) {
+    const statements = getSessionEventsStatements(db);
+    const updated = replaceExisting ? statements.updateEvent.run(input).changes : 0;
+    return updated + statements.insertEvent.run(input).changes;
 }
 /**
  * Next free `event_index` for a session (max + 1, or 0 when the session has no

package/docs/architecture.md

@@ -70,7 +70,19 @@ When an agent or `sessionmem search` submits a query, the core engine searches t
 
 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.
+Existing public request fields and all response fields are unchanged; `includeHistory` is an optional addition. With default retrieval, the `semantic` field 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. Default retrieval needs no API keys, downloaded models, or new dependencies.
+
+With `semanticSearch=true` and the optional local packages installed, migration
+016 stores versioned learned vectors separately from hash embeddings. Retrieval
+unions up to 50 exact-cosine semantic candidates with lexical candidates, blends
+normalized BM25 and positive cosine 2:1, and retains the existing entity and outer
+scoring weights. With no lexical match it uses cosine relevance. The `semantic`
+field remains the legacy hash diagnostic, matching `embeddingDim` and
+`embeddingVersion`; learned cosine contributes to ranking. The same project,
+expiry, and supersession checks apply. Edits invalidate vectors and deletes
+cascade; missing vectors are backfilled from stored redacted content. This path
+does not change contradiction rules. Model loading/inference errors restore the
+default retrieval path. See [installation and limitations](local-semantic.md).
 
 ## Injection flow
 

package/docs/benchmark.md

@@ -5,6 +5,15 @@
 [benchmarks/README.md](../benchmarks/README.md) for the corpus license, selection
 rules, metric definitions, and detailed reproduction instructions.
 
+## Local semantic and competitor comparison
+
+The [measured comparison](../COMPARISON.md) records a new unchanged-main run,
+local raw-turn retrieval variants from claude-mem, Mem0 OSS, Graphiti and cognee,
+and the optional MiniLM hybrid. It includes exact commands and commits, complete
+per-question archives, latency costs and regressions. These component scores do
+not evaluate full capture/graph/answer pipelines. The comparisons below are
+earlier changes on earlier commits; their timings are not the new baseline.
+
 ## Entity overlap comparison
 
 The baseline was run first on current main at `81f987c`. A fixed 10% entity

package/docs/local-semantic.md

@@ -0,0 +1,56 @@
+# Optional local semantic retrieval
+
+The default is BM25 plus entity overlap. To add a learned semantic candidate pool,
+install the optional packages beside sessionmem and enable it:
+
+```bash
+ONNXRUNTIME_NODE_INSTALL=skip npm install sessionmem @huggingface/tokenizers@0.2.0 onnxruntime-node@1.30.0 @xcidos/genesis-memory-model@0.1.0-alpha.1
+npx sessionmem config set semanticSearch true
+```
+
+For a global sessionmem installation, use `npm install -g` for the same packages.
+`ONNXRUNTIME_NODE_INSTALL=skip` skips optional CUDA downloads; the npm package
+already contains the CPU runtime. On PowerShell set
+`$env:ONNXRUNTIME_NODE_INSTALL = 'skip'` before the install command.
+Developers should also use that variable with `npm ci` to avoid CUDA downloads.
+Disable semantic retrieval with `sessionmem config set semanticSearch false`.
+
+Installation fetches packages and weights. Capture and retrieval only load files
+from these installed packages; they never download a model, contact a model
+server, or send memory text over a network. Missing packages, checksum mismatches,
+unsupported native runtimes, and inference errors fall back to BM25 and emit one
+diagnostic per service instance. Restart after installing or repairing packages.
+Before loading ONNX Runtime, sessionmem sets the process-wide
+`ORT_DISABLE_TELEMETRY=1` to suppress its native POSIX telemetry uploader.
+The benchmark's `--semantic` mode instead fails if the model cannot load, to
+prevent accidentally publishing fallback scores as semantic results.
+
+The encoder is sentence-transformers/all-MiniLM-L6-v2: 384 dimensions, mean pooling,
+L2 normalization, and at most 256 WordPiece tokens. Its weights and tokenizer come
+from the pinned npm distribution above, whose provenance names upstream revision
+`c9745ed1d9f207416be6d2e6f8de32d1f16199bf`. Both files are SHA-256 checked before
+loading. The model is by the sentence-transformers contributors, distributed under
+[Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0); see
+[model information](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2)
+and the package's provenance README. No competitor code or prompt is included.
+
+Learned vectors are a separate SQLite BLOB index, keyed by memory and complete
+model/tokenizer/pooling version. Content edits invalidate vectors; deletes cascade.
+Only stored text is embedded, after the configured capture redaction policy.
+Capture through `storeMemory` indexes it immediately. Existing memories are
+embedded as stored; other write paths are backfilled
+on the next semantic query, so the first query on a large existing store can be
+slow. Model initialization and indexing cost are distinct from warm retrieval.
+
+Queries perform an exact local cosine scan, take up to 50 semantic candidates,
+and union them with FTS candidates. Project, expiry, and supersession filters
+apply to both channels; `includeHistory` explicitly includes superseded rows.
+Normalized BM25 relevance and positive cosine are blended 2:1 before the existing
+entity, recency, importance, and access signals. With no lexical match, cosine
+supplies relevance. This weighting follows the measured weakness of dense-only
+retrieval; it is not a held-out optimum. Read the measured regressions in
+[the comparison](../COMPARISON.md).
+
+Exact scans are intended for small project stores and scale linearly with the
+number of vectors. Long memories are truncated to the encoder's token window;
+no new chunking or model-based contradiction resolution is implemented.

package/docs/research/automatic-capture.md

@@ -0,0 +1,62 @@
+# Automatic transcript capture
+
+Research reviewed on October 18, 2026, before implementation. This change adopts
+approaches only. No competitor source code was copied or adapted.
+
+| Project and primary sources | Observed approach | Takeaway for sessionmem |
+| --- | --- | --- |
+| [claude-mem hooks](https://github.com/thedotmack/claude-mem/blob/main/plugin/hooks/hooks.json), [worker service](https://github.com/thedotmack/claude-mem/blob/main/docs/public/architecture/worker-service.mdx) | SessionStart starts a worker; async tool and stop hooks enqueue capture. The worker exposes health checks and separate start, stop, status and log controls. | Start capture automatically, keep explicit controls, and diagnose capture independently of registration. Keep the existing Claude Code hooks. |
+| [Mem0 Claude Code plugin](https://github.com/mem0ai/mem0/blob/main/integrations/claude-code-plugin/README.md), [OpenClaw integration](https://github.com/mem0ai/mem0/blob/main/integrations/openclaw/README.md) | Hooks save local evidence; detached workers flush batches and survive host exit. Capture has pause/resume controls. The OpenClaw integration filters and redacts automatic capture. The previously indexed `mem0-plugin/scripts/auto_capture.py` path is now absent; the current plugin README was reviewed instead. | Keep capture local and redacted, preserve restart checkpoints, and expose enable/disable/status. This change keeps the existing offline summarizer. |
+| [Cognee Claude Code integration](https://github.com/topoteretes/cognee-integrations/blob/main/integrations/claude-code/README.md) | SessionStart bootstraps a background watcher, write hooks stage capture, and detached final-sync workers handle exit. Persisted markers coordinate retries and avoid duplicate work. Logs and diagnostics expose failures. | Reuse the existing persistent transcript checkpoints and event IDs. Log failures and make stale capture visible in doctor. |
+| [Engram installation](https://github.com/Gentleman-Programming/engram/blob/main/docs/INSTALLATION.md), [daemon control discussion](https://github.com/Gentleman-Programming/engram/issues/1462) | Local memory tooling also uses a background service. The daemon discussion describes stale executable paths and service/session process collisions as operational problems. The discussion is a reported problem, not an implemented guarantee. | Pin absolute runtime and entry-point paths, refresh one stable registration, and validate the registered paths. |
+
+Sessionmem uses OS login supervision rather than requiring a host hook to start
+capture. This covers Codex and Cursor installations without wired capture hooks.
+The OS implementations share an `enable`, `disable`, `status` interface. They
+update one stable per-user registration and start it immediately. The watcher
+records completed sweeps separately from the OS registration so doctor can report
+capture that has stopped or is failing.
+
+The npm binary is a JavaScript entry point. Services invoke its absolute path
+through the absolute Node executable running install. They do not use npm shims,
+`npx`, an interactive shell, or PATH lookup. Changing Node installations requires
+`sessionmem autostart enable` again.
+
+Native definitions were also checked with `systemd-analyze verify`, Python's
+plist parser, and the [Microsoft Task Scheduler schema](https://learn.microsoft.com/en-us/windows/win32/taskschd/task-scheduler-schema).
+The task uses schema version 1.3, unlimited execution time, and the schema's
+maximum 255 restart attempts at one-minute intervals. Windows status and stop
+checks use [numeric HRESULTs](https://learn.microsoft.com/en-us/windows/win32/taskschd/task-scheduler-error-and-success-constants)
+rather than localized error text.
+
+## Validation boundaries
+
+CI mocks the OS supervisor commands, tests all three native definitions and
+command sequences, and runs the real watcher against synthetic transcripts.
+The packaged-install smoke test uses that same test-only supervisor. It does not
+validate the live login behavior of launchd, systemd or Task Scheduler.
+
+Manual verification required before release:
+
+- macOS: install from a normal GUI login as an ordinary user. Confirm the plist
+  in `~/Library/LaunchAgents`, `launchctl print gui/<uid>/io.sessionmem.watch`,
+  immediate capture, and capture after logout/login with the terminal closed.
+  Repeat install and confirm one loaded job. Check paths containing spaces.
+  Disable, enable and uninstall; verify the job stops and the plist is removed.
+- Linux: use a desktop/login with systemd's user manager. Confirm
+  `systemctl --user is-enabled sessionmem-watch.service` and `is-active`, capture
+  after login with no terminal, and restart after killing the watcher. Repeat
+  install and check one unit. Disable/enable and uninstall must stop capture and
+  remove the unit. Also verify install reports a useful failure without a user
+  bus; it must not claim capture succeeded.
+- Windows: install without elevation as the current user. Confirm one Scheduled
+  Task with that user's logon trigger, immediate capture, capture after logging
+  out/in, paths with spaces/non-ASCII characters, and no interactive prompt.
+  Confirm unlimited runtime, restart after a failing process, and battery
+  settings. Repeat install, disable/enable, and uninstall; verify no old task or
+  watcher remains. Test on a non-English Windows installation as well.
+- Each OS: append a real Codex or Cursor conversation and confirm imported
+  memories, a fresh checkpoint and timestamped `logs/watch.log` output. Move or
+  remove the registered runtime/entry point and check doctor's binary-path fix
+  hint. Stop capture long enough to stale the checkpoint and check the capture
+  failure hint. Uninstall must preserve memories unless `--purge` is supplied.

package/docs/troubleshooting.md

@@ -13,6 +13,8 @@ Doctor prints PASS or FAIL and a fix hint for each problem. Any failed check
 returns a nonzero exit status. It checks:
 
 - **Memory store:** the selected database exists, opens, and passes SQLite's quick integrity check. It does not create a missing database.
+- **Auto-start:** this OS's per-user login registration is present and enabled; the registered Node executable and sessionmem entry point still exist. Run `sessionmem autostart enable` after moving the package or changing Node versions.
+- **Watcher capture:** a recent completed sweep checkpoint has no capture errors and transcript checkpoints exist when source files were found. Check `logs/watch.log` beside the database. Unchanged transcripts do not require new imports. Missing or stale checkpoints fail even if an OS service is registered.
 - **Schema:** all bundled migrations have been applied. It reports pending or unrecognized migrations without changing the schema.
 - **Hooks, per host:** Claude Code's SessionStart, SessionEnd, and PostToolUse commands, types, matchers, and enabled state match the current version's definitions. Other hosts report that lifecycle hooks are not required.
 - **Adapter wiring, per host:** the installed MCP entry matches the installer, its local command starts, the server version matches, and the expected tools and stats response work. This tests the configured server process without starting the coding agent itself.
@@ -21,6 +23,8 @@ returns a nonzero exit status. It checks:
 For Codex, the wiring check supports the installer-generated TOML command and
 args. Custom Codex launch settings require manual verification.
 
+Codex and Cursor transcript capture uses the login watcher; install does not wire lifecycle capture hooks for those hosts. Claude Code also has its installed hooks.
+
 All checks work offline, including when cloud summarization is enabled. Doctor
 does not summarize sessions or sync shared memories. It honors `SESSIONMEM_DB_PATH`
 and the same host overrides as install. Keep those environment settings when
@@ -29,6 +33,7 @@ running a suggested repair.
 Safe repair commands printed by doctor include:
 
 ```bash
+sessionmem autostart enable             # update paths and restart login capture
 sessionmem ping                         # initialize a missing store / apply pending migrations
 sessionmem install --adapter claude-code # repair MCP registration and hook definitions
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sessionmem",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "private": false,
   "type": "module",
   "description": "Local-first MCP memory layer for coding agents across Claude Code, Codex, Cursor, Cline, Windsurf, and other MCP-compatible hosts.",
@@ -46,9 +46,12 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@huggingface/tokenizers": "0.2.0",
     "@types/better-sqlite3": "^9.6.0",
+    "@xcidos/genesis-memory-model": "0.1.0-alpha.1",
     "eslint": "^10.12.0",
     "globals": "^17.13.0",
+    "onnxruntime-node": "1.30.0",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.71.2",
     "vitest": "^4.1.8"
@@ -59,5 +62,21 @@
   "bugs": {
     "url": "https://github.com/catfish-1234/sessionmem/issues"
   },
-  "homepage": "https://github.com/catfish-1234/sessionmem#readme"
+  "homepage": "https://github.com/catfish-1234/sessionmem#readme",
+  "peerDependencies": {
+    "@huggingface/tokenizers": "0.2.0",
+    "onnxruntime-node": "1.30.0",
+    "@xcidos/genesis-memory-model": "0.1.0-alpha.1"
+  },
+  "peerDependenciesMeta": {
+    "@huggingface/tokenizers": {
+      "optional": true
+    },
+    "onnxruntime-node": {
+      "optional": true
+    },
+    "@xcidos/genesis-memory-model": {
+      "optional": true
+    }
+  }
 }