One binary, markdown files, a derived index

1. 1

   HookZero LLM

   The agent CLI fires a lifecycle hook. It is fire and forget with a 200 ms budget: native hooks spool the event locally and a detached helper delivers it. The server answers 202, or 429 when saturated.

2. 2

   SanitizeZero LLM

   The /hook router strips secrets and caps sizes. This is the only path from untrusted text into the store.

3. 3

   Single writerZero LLM

   The sanitized event goes onto one queue, drained by one thread that owns the only write connection.

4. 4

   ObservationsZero LLM

   Events land in SQLite as an operational audit trail. It is a bounded projection of the session, never a full transcript.

5. 5

   Session endZero LLM

   Rules, no model, turn the observations into sessions/<id>.md and open a Handoff row for the next agent, in one transaction.

6. 6

   ConsolidationOptional LLM

   With a provider configured, an LLM rewrites the summary or fans it out into concepts/, decisions/, gotchas/ and procedures/. It runs from a retryable queue, outside hook latency.

7. 7

   Commit and indexZero LLM

   Each page write is atomic (tmp, rename, fsync), committed to git, and indexed in the same SQLite transaction as its row.

8. 8

   Query and briefingZero LLM

   memory_query searches the index. At the next SessionStart the hook fetches the open handoff and a structured briefing for that directory.

• Full text

  SQLite FTS5 over page titles and bodies, with stopwords filtered from bare queries.

• Entity match

  A lexical index of names from frontmatter entities and tags, weighted by inverse page frequency.

• Graph neighbours

  One hop over the links table: wikilinks, markdown links, typed edges and cross-project links. Plain SQL, no graph database.

• Observations

  Full text over the project’s raw observations. Each matching session votes once, through its best observation, for its own session page, so detail that never made it into the page still finds it. On by default since 3.0.

• Vectors, optional

  Cosine similarity over embeddings from the in-process local model. On by default since 2.0, never required, and brute force on purpose.

After fusion

• Reciprocal Rank Fusion with k=60 merges the streams by rank, so no stream needs score calibration.
• A bounded authority multiplier then nudges close contests toward maintained rules, decisions, procedures and gotchas. Episodic and historical pages stay searchable, and nothing is excluded outright.
• Optional LLM rerank: one call per query over up to 30 titles and snippets. Any failure keeps the local order. There is no local reranker yet.
• If compiled pages miss entirely, a bounded search over raw observations returns raw_hits.
• Filters apply before ranking: kind, tag, tier and a path prefix narrow every stream, so a rare page cannot be crowded out by a common one.
• Two optional signals start at zero: one lowers the authority of a page carrying open stale or wrong feedback, the other boosts a page the same session read or marked helpful for a similar query. A rewrite clears both.
• Pass explain=true to see per-stream ranks, RRF contributions and the multiplier for every hit.

ARCHITECTURE.md, with all 16 invariantsDesign decisions and rejected options