23 — Memory & cross-session recall

Status: implemented in 2.0.0

Pillar 2 of the platform plan (see 22-gateway.md intro): Hermes' crown differentiator is not the loop — it is that nothing learned is ever stranded. Past sessions become retrievable context via a model-visible search tool plus FTS-style indexing. We get the same capability with zero new dependencies because our session store is already structured JSONL.

Model

model calls session_search {query, limit?}
        │
vak_session::search::search(home, cwd, query, limit, exclude)
        │  scans <home>/sessions/<hash_cwd(cwd)>/*.jsonl
        │  scores user+assistant texts (term frequency w/ saturation,
        │  whole-phrase bonus), newest-first tiebreak
        ▼
top-N hits: {session, ts, role, score, snippet}
        │
returned as an ordinary tool result → appended to the ledger

Invariant 1 holds by construction: the answer reaches the model only as a logged tool_result; nothing is injected outside the chain.

Scoring

Deterministic, dependency-free:

• Query tokens lowercased, alphanumeric, length ≥ 2.
• Per-hit score: Σ over unique terms: 1 + ln(count) (saturating), plus +3 when the full phrase occurs verbatim (case-insensitive), plus a small recency nudge (ts descending rank × 0.01).
• Bounded work: at most the trailing MAX_SCAN_LINES = 4000 message lines per ledger, DEFAULT_LIMIT = 8 hits, snippets ≤ 240 chars centered on the first matched term.

An incremental index (per-ledger mtime-keyed cache) can slot in behind the same function signature later; scan-first keeps v1 honest about relevance and simple.

Surfaces

Configuration

[memory]
search_enabled = true   # default; false removes the tool from the loop

Privileged rules do not apply (read-only, workspace-scoped), but unknown keys still warn per convention.

Exclusions & safety

• The current session id is excluded — its content is already in context; recalling it would double-count.
• Worker ledgers (child-*) are included; they carry parent_session_id and are legitimate knowledge.
• Search reads only; it never mutates ledgers, and respects the frozen contract (no rewriting, branching untouched).

Operational invariants (2026-08)

All durable-memory writes use a per-store lock and atomic temp-file replacement; append, amend, and forget are bounded and reject control characters in header metadata. Server and desktop search use the same curated-document ranking as the agent tool, including stored provenance timestamps. Channel overlays are applied after the complete tool set is assembled, and background reflection is skipped in read-only or channel-denied contexts. Retention is conservative: age alone never deletes a durable note. vak memory clean removes only abandoned lock/temp artifacts and empty workspace directories; stale knowledge is removed explicitly with forget or amended in place. There is no automatic “dream”/overnight consolidation pass; reflection is bounded to at most two deduplicated proposals after a clean completion.

Phases