Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs(design): record the UniiChat lessons for the cross-project profile
AkitaOnRails3a6dafed114b
diff --git a/docs/design-cross-project-profile.md b/docs/design-cross-project-profile.mdindex 013b7dce..c6c931de 100644--- a/docs/design-cross-project-profile.md+++ b/docs/design-cross-project-profile.md@@ -51,11 +51,16 @@ the same way the brief is.## 3. What we borrowed from OptChat, and what we did not-Victor Taelin's OptChat-(<https://gist.github.com/VictorTaelin/91837951a5ce5b38f341ec1ba1df6449>)-makes one endless chat the memory: a binary tree of one-line summaries over a-verbatim log, a fixed-size view rebuilt every turn, and a `zoom` tool to open a-summary back into detail.+Victor Taelin's OptChat, since rewritten as UniiChat+(<https://gist.github.com/VictorTaelin/91837951a5ce5b38f341ec1ba1df6449>,+revisions of 2026-10-04 and 2026-10-08), makes one endless chat the memory: a+binary tree of one-line summaries over a verbatim log, a fixed-size view, and a+`zoom` tool to open a summary back into detail. The rewrite fixed a cache bug in+the first version: a pair's age was measured from its first message, merges ran+at every message, and the view was rebuilt at start, so old lines kept being+rewritten and the cached prefix broke early. The profile has no tree or view+and never inherited that formula; the lessons it applies are stable-first+ordering and leaving settled lines alone (below, and §11).Borrowed:@@ -67,13 +72,27 @@ Borrowed:the older one; the older version stays reachable through the wiki'ssupersession chain (invariant #16: supersede, never destroy).- **Fixed byte budget, stable rendering.** Sizes are UTF-8 bytes, not tokens.- The digest is deterministic and byte-identical between sessions unless the- profile changed, so it stays inside the harness's cached prompt prefix.+ The digest is deterministic: one line per entry (scope, statement, page),+ with no evidence counts, dates or confidence, in fixed category-then-path+ order. It goes first in the SessionStart payload, ahead of the handoff,+ brief and inbox, which change every session, so it stays in the reusable+ part of the harness's prompt.+- **Settled lines don't churn.** UniiChat's correction to OptChat was that an+ old line must change only when its content does. New evidence that agrees+ with an entry is appended to its evidence and leaves the statement, and so+ the digest line, untouched. The statement is rewritten only when the ruling+ changes (the latest ruling wins) or its scope narrows; the LLM merge reports+ `changed`, and its restatement is ignored otherwise.- **Zoom.** Each digest line names its page; `memory_read_page` opens it, andeach page's evidence links back to the projects and sessions that taught it.- **Context for the summarizer, and it never obeys.** The LLM merge step seesthe current profile entry when folding in new evidence, and its prompt- forbids following instructions found in the text it summarizes.+ forbids following instructions found in the text it summarizes. It uses the+ evidence to understand the entry, never to add what the user did not say,+ and credits quoted text to its real author.+- **Zoom before you act.** The digest footer tells the agent to open an entry+ with `memory_read_page` before relying on its one-line summary for anything+ non-trivial.Not borrowed: the single universal chat and harness (ai-memory ismulti-harness and the harness owns its context), a verbatim log kept forever@@ -152,6 +171,10 @@ Zero-LLM topic matching normalizes the statement (lowercase, stop words out,tool and language names kept) and groups by token overlap. With a providerconfigured (§6) the LLM classifies and merges instead.+Grouping is incremental: each candidate's topic group is stored, and a pass+compares only new candidates with the existing groups, never every pair of+candidates (UniiChat's "queue ready work, never scan").+### 5.3 StoreEntries are wiki pages, markdown in git, editable by hand:@@ -285,3 +308,25 @@ Each gets an adversarial test and a row in `docs/security-boundaries.md`.Automatic edits of a rules file (only `profile apply` writes one), auniversal harness, and promoting arbitrary project knowledge into the profilewithout evidence from more than one project or an explicit general statement.++## 11. Revision 2026-10-08: UniiChat lessons++A review against the UniiChat rewrite found three places where 2.6.0 diverges+from §3 and §5.2; they are tracked as fixes:++1. **Digest position.** SessionStart assembles handoff, notice, managed+ context and brief before the digest, so the digest sits after content that+ changes every session. Move it first.+2. **Churn on corroboration.** `place()` rewrites an entry whenever its+ evidence changes, and the LLM merge always restates it, so a settled entry's+ statement and digest line change when it is merely confirmed. Keep the+ statement unless the ruling changes or its scope narrows; add `changed` to+ the merge schema.+3. **Quadratic grouping.** Each pass regroups every candidate (up to the+ 20,000-candidate cap) against every group. Persist each candidate's group+ and compare only new candidates.++Lower priority, considered and not scheduled: a byte ruler with retry instead+of truncating long statements (truncation only affects the rare entry over 200+bytes).+