Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

docs(design): the cross-project profile

AkitaOnRailsfdbefd3c8158
diff --git a/docs/design-cross-project-profile.md b/docs/design-cross-project-profile.md
new file mode 100644
index 00000000..de5ca5fb
--- /dev/null
+++ b/docs/design-cross-project-profile.md
@@ -0,0 +1,263 @@
+# Design: the cross-project profile
+
+*Status: accepted (2026-10-04), implementing for 2.6.*
+
+## 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** is the missing piece: 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:
+
+1. The user's current instructions in the conversation.
+2. The repository's rules file (`AGENTS.md`, `CLAUDE.md`, the harness's own).
+3. The project's memory (its pages, rules and decisions).
+4. 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
+(<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.
+
+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 and byte-identical between sessions unless the
+ profile changed, so it stays inside the harness's cached prompt prefix.
+- **Zoom.** Each digest line names its page; `memory_read_page` opens 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.
+
+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, in `default/_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 `_profile`
+ of 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 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 like `global`.
+- `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:
+
+1. **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.
+2. **Curated pages** of the project: `_rules/`, `decisions/`, `gotchas/`,
+ `procedures/`.
+3. **Stack signals** derived from the project's observed file paths
+ (`Cargo.toml`, `package.json`, `pyproject.toml`, `go.mod`, …), recorded as
+ `applies_to` facts 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 said it was general ("in all my projects", "always", "by default"),
+ or
+- the same choice appears in at least `min_projects` distinct 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.
+
+### 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).
+
+### 5.4 Deliver
+
+- **SessionStart digest.** A fenced section after the project brief:
+ *"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_to` is empty or matches the project's stack signals,
+ in a fixed category order then path order, one line each with its page path,
+ until `digest_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
+ offer `ai-memory profile apply` to seed the repository's rules file.
+- **Query union.** `memory_query` already unions `_global`; for `workspace`
+ and `user` profiles 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 at `apply_max_lines` (default 40), never
+ touching text outside the markers. Command-driven only, with `--dry-run`.
+ 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 imperative `statement` (≤ 200 chars), the verbatim `quote`,
+ `applies_to` and `confidence`. 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_*`):
+
+```toml
+[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 500..12000
+baseline_max_bytes = 6000 # clamped 1000..20000
+apply_max_lines = 40
+llm = true # use the configured provider when there is one
+```
+
+Per project (`.ai-memory.toml`):
+
+```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]`.
+
+On the MCP side no tool is added: `memory_write_page` accepts
+`scope: "profile"` (the caller's profile scope), `memory_delete_page` removes
+an entry the same way, and `memory_query` returns profile hits next to the
+global ones.
+
+## 9. Security boundaries
+
+- A `user` profile is private: another operator's read, write or delete is
+ refused (restricted project); the harvester never reads another operator's
+ sessions into it.
+- A `global` profile in multi-user mode never harvests a restricted project.
+- `contribute = false` is honoured by the harvester; `consume = false` by 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.
+
+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.
diff --git a/docs/design-rules-promotion.md b/docs/design-rules-promotion.md
index b838fac8..3a173217 100644
--- a/docs/design-rules-promotion.md
+++ b/docs/design-rules-promotion.md
@@ -1,5 +1,8 @@
# Design: Promoting Memory into Governed AGENTS.md Rules
+*Cross-project sharing (deferred in §8 below) is designed and implemented by
+the profile: see `docs/design-cross-project-profile.md`.*
+
*Status: design proposal — not implemented. (Originally scoped against the 2.1
line; that and 2.2 shipped without it, so it is un-targeted and still open —
this is the balance research the feature needs before code.)*