sessionmem 1.6.0 → 1.8.0

package/docs/retrieval-tools.md

@@ -0,0 +1,144 @@
+# Compact retrieval and optional ranking
+
+## Search, inspect nearby context, then fetch details
+
+The MCP server exposes these tools alongside the existing tools. Project scope
+comes from the server, so callers do not supply `projectId` over MCP.
+
+| Tool | Input | Output |
+| --- | --- | --- |
+| `searchMemoryIndex` | `query`, optional `limit`, `includeHistory`, `tags` | IDs, one-line summaries, kind, capture date, numeric score, `hasMore` |
+| `memoryTimeline` | `memoryId`, or both `fromDate` and `toDate`; optional `limit`, `includeHistory` | Compact rows in capture order; scores are null |
+| `getMemory` | `memoryId` | One complete stored memory, including content and metadata |
+
+Start with `searchMemoryIndex({"query":"database migration","limit":5})`.
+Inspect the surrounding records with
+`memoryTimeline({"memoryId":"selected-id","limit":5})` when chronology matters.
+Fetch only the records needed with `getMemory({"memoryId":"selected-id"})`.
+The existing get-by-ID tool already returns full bodies, so no duplicate tool is
+needed. Existing `retrieveMemories` remains available.
+
+Index and timeline limits default to 10 and accept integers from 1 to 50. Summaries
+are extractive previews of stored text, with whitespace collapsed and at most 160
+characters. They can omit qualifiers from longer memories; read the full body
+before relying on a fact. No summaries or inference are generated for these tools.
+Search scores are rounded to four decimal places. Search uses the same ranker as
+`retrieveMemories`, without its startup formatting or access-counter updates.
+
+Index `hasMore` describes the bounded retrieval candidate pool, not an exhaustive
+store count. Timeline `hasMore` means more visible records exist outside the
+returned window. Around an ID, it balances earlier and later records and fills
+remaining slots from the available side. Timestamp ties use ID ordering. Ranges
+are inclusive UTC ISO timestamps, for example:
+
+```json
+{"fromDate":"2026-01-01T00:00:00Z","toDate":"2026-01-31T23:59:59.999Z","limit":10}
+```
+
+Timeline dates are **capture dates**, not dates mentioned inside prose. Timeline
+includes superseded records by default so it can explain changes; set
+`includeHistory:false` for current records only. Index excludes fully superseded
+records by default. All three tools enforce project scope and expiry. Compact
+search and timeline do not update access counters. Optional local semantic search
+can still backfill its derived vector index, as with ordinary retrieval.
+
+## Optional temporal retrieval
+
+`temporalRetrieval` defaults off. It did not improve the pinned-clock LoCoMo run.
+Enable it for stores with meaningful observation times:
+
+```bash
+sessionmem config set temporalRetrieval true
+```
+
+A deterministic English cue detector recognizes current state (`current`,
+`currently`, `now`, `latest`, `today`, `at present`) and historical questions
+(`before`, `previously`, `formerly`, `prior`, `used to`, `no longer`, `when did`,
+`when was`, `when were`, `in the past`, `historical`, `history`). Dated clauses take
+precedence over current-state cues. With no recognized cue, the previous retrieval
+behavior and scores stay unchanged, even when enabled.
+
+Supported ranges are `YYYY-MM-DD`, `YYYY-MM`, `in YYYY`, `during YYYY`, `yesterday`,
+`last/previous week/month/year`, and numeric day/week offsets such as `2 days ago`.
+Relative dates use the injected retrieval clock in UTC; weeks start on Monday and
+months are calendar months. The detector does not interpret arbitrary natural
+language dates, future plans, locale-specific dates or conversational reference
+times. An invalid date supplies no date signal.
+
+Historical intent includes superseded candidates automatically unless the caller
+explicitly sets `includeHistory:false`. That decision applies to both lexical and
+optional semantic candidates. Explicit `true` also works for current-state queries.
+Existing supersession rules still determine which facts have changed; no new
+contradiction inference is added.
+
+Within relevance, temporal scoring uses a fixed 90% existing relevance and 10%
+time signal. Current-state signals average the non-superseded claim fraction and
+freshness, `1 / (1 + ageDays / 30)`. Historical ranges use the distance from the
+range with the same 30-day scale. `before` and similar previous-state cues favor
+the superseded fraction. Undated historical questions have a neutral time signal.
+The time is the latest extracted claim observation timestamp, falling back to
+original capture time. Editing a row does not invent a new event date.
+
+Past queries neutralize ordinary recency and inactivity-based importance decay,
+so age alone does not suppress historical evidence. Stored importance and access
+boosts still apply. Dates rerank candidates; they are not hard date filters and do
+not guarantee that a relevant memory outside the candidate pool will be found.
+For exact capture-date browsing, use `memoryTimeline`.
+
+## Optional entity-link boost
+
+Entity coverage is enabled by default when retrieval uses BM25, including when
+optional inference is unavailable. It improves all three primary LoCoMo metrics
+in that mode. With active MiniLM it defaults off because hit rate and recall
+regressed. An explicit `entityLinkBoost` value overrides that mode-specific
+choice. To enable it explicitly:
+
+```bash
+sessionmem config set entityLinkBoost true
+```
+
+The query links literal normalized name spans against the existing
+`memory_entities` tables. Explicit aliases cover `postgres`/`postgresql`,
+`node`/`node.js` and `k8s`/`kubernetes`. There is no fuzzy name matching, pronoun
+resolution, entity embedding, or graph traversal. Extraction rules stay unchanged.
+Project, expiry and requested history visibility apply before link scoring.
+
+Each linked `(kind, name)` receives weight
+`1 + log((visibleMemoryCount + 1) / (matchingMemoryCount + 1))`. A memory's entity
+score is its matched weight divided by the total linked weight. Up to 50 highest
+entity-score IDs are admitted to the candidate union, with ID tie breaks. This
+channel can admit rows that were absent from the BM25 or semantic pool.
+
+The fixed fusion is 80% base relevance and 20% linked-entity score. With semantic
+search enabled, base relevance retains the existing 2:1 BM25/positive-cosine blend.
+When no entity is linked, the prior scoring path is retained. The existing 10%
+entity-overlap signal remains in use when coverage is off. Temporal
+fusion, when enabled too, follows entity fusion. Outer relevance, recency and
+importance weights remain 60%, 25% and 15%.
+
+Disable coverage with `sessionmem config set entityLinkBoost false` and temporal
+retrieval with `sessionmem config set temporalRetrieval false`.
+
+## Source-informed fusion alternatives
+
+The optional `retrievalRanking` setting accepts `legacy`, `adaptive-bm25`,
+`hub-additive` and `adaptive-hub-additive`. `legacy` means the existing BM25/dense
+fusion, with the mode-specific entity-coverage default above. Other modes default
+to their stated experiment without coverage, unless explicitly overridden.
+
+`adaptive-bm25` uses a query-length adaptive sigmoid on raw positive FTS5 BM25.
+The additive modes use a hub-damped maximum entity boost from at most eight names,
+plus lexical and optional dense signals, divided by the maximum score of active
+channels. A 0.2 semantic gate applies before additive fusion. The adaptive additive
+variant also enables the sigmoid. These hypotheses did not pass the three-metric
+regression gate and remain opt-in. See the
+[source notes](../benchmarks/retrieval-source-notes.md) for exact parameters,
+algorithm differences and licensing scope. No competitor source or prompt was
+adapted. The current defaults select entity coverage for BM25 and the existing
+fusion for MiniLM; there are no per-query-label or per-category exceptions.
+
+The temporal and entity settings work alongside the existing `semanticSearch`
+setting. Results,
+per-category losses and token measurements are in the
+[retrieval evaluation](../benchmarks/retrieval-gaps.md). They do not establish
+accuracy for generated answers or gains on coding workloads.

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.6.0",
+  "version": "1.8.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
+    }
+  }
 }