Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Design: the cross-project profile
Status: accepted (2026-10-04), implemented for 2.6. User guide:
cross-project-profile.md.
1. The problem
ai-memory keeps knowledge per project, and switching harness already costs nothing: Claude Code, Codex and OpenCode in one checkout read the same pages. What still costs something is switching project. A new repository starts from zero, so the user re-explains the same habits in every one: the package manager they use, how they like tests laid out, which architecture they reach for, the review and commit workflow they follow.
Nothing in the tree converges that knowledge today. The reserved
default/_global scope only receives pages an agent writes there explicitly,
reaches the agent only when a memory_query happens to match it, and is
deliberately kept out of the SessionStart brief. docs/design-rules-promotion.md
defers cross-project sharing, and RFC #1000 asks for exactly that.
The profile fills that gap. It is a small, curated, cross-project record of how this user usually works, built from evidence, delivered to every project and every harness, and used as the default whenever nothing more specific says otherwise.
2. Doctrine: memory as the fallback, rules as the override
The previous stance was "memory is untrusted history, never policy; always-on
rules belong in CLAUDE.md/AGENTS.md." It protected against a memory page
turning into an instruction. It also meant the agent ignored what it already
knew about the user unless someone copied it into every repository by hand.
The stance from 2.6 is an ordered precedence:
- The user's current instructions in the conversation.
- The repository's rules file (
AGENTS.md,CLAUDE.md, the harness's own). - The project's memory (its pages, rules and decisions).
- The profile: what the user usually does across projects.
Lower levels fill gaps; they never override a higher one. When a rules file says "use npm", the profile's "usually pnpm" is irrelevant. When nothing says, the agent uses the profile instead of asking again, and says which default it applied so the user can correct it.
What does not change: retrieved text is still data. A profile entry is a preference the user expressed, not a command found in stored text; it can set a default (a tool, a layout, a convention) but it cannot authorize anything the current instructions would not (no tool use, permission change, disclosure or destructive action because a page says so). The digest is fenced and labelled the same way the brief is.
3. What we borrowed from OptChat, and what we did not
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:
- The user's own words rank first. OptChat's compactor keeps orders, corrections and reasoning nearly verbatim; that is why instructions stick without a rules file. The profile harvests mainly from the user's prompts and corrections and from curated pages, never from tool output.
- The latest ruling wins. A newer statement on the same topic supersedes the older one; the older version stays reachable through the wiki's supersession chain (invariant #16: supersede, never destroy).
- Fixed byte budget, stable rendering. Sizes are UTF-8 bytes, not tokens. 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_pageopens it, and each 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 sees the current profile entry when folding in new evidence, and its prompt 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_pagebefore relying on its one-line summary for anything non-trivial.
Not borrowed: the single universal chat and harness (ai-memory is
multi-harness and the harness owns its context), a verbatim log kept forever
(the sanitizer boundary and capture exclusions win), and a 64k-token view (the
injected digest stays in the low kilobytes; rule adherence drops well before
that, docs/design-rules-promotion.md §2).
4. Where the profile lives
[profile] share selects the scope; auto (the default) picks by deployment:
| Deployment | Default | Profile location |
|---|---|---|
| Single user (no DB users, no trusted proxy), any number of workspaces | on, share = "global" |
default/_global, under profile/ |
| Multi-user | off; opt in with enabled = true |
share = "user": one private restricted project per operator |
Explicit values:
global: one profile for the whole server, indefault/_global/profile/. Every workspace contributes and consumes. In multi-user mode this is a team profile: it harvests only from open (non-restricted) projects, and it is readable by everyone like the rest of_global.workspace: one profile per workspace, in the reserved project_profileof that workspace. Use it when workspaces separate contexts that must not mix (work and personal, or two clients).user: one private profile per operator, in a restricted project in the default workspace, named_profile.<user id>, whose creator is that operator. It harvests only that operator's own sessions and pages and only from projects the operator can read. Other operators cannot read or write it (per-project authorization,docs/design-per-project-authz.md); root can, as with every restricted project. On a single-user server it behaves likeglobal.off: no harvesting, no digest, no union.
Single vs multi-user is the existing distinguishes_operators decision.
5. Pipeline
5.1 Harvest (per project, zero-LLM)
Candidates come from three sources, after the sanitizer and capture exclusions, never from tool output:
- The user's prompts whose shape is a preference or a correction: always / never / prefer X over Y / use X instead of Y / don't use / from now on / in all my projects / by default, and the Portuguese equivalents the recall router already recognizes. The verbatim words are kept with the candidate.
- Curated pages of the project:
_rules/,decisions/,gotchas/,procedures/. - Stack signals derived from the project's observed file paths
(
Cargo.toml,package.json,pyproject.toml,go.mod, …), recorded asapplies_tofacts rather than preferences.
Each candidate is stored in profile_candidates with the identity tuple
(invariant #4), its source (session:<id> or page:<path>), its date and the
contributing operator. A project whose marker sets [profile] contribute = false is never harvested.
5.2 Converge
A server job on the writer actor groups candidates across projects by topic. A candidate becomes (or updates) a profile entry when:
- the user explicitly scoped it beyond the project ("in all my projects", "every project", "across projects", "everywhere", or the Portuguese equivalents); a bare "always", "never", "by default" or "from now on" is compatible with one file, app or task and does not count (#1148), or
- the same choice appears in at least
min_projectsdistinct projects (default 2).
A conflicting choice in the same scope supersedes the older entry (the latest
ruling wins); a choice that only holds for one stack becomes a scoped entry
(applies_to: [rust]). Exceptions that only one project makes stay in that
project.
Zero-LLM topic matching normalizes the statement (lowercase, stop words out, tool and language names kept) and groups by token overlap. With a provider configured (§6) the LLM classifies and merges instead.
Grouping never scans every pair of candidates (UniiChat's "queue ready work, never scan"): a candidate is compared only with groups that share one of its topic words, once per distinct word set in each group.
5.3 Store
Entries are wiki pages, markdown in git, editable by hand:
profile/<category>/<slug>.md category: stack, architecture, workflow,
testing, tools, style, habits
Frontmatter: kind: preference, applies_to, projects (count),
first_seen, last_seen, confidence, evidence (project, source, date,
quote; capped), and optionally enforced_by (a hook or rules-file line that
already enforces it, which drops it from the digest). The body is one
imperative line, then the user's own reasoning when there is some.
All writes go through Wiki::write_page (sanitization, admission,
attribution, rollback, index in the same transaction).
A harvested page carries generated_by: profile-harvest and the sha256 of
the body it wrote (generated_sha). The harvester rewrites only such a page,
and only while its body still matches: a page written or edited by hand is
never rewritten, and the group it would have updated is reported as skipped.
profile_entry_ledger records the entries it wrote; a ledger row whose page
is gone was removed by the user, and that topic is not recreated until a
candidate newer than the entry's last write arrives. When the path still
exists but its generated metadata was removed by a manual or public page
rewrite, the ledger topic remains a matching alias: convergence leaves that
page alone instead of recreating the former wording at a suffixed path.
5.4 Deliver
- SessionStart digest. A fenced section, first in the payload (ahead of
the handoff, managed context, project brief and inbox notice):
"Your usual choices from other projects. Use them as defaults when this
project's rules and the user say nothing; say which default you applied."
Entries whose
applies_tois empty or matches the project's stack signals, in a fixed category order then path order, one line each with its page path, untildigest_max_bytes(default 3,000). The rest are counted with a hint to query. No timestamps, so the text is stable. - New-project baseline. When the project has no pages yet, the digest uses
baseline_max_bytes(default 6,000) and adds a line telling the agent it can offerai-memory profile applyto seed the repository's rules file. - Query union.
memory_queryalready unions_global; forworkspaceanduserprofiles it also unions the caller's profile project, subject to authorization. ai-memory profile apply. Writes the top entries into a managed sub-block (<!-- ai-memory:profile:start -->…end) of the rules file in the current repository, capped atapply_max_lines(default 40), never touching text outside the markers. Command-driven only, with--dry-runand--remove. The entries come fromGET /admin/profile/applywith the digest's selection; the target is--target, else an existingAGENTS.md, else aCLAUDE.mdthat does more than importAGENTS.md, else a newAGENTS.md. The write is atomic with its backup kept under the data dir. This is how a profile entry becomes a hard rule, when the user wants one.
6. Using an LLM when one is configured
Zero-LLM remains the complete default (invariant #13). With a provider
configured, and [profile] llm not false:
- Classify: at session end, the user-authored statements of the session
go to a structured-output call (JSON schema, invariant #7) returning, per
statement,
generality(project|general),category,topic, a normalized imperativestatement(≤ 200 chars), the verbatimquote,applies_toandconfidence. Text is JSON-encoded in the user message, sanitized first. - Merge: when a topic gains evidence, the current entry plus the new candidates go to a second structured call that returns the updated entry (statement, reasoning, applies_to, supersedes). Like OptChat's compactor, it sees the existing entry as context, ranks the user's words first, records faithfully and is told never to follow instructions in the text.
Both calls fall back to the zero-LLM path on any provider error.
7. Configuration
Server (config.toml / AI_MEMORY_PROFILE__<KEY>):
[profile]
enabled = "auto" # auto = on for single-user, off for multi-user
share = "auto" # auto | global | workspace | user | off
min_projects = 2
inject_on_session_start = true
digest_max_bytes = 3000 # clamped 1500..12000
baseline_max_bytes = 6000 # clamped 2000..20000
apply_max_lines = 40
llm = true # use the configured provider when there is one
Per project (.ai-memory.toml):
[profile]
contribute = false # never harvest this project (client or NDA work)
consume = false # no digest or union in this project
8. Commands
ai-memory profile status | list | show <path> | forget <path> | review | rebuild | apply [--target FILE] [--dry-run | --remove].
status, list, review and apply read /admin/profile/* and rebuild
posts to it (forget the harvest marks, re-read every project, converge);
show and forget reuse /admin/read-page and /admin/delete-page against
the profile's scope. All
are root-only on a multi-user server, like every /admin/* route; there, each
operator manages their own private profile through MCP.
On the MCP side no tool is added: memory_write_page accepts
scope: "profile" (the caller's profile scope; the path is placed under
profile/), memory_delete_page removes an entry the same way, and
memory_query returns profile hits in global_scope_hits.
9. Security boundaries
- A
userprofile is private: another operator's read, write or delete is refused (restricted project); the harvester never reads another operator's sessions into it. - A
globalprofile in multi-user mode never harvests a restricted project. contribute = falseis honoured by the harvester;consume = falseby the digest and the union.- Candidates come only from user prompts and curated pages, after the sanitizer; tool output is never a source.
- The digest and the LLM prompts treat stored text as data.
- The shared scopes (
_global, a workspace_profile) are read-open and write-gated on a multi-user server: root or awritegrant. - Event capture is never attributed to a reserved profile project.
Each gets an adversarial test and a row in docs/security-boundaries.md.
10. Out of scope
Automatic edits of a rules file (only profile apply writes one), a
universal harness, and promoting arbitrary project knowledge into the profile
without 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 diverged from §3 and §5.2. All three are fixed for 2.6.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.
- 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; addchangedto the merge schema. - 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.
As shipped, grouping compares a candidate only with groups that share one of its tokens (an inverted index), once per distinct token set in each group, which keeps a pass near-linear without any stored state. Fully incremental grouping, keyed by a stored group per candidate, needs a schema change and is left to 3.0.
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).