Open source Grok Bot alternative, Bring your own agent and subscription: message Claude Code, Codex, Gemini CLI, Cursor, Copilot and 40+ AI agents as bots on your own computer, from iPhone, Mac, Windows, Linux or terminal. Agent-agnostic and free. Also a Muse and Dots alternative. Built in Rust.
Rust acpagent-client-protocolai-agentsai-assistantclaudeclaude-codecodexcoding-agentscursorgeminigemini-cligrok-bot-alternativeiosiphonelinuxmacosmcpopen-sourcerustself-hosted
docs: propose bot memory and compaction redesign
leepokaib90aeaaa4663
diff --git a/docs/README.md b/docs/README.mdindex 5055cc7e..1b04e24c 100644--- a/docs/README.md+++ b/docs/README.md@@ -26,6 +26,7 @@ Source review, a passing build, local integration tests and production acceptanc- [Group chats and reply threads](features/groups-and-threads.md)- [Bot-to-bot collaboration](features/bot-collaboration.md)- [Context and memory](features/context-and-memory.md)+- [Bot memory and compaction redesign](design/bot-memory.md) (proposal)- [Bot workspaces](features/bot-workspaces.md)- [Voice calls](features/voice-call.md)- [File attachments](features/file-attachments.md)diff --git a/docs/design/bot-memory.md b/docs/design/bot-memory.mdnew file mode 100644index 00000000..74ad578d--- /dev/null+++ b/docs/design/bot-memory.md@@ -0,0 +1,617 @@+# Bot memory and compaction (proposal)++Status: **proposal, not implemented** (2026-10-17). It replaces the current Engram-based memory described in+[context and memory](../features/context-and-memory.md) and [Engram memory integration](../features/engram-memory.md).+Nothing here is shipped. The numbers are starting values to be tuned against the [evaluation](#evaluation).++In one line: **memory records the person, the transcript stays in the host, the opening stays frozen until+compaction, and the host decides when to compact.**++## Why redesign++Reading the current implementation turned up these problems.++- **Two writers for one memory.**+ - The agent writes through Engram's MCP tools, and the keeper extracts facts from the same exchanges.+ - Each keeper batch runs the agent twice.+ - User messages are stored three times: transcript, keeper queue, and Engram's captured prompts.+ - Each turn makes three Engram round trips.+- **The mid-session reload doesn't work.**+ - Claude Code records the system prompt on a session's first request and reuses that record until the session+ is compacted. This is on by default since Claude Code 2.1.265 (SDK 0.3.265) and no longer flag-gated since+ 2.1.268. Local transcripts already contain `systemPromptSnapshot` records.+ - When `_meta.systemPrompt` changes, `claude-agent-acp` tears down the query and resumes it, which replays history+ and re-runs SessionStart hooks. The new text still takes effect only at the next compaction.+ - So "memory changed, `session/load` with a new append" restarts the process for nothing.+- **The opening is one compaction late.** The host reacts to `compaction_update` completed by re-rendering and+ loading the new opening. The compaction that just ran already re-recorded the old prompt, so the new one is+ picked up only at the following compaction.+- **Non-Claude harnesses lose the profile.**+ - `<bot-profile>` is sent only in a session's first message (`host/src/agent/bot/turn.rs`).+ - Codex keeps only the last 20k tokens of user messages verbatim when it compacts locally+ (`COMPACT_USER_MESSAGE_MAX_TOKENS`). Remote compaction keeps developer messages only behind a feature flag.+ - `codex-acp` passes developer instructions only on `session/new`, not on load or resume.+ - Codync re-sends the profile in none of these cases.+- **Fork drops the opening.** `session/fork` sends no `_meta`, and the adapter forwards none, so a new thread needs+ an immediate `session/load` (`host/src/agent/bot/session.rs`).+- **Adapter signals are ignored.** Both `claude-agent-acp` and `codex-acp` report:+ - `usage_update{used,size}`;+ - per-prompt `cachedReadTokens` / `cachedWriteTokens`;+ - compaction progress.++ Claude also sends `compact_boundary` token counts and the summary. The host reads only+ `_meta["_claude/rateLimit"]` (`host/src/agent/bot/updates.rs`).+- **A second memory runs unseen.** Claude Code's auto memory and auto-dream run inside bot sessions. Auto memory is+ "loaded into the system prompt at session start", and none of it is visible in Codync.+- **Engram has the wrong shape.** The details are under [Engram](#engram).+ - Engram is built for one coding agent remembering its own work: one database per bot, written only by Engram,+ with Codync reading its schema read-only.+ - That rules out the shared "yours" layer, the write gate, provenance with cascade delete, a dream log with undo,+ and memory writes stamped with `rev` in the same transaction.++## Patterns explored++Two research passes on 2026-10-17 compared:++- **Products:** ChatGPT, Claude, Grok (Grok Bot, Grok Build), Gemini, Codex, Claude Code, Cursor, Amp, Factory,+ OpenClaw, Hermes, Letta, Mem0, Zep/Graphiti.+- **Papers** from 2024–2026.+- **Community threads:** Hacker News, Reddit and GitHub issues.+- **Local sources:**+ - `claude-agent-acp` 0.92.0;+ - Claude Agent SDK 0.3.300, which bundles Claude Code 2.1.300;+ - `codex-acp` on GitHub.++### Where memory lives and who writes it++| Pattern | Seen in | What we found | For Codync |+|---|---|---|---|+| Agent-managed memory through tools | Letta/MemGPT core memory, Engram MCP, Hermes | Agents forget to call the tool, or say "remembered" without calling it. Tool writes bypass any review. Letta shared blocks are last-write-wins. | Not the main writer. A bot's proposal becomes a confirm card. |+| Background extractor | Mem0, ChatGPT saved memories, our keeper | One background writer is the consensus. Mem0 went add-only in April 2026 because reconciliation "was where context got destroyed". | Kept as **dreaming**, limited to add and archive. |+| Small profile always in context | ChatGPT saved memories, Claude memory summary, Hermes `MEMORY.md`/`USER.md` | Reliable, because nothing depends on the model deciding to look. Needs a size cap. Hermes' 2,200-character cap caused silent fact loss. | **Adopted** for active memory, capped in tokens. |+| Retrieval on demand | Vector RAG, our former "context" section | A community evaluation found about 60% of failures were the agent never searching. | Only for archived memory and the transcript. |+| Raw transcript search | Letta's filesystem benchmark (grep agent ≈74%) | Beats most memory products. Replacing the transcript with summaries or extracted facts lowers accuracy (LongMemEval). | **Adopted**: `search_history` over the host transcript. |+| Knowledge graph / temporal graph | Zep/Graphiti, A-MEM | Graphiti invalidates old facts instead of deleting them. Benchmark gains are small next to benchmark noise: 6.4% of LoCoMo's answer key is wrong. | Not built. We borrow "supersede, don't delete". |+| File-based memory | CLAUDE.md, Claude Code auto memory, Codex memories, OpenClaw `MEMORY.md` | Transparent and editable, but no transactions and no sync to three clients. | SQLite, made fully visible in the UI. Harness file memory stays for project bots only. |+| Sleep-time consolidation ("dreaming") | ChatGPT dreaming, Claude Code auto-dream, OpenClaw, Letta sleep-time, Grok Build `/dream` | Useful, and every product adds guards. OpenClaw rejects a rewrite that removes more than 0.25 of entries and keeps a pre-image. Hermes removed its `replace` action because it wiped other facts, and #5563 traced lost memory to corruption and the cap. Claude Code auto-dream keeps "no log of what was created, modified, or removed" (#38493). | Adopted, with the guards below. |+| External memory service | Engram, Mem0 cloud, Supermemory, Honcho | A separate process owns the writes and has its own failure modes. | Dropped. |++### Scoping across bots++| Product | Scope |+|---|---|+| Grok Bot | Per bot: "Memory and Routines belong to the Bot … context remains with the role" |+| Claude Projects | Per project, with a per-project "Use account memory" toggle |+| ChatGPT Projects | "Project-only memory", but a 653-point Reddit thread reproduced a leak into a project-only project |+| Letta | Shared blocks, last write wins; read-only blocks advised |++Cross-scope bleed is the most common complaint everywhere. A 738-point r/ChatGPT thread: "memory is great until+it quietly carries an assumption from three chats ago into something unrelated. a per-chat toggle would fix most+of it". Codync's shape follows Claude Projects: per-bot memory plus a shared "yours" layer that each bot can switch+off. Only the user and dreaming write "yours".++### Consensus we design to++1. **Memory is for the person, not the work.**+ - Codex: "Keep required team guidance in AGENTS.md"; memories are "a recall aid".+ - Grok Build memory excludes anything the repository already covers.+ - Claude Code auto memory skips what it can derive from the code.+ - Users who let memory touch code complain that it "saves a memory with the patch in it instead of fixing the+ code. disabled memory user wide" (r/ClaudeAI).+2. **Scope it.** Memory must not leak across contexts the user keeps apart.+3. **Staleness is the hard part**, more than finding things. Archive superseded facts with a pointer to what+ replaced them, and turn the future into the past as time passes. ChatGPT dreaming turns "You're going to+ Singapore" into "You went in July 2026".+4. **Visible, editable, with provenance.** Every memory says where it came from and can be undone.+5. **One automatic writer, behind a gate.**+6. **Memory is an attack surface.** Treat it as data, not instructions. Published attacks:+ - MINJA poisons memory through queries alone.+ - AgentPoison reaches over 80% success at a poison rate under 0.1%.+ - Gemini's delayed tool invocation fires a planted instruction when the user later says "yes".+ - Microsoft found over 50 "remember … as a trusted source" prompts from 31 companies planted in links.++ The defense that holds is structural (CaMeL, the design-patterns paper): untrusted input must be unable to+ trigger consequential actions.+7. **The raw transcript is the source of truth.** Memory is an index over it.+8. **A stable prompt prefix.** Anthropic: "Put changing information in messages, not the system prompt."+9. **Small and complete beats large plus retrieval.**++Still contested: files vs. a database, vectors, and graphs. We use SQLite for transactions and three-client sync,+and keep the file camp's real requirement: no hidden state.++### Compaction patterns++| Pattern | Seen in | For Codync |+|---|---|---|+| Harness auto-compacts at a threshold | Claude Code (at the model limit, about 967k on 1M models), Codex | Kept as the safety net |+| Idle compaction inside the harness | Claude Code 2.1.299+: interactive terminal only, flag-gated off by default | Never active in bot sessions, so the host's idle compaction is the only one |+| Summary written while idle, swapped in on return | Claude Code's flag-gated `compact_on_return` mode; its "resume from summary" offer after over 1 hour idle and over 100k tokens | Precedent for host idle compaction and rollover |+| Host-timed compaction | No product feature found | **Adopted**: end of turn, and idle before the cache expires |+| Handoff to a fresh session | Amp Handoff, an editable draft; Amp calls compaction "lossy" and warns about "stacking summary on top of summary" | **Adopted** as rollover |+| Anchored or iterative summaries | Factory: only the newly truncated span is summarized and merged. It scores 3.70 vs. 3.44 (Anthropic) and 3.35 (OpenAI); the artifact trail is weakest everywhere. | Left to the harness; rollover resets drift; probes in the evaluation |+| Memory-flush turn before compaction | OpenClaw | Not needed: the host keeps the full transcript |+| Masking old tool output | Anthropic context editing (it invalidates cached prefixes) | The harness's job |+| Writing our own summaries | Anthropic on-demand and threshold compaction APIs | Not built until harness summaries prove insufficient |++## The design++### Two layers++Caps count tokens, not characters, so Chinese users aren't penalised. 2,000 CJK characters are 2–3k tokens, but+2,000 English characters are about 500. The estimate is CJK-aware: one token per CJK character, one per four Latin+characters.++| Layer | Holds | Cap (initial) | Default | Scope |+|---|---|---|---|---|+| **Yours** | Name, time zone, language, important people, standing preferences | ≤ 400 tokens | On for personal bots, off for project bots | Shared by all bots |+| **This bot** | How to work with you, promises, ongoing commitments | ≤ 1,200 tokens | Always on | One bot; wins over "yours" when they conflict |++Active total: ≤ 1,600 tokens per opening. For comparison:++- Hermes: about 800 + 500 tokens;+- the Claude Code `MEMORY.md` index: 200 lines or 25 KB;+- Letta blocks: 5,000 characters by default.++Placement:++- **Active** memory is placed in full in the session opening.+- **Archived** memory is out of the prompt and searchable with FTS5 trigram, which also handles Chinese.+- Past a cap, dreaming merges or archives entries.+- Project knowledge stays in the harness's files (`AGENTS.md`, `CLAUDE.md`).++### Writers and the gate++- **The user, in the UI**: writes directly. This is the only direct write.+- **The bot**: proposes. A proposal appears as a confirm card in all three clients, and accepting it is a UI write.+- **Dreaming**: proposes. It is the only automatic writer, and it also records an explicit "remember …" the user+ typed when the bot didn't call its tool.++Every proposal is audited only against **the user's own words**. These checks are deterministic code in the core,+not another model's judgment.++- **Evidence must be user-authored.** Each item quotes the user verbatim and cites at least one message id.+ - The quote must appear in a user-authored span.+ - Code fences, blockquotes, attachments, forwarded text and spans the composer tagged as pasted don't count.+ The iOS, desktop and TUI composers mark pasted spans.+- **Minimum content.** A quote of three content tokens or fewer, or one that is only an acknowledgement (好, yes, ok,+ sure), can't carry a memory. This stops the delayed-trigger attack and "shall I remember X?" loops.+- **Instruction-like content is rejected:**+ - "remember / 記住" imperatives addressed to the assistant that didn't come from the user's typing;+ - invisible Unicode;+ - URLs with prompt-carrying parameters (`?q=`, `prompt=`).+- **Sensitive data.**+ - Passwords, government ID numbers and account numbers are never stored, even when asked.+ - Health, religion and politics are stored only on explicit request, with a visible notice.++Source policy:++| Source | Can create memory |+|---|---|+| UI edit | Directly |+| User text in the main chat or a thread | Yes, through the gate |+| User text in a group room | Only for the bot(s) addressed, tagged with the room id |+| Voice transcript (`source: voice`) | Only after UI confirmation or a second occurrence. Audio-model attacks such as AudioHijack reach 79–96%. |+| Bot-to-bot requests | Never. They also never read another bot's private layer. |+| Bot output, routines, webhooks, files, web pages | Never |++### Dreaming++**Schedule.**++- It runs after five idle minutes or eight queued user messages.+- It also runs before any host-initiated compaction or rollover.+- It is skipped while subscription usage is above 75% of the window. Codex keeps the same 25% headroom with+ `min_rate_limit_remaining_percent`.++**How it runs.**++- It uses a fresh, tool-free context on the bot's cheapest model. The keeper already does this: `tools: []`, Haiku.+- It reads the transcript from a bookmark forward.+- Untrusted and system-provenance spans are stripped before the proposal prompt (OpenClaw does the same).++**Pipeline.**++1. Proposal.+2. Audit.+3. The host re-checks the result deterministically.+4. One transaction writes memories, revisions, the dream log and `rev`.++The transaction aborts if the bot's memory `rev` changed since the dream's snapshot, so a UI edit made during the+run is never overwritten (OpenClaw uses optimistic concurrency the same way).++**Rules:**++- **Your words are fixed.** Entries the user wrote, or explicitly asked for, can never be changed by dreaming.+- **Add and archive only.** Dreaming never rewrites or deletes. Archiving names what superseded the entry.+ Deletion happens only when the user presses Forget.+- **Limits.** At most 10 operations per run. A batch that would archive more than ¼ of active entries is rejected+ whole (OpenClaw's default is also 0.25).+- **Tombstones.** A forgotten entry leaves only a content hash, so dreaming can't grow it back. Its revisions are+ deleted too.+- **Cascade.** Deleting a message deletes memories learned only from it. ChatGPT ("Deleting a chat alone does not+ necessarily delete a separate saved memory") and Claude ("related memory entries generated from it won't be+ removed") don't do this.+- **Time review, daily.** Future tense turns into the past once the date passes. Relative dates become absolute at+ write time.+- **Dream log.** Every run's changes are visible and can be undone in one tap.+- **Migrated entries.** Entries imported from Engram or Markdown change only on contrary evidence.++### Frozen opening++The opening, in order:++1. harness tools and preset;+2. identity and rules;+3. yours;+4. this bot.++It stays byte-identical until compaction or a new session.++- **Claude transport.** Send the object form, which the adapter spreads into the SDK preset:+ `_meta: {"systemPrompt": {"append": …, "excludeDynamicSections": true}}`.+ - Not the ACP spec `systemPrompt` field yet: for Claude the adapter rebuilds it as preset plus append and drops+ the other options.+ - `excludeDynamicSections` moves the working directory, git status and similar per-session context into the+ first user message. The opening is then identical across a bot's main chat, threads and routines, and a new+ session reads the cache.+- **Change the opening only at compaction or rollover.** Every change restarts the adapter's query and replays+ history. Resume has had regressions, such as 2.1.288 dropping files a compaction had just restored.+ - The SDK has undocumented mid-session invalidation hooks (`liveAppendSections`,+ `CLAUDE_CODE_HOST_PROMPT_SUPERSEDES_RECORD`).+ - They are unstable and any re-render invalidates the system-prompt cache layer, so the design doesn't depend on+ them.+- **Deltas.** Changes made elsewhere reach the bot as one `<system-reminder>`-style block prefixed to its next+ message. That covers UI edits and what other threads or bots learned.+ - Nothing is sent for what this session learned itself, because the bot already heard it.+- **Ledger.** It records two numbers per session: the memory revision the opening contains, and the revision deltas+ have delivered up to.+- **The handoff summary goes in the first user message**, not the opening, because it differs per session.+- **Fork.** Re-send the parent's `_meta.systemPrompt` on `session/fork`.+- **Settings isolation.** Consider `settingSources: []` or `["project"]`. The adapter default+ `["user","project","local"]` loads the user's own `~/.claude/CLAUDE.md` and settings into every bot.++### Compaction++The harness writes the summary, because it knows the work: files read, todos, tool results. The host decides+**when**, because it knows how full the context is, whether the user is present and whether the cache is warm.++Cache economics (Anthropic):++- a cache read costs 0.1× input, or less on newer models (0.05× on Opus and Sonnet 5.5);+- a 5-minute cache write costs 1.25×;+- a 1-hour cache write costs 2×.++Compacting an idle session before its cache expires beats a cold re-read once the context passes roughly 70–90k+tokens at 0.1× reads. Recompute this per model.++The 1-hour TTL applies to SDK turns only "on a Claude subscription within your plan's included usage". On+extra-usage credits or an API key it drops to 5 minutes. The host reads the TTL actually in use (the SDK's+`usage.cache_creation` separates 5-minute and 1-hour writes), or pins `promptCacheTtl: "1h"` for main lanes, which+doubles the write cost on API billing.++| Trigger | When | Why |+|---|---|---|+| **End of turn** | `used ≥ min(0.75 × size, 200k)` when a turn ends, leaving room for the summary (about 20k tokens) | The cache is hot, so reading the history costs ≈1/10. Nothing stalls mid-task. |+| **Idle** | 1-hour TTL: at TTL − 5 min when `used ≥ 100k`, main lane only. 5-minute TTL: no idle compaction. | Cheaper than a cold read on return. The threshold sits above break-even because compaction loses detail. |+| **Rollover** | Any of: (1) returning with a cold cache and `used ≥ 100k`; (2) away ≥ 8 hours with ≥ 3 compactions; (3) the loop guard fires | Summaries of summaries drift. A new session starts with a handoff. |+| **Safety net** | A single turn fills the window | The harness's own auto-compaction |++The `idleCompaction` setting needs no change. The harness never idle-compacts in SDK/ACP sessions, and setting it+to true "does not turn idle compaction on".++**Loop guard.** It allows at most 3 host-initiated compactions per lane per 24 hours. If post-compaction usage is+≥ 60% of the trigger, or two compactions happen within 5 turns, the host rolls over instead.++- Claude Code added a 3-attempt circuit breaker in 2.1.76 and thrash detection in 2.1.89, and still fixed+ "conversations being compacted over and over" in 2.1.301.+- One issue reported 211 compactions in a single session.++Threads, group rooms and routines are never compacted early. Most are not revisited, so the cost isn't spent ahead+of time. When the main chat is nearly full, a new thread starts from a handoff instead of a fork.++**Before a host-initiated compaction:**++1. dream;+2. render a new opening with the latest memory;+3. load it into the session;+4. compact with a keep-list.++This order puts the new opening into the very compaction that runs. Anthropic's docs say "the first compaction+switches to the current prompt".++How the keep-list is passed:++- **Claude:** `/compact <instructions>`, which the SDK turns into `custom_instructions`.+- **Codex:** `/compact` ignores trailing text, so the keep-list goes in as `compact_prompt` through `CODEX_CONFIG`.++The keep-list:++- **Verbatim:** the last user request, and every "don't / 不要".+- **Exact identifiers:** paths, URLs and ids (OpenClaw keeps "exact opaque identifiers").+- **Kept:** decisions with reasons, pending tasks with the next step, who said what in rooms, and the thread intro.+- **Left out:** identity and memory, because the host re-injects them.++The keep-list also lives in the opening, so harness-initiated compactions see it.++**After any compaction.** The signal is `compaction_update` completed, Claude's `compact_boundary`+`pre_tokens`/`post_tokens`, or a sudden drop in `usage_update.used` for harnesses that don't notify. Then:++1. Reset the ledger's delivered number to the opening's, and send one merged delta.+2. Re-send `<bot-profile>` to non-Claude harnesses. Do the same after every resume.+3. Re-send the thread intro inside a thread.+4. Store the summary as a transcript entry and show an "Earlier conversation summarized" card.+ - Codex's `compaction_update` carries no summary. For Codex the host builds the card from its own transcript:+ the boundary plus the latest turns.++**Rollover handoff.** It contains:++- the last compaction summary;+- the last 3–5 user turns verbatim;+- the open plan.++The user can edit it as a draft before it is sent (Amp's handoff works this way).++### Claude Code's own memory++| Bot | Auto memory | Auto-dream | Why |+|---|---|---|---|+| Personal (workspace Codync created) | Off: `autoMemoryEnabled: false` + `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` | Off: `autoDreamEnabled: false` | Only one memory, fully visible in Codync |+| Project (points at a real repo) | On | Off | It is the project's working memory. |++For project bots:++- The auto-memory directory is shared with the user's own Claude Code sessions in the terminal.+- Its `user`/`feedback` notes overlap Codync's person memory.+- Codync shows the project's `MEMORY.md` read-only, so it isn't unseen.+- The opening states the split: people in Codync memory, the project in harness memory and `CLAUDE.md`.++The adapter passes `claudeCode.options.settings` and `.env` through untouched, so these settings reach the SDK.++### Storage++Host SQLite, one transaction per change, every change stamped with `rev`. The tables:++- `memories`: layer, active/archived, source, room, pin, dates, evidence message ids;+- `revisions`;+- `tombstones` (hash only);+- `ledger`;+- `dream_runs`;+- an FTS5 trigram index.++### UI (all three clients)++- **Two sections**, "About you" and the bot's own. Each entry shows where it was learned, with a link to the+ message.+- **A per-bot switch** for "yours".+- **Confirm cards** for bot proposals and voice-only memories.+- **The dream log** with undo.+- **Entry actions:** edit, pin, forget, and forget everything.+- **For project bots**, the project `MEMORY.md`, read-only.+- **In the chat**, a summary card after compaction, and an editable handoff draft at rollover.++### Deliberately not built++Each of these has a trigger for adding it later.++| Not built | Add it when |+|---|---|+| Vectors | Full-text search stops finding things |+| Knowledge graph | — |+| Project or team tiers | — |+| Multi-computer sync | — |+| Our own compaction summaries | Harness summaries prove insufficient |+| Per-reply memory citations | — |+| Engram | — |++## Engram++Engram fits its own goal: one coding agent's memory of its own work. The mismatch is shape, not quality.++| Engram | Codync needs |+|---|---|+| One database per bot; a `personal` scope stays inside it | A "yours" layer shared by all bots |+| Engram owns every write; Codync reads the pinned schema read-only | The gate, provenance with cascade delete, revisions, tombstones and dream undo, all inside Codync |+| The agent gets Engram's write tools directly | Every non-UI write passes the gate |+| A separate process per bot; downloaded on first use; a lost acknowledgement means a write can't be retried safely | Memory that is as reliable as the host |+| Separate from `rev` | Memory and `rev` written in one transaction |++Everything Engram provides that we use, FTS5 search and a few tables, is a few SQLite tables in the host.+`host/src/chat/memory/engram/` (install, process, migration, backup, clear) disappears.++## Packaging++The memory system is built as a self-contained crate, `codync-memory`, so other ACP clients can use it later.++**A core that only decides (sans-IO).**++- The core has no processes, network, model calls or threads. Events and data go in; changes and commands come+ out.+- It contains:+ - the store;+ - the gate;+ - the dreaming rules;+ - the opening, delta, keep-list and handoff renderers;+ - the compaction-timing state machine with its loop guard;+ - the mapping from commands to ACP payloads (`_meta.systemPrompt` for Claude, first message for others,+ `compact_prompt` for Codex).+- It uses the **caller's SQLite connection**, keeps its own tables and migration version, and writes in the+ caller's transaction. Memory and `rev` therefore commit together.+- **Model work goes back to the driver.** The core returns a job (prompt plus answer format). The driver runs it+ on the user's own harness and never calls provider APIs. The core validates the answer deterministically before+ writing: user-authored verbatim evidence, minimum content, the ¼ guard, the operation limit, the format, and the+ `rev` precondition.++**Drivers.**++- **The Codync host** embeds the core. It is the full product: three-client UI, transcript in the host, and a gate+ that sees only what the user typed.+- **An ACP proxy (later)** lets any ACP client use the core without changes: `codync-memory acp -- <agent command>`.+ - It can inject deltas and observe `usage_update` and `compaction_update`.+ - It can't set the opening. The [proxy chains RFD](https://agentclientprotocol.com/rfds/proxy-chains) (Draft)+ says proxies "cannot directly modify an agent's system prompt".+ - That waits for the [Client-Provided System Prompt RFD](https://agentclientprotocol.com/rfds/client-system-prompt)+ (Draft, 2026-10-09), which adds `systemPrompt {mode, content}` to new, load, resume and fork.+ - It can't separate what the user typed from what the client injected, so its gate is weaker.+ - It has no UI; a CLI covers review and undo.+ - Dreaming and compaction run between turns on the user's quota.++ACP status as of 2026-10:++- Completed: Session Usage, and Session Compaction (2026-10-06).+- Draft: End-Turn Token Usage, Session Fork, Client-Provided System Prompt, Proxy Chains.++**Repository.**++- The crate lives at `host/crates/memory`, as a member of a `[workspace]` added to `host/Cargo.toml`.+- The build output stays in `host/target`, so `npm run dev` and packaging are unaffected.+- CI runs `cargo clippy --workspace`.+- No git submodule and no separate repository for now, because core and host will change together. Split it out+ when one of these happens:+ - outside users file issues or PRs against it;+ - its API stops changing with host changes for a few months;+ - the proxy gains users.++ `git subtree split` or `git filter-repo --subdirectory-filter host/crates/memory` keeps the history.+- Publish 0.1 to crates.io, with the proxy, only after Codync runs on it.++## Verification status++What the research answered:++1. **Does compaction pick up the latest loaded opening? Yes.**+ - Docs: "The new text takes effect after that compaction, or in a new session."+ - In the SDK binary, the recorded prompt is a hidden `prompt_snapshot` attachment. After a full compaction the+ message list is rebuilt without it, so the next request renders from the current options. This part is+ inferred: no explicit delete was found.+ - Resume reads the record and doesn't re-record.+ - Hence: render, load, then compact.+2. **Can the settings be set through ACP? Yes.**+ - `autoMemoryEnabled`, `autoDreamEnabled` and `idleCompaction` go through `claudeCode.options.settings`, which+ the adapter passes on untouched.+ - `excludeDynamicSections` and `snapshot` go on the `_meta.systemPrompt` object.+3. **What does Codex report?**+ - `codex-acp` reports `usage_update{used,size}` (from `thread/tokenUsage/updated`) and per-turn cached tokens.+ - It sends `compaction_update` in_progress/completed when the client declares `session.compaction`, which+ Codync does. The update carries no summary and no token counts.+ - Its `/compact` takes no instructions.+4. **Is recording on for Codync's sessions? Yes.**+ - Default-on since Claude Code 2.1.265; the feature-flag dependency ended in 2.1.268.+ - In 2.1.300 only `systemPromptSnapshot: false` or `CLAUDE_CODE_SIMPLE` turn it off.+ - Installed versions: Claude Code 2.1.301 and adapter 0.92.0 (SDK 0.3.300).++Still unknown, to check locally before step 3 of the rollout:++- **Partial compaction:** how "Summarize from here" treats the recorded prompt.+- **2.1.301:** the installed binary wasn't searched, only the 2.1.300 binary bundled in the SDK.+- **Codex's auto-compact threshold:** about 90% of the window, from a secondary source only.+- **The real flow, end to end:** compaction order, keep-list effect, and cache read/write ratio per turn, all on+ the real host.++## Evaluation++**Property tests** in the crate:++- no memory without a user-authored verbatim span;+- pasted and quoted spans never count;+- acknowledgement-only quotes are rejected;+- the ¼ guard and the 10-operation limit;+- tombstones never resurrect;+- cascade on message delete;+- the temporal flip;+- the `rev` precondition;+- the loop guard.++**Scripted regression.** About 50 zh-Hant and English conversations covering:++- LongMemEval's five abilities: extraction, multi-session reasoning, temporal reasoning, knowledge update and+ abstention;+- MemoryAgentBench's selective forgetting.++Validate the judge adversarially first: a LoCoMo audit found a judge accepting up to 63% of intentionally wrong+answers.++**Compaction probes** after each compaction, Factory-style:++- recall;+- artifacts (paths, ids);+- continuation;+- decisions.++Also log the cache read/write ratio per turn and assert on it in e2e.++**Product metrics** (PostHog counts only, never content):++- the 7-day regret rate (memories the user edits or deletes);+- the dream-undo rate;+- compactions per session;+- rollovers;+- cache hit ratio before and after compaction;+- "wrong memory" taps.++## Rollout++Each step ships on its own.++1. **Store, migration, gate.**+ - Add the new tables and migrate Engram and Markdown memory in one pass.+ - Add the gate with pasted-span tagging in all three composers, the source policy and the sensitive-data rules.+ - Add confirm cards.+ - Turn off auto memory and auto-dream for personal bots, and auto-dream for project bots.+ - Show two layers on the memory screens of all three clients. If an API field is removed, raise `minApp`+ ([compatibility](../reference/compatibility.md)).+2. **Dreaming replaces the keeper.**+ - Proposal, audit and evidence ids.+ - The `rev` precondition, operation and ¼ limits, and rate-limit headroom.+ - The time review.+ - The dream log with undo, and cascade on message delete.+ - Move automatic naming's trigger to turn end.+3. **Cache-safe opening and compaction.**+ - Remove the reload; send the `_meta.systemPrompt` object with `excludeDynamicSections`; fork re-sends it.+ - Add the ledger and deltas.+ - Read usage and the TTL.+ - Add the three triggers with the loop guard and the before/after steps.+ - Add the Codex keep-list via `compact_prompt`, and profile re-send after compaction and resume.+ - Add the summary card and the editable handoff.+ - Assert cache tokens in e2e.+4. **Turn on the shared "yours" layer.** Dreaming may write to it, labeled with the bot that learned it.++## Sources++**Products**++- ChatGPT: [memory and dreaming](https://openai.com/index/chatgpt-memory-dreaming/), [Memory FAQ](https://help.openai.com/en/articles/8590148-memory-faq), [Projects](https://help.openai.com/en/articles/10169521-projects-in-chatgpt)+- Claude: [chat search and memory](https://support.claude.com/en/articles/11817273-use-claude-s-chat-search-and-memory-to-build-on-previous-context)+- Claude Code docs: [memory](https://code.claude.com/docs/en/memory), [context window](https://code.claude.com/docs/en/context-window), [prompt caching](https://code.claude.com/docs/en/prompt-caching), [hooks](https://code.claude.com/docs/en/hooks), [settings](https://code.claude.com/docs/en/settings-reference), [modifying system prompts](https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts), [changelog](https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md)+- Claude Code issues: [auto-dream #38493](https://github.com/anthropics/claude-code/issues/38493)+- Anthropic API: [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching), [compaction](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand), [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing), [memory tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool)+- Grok: [designing Grok Bot](https://x.ai/news/designing-grok-bot), [Team Bots](https://x.ai/news/team-bots), [Grok Build memory](https://x.ai/news/grok-build-memory)+- Codex: [memories](https://learn.chatgpt.com/docs/customization/memories), [`compact.rs`](https://raw.githubusercontent.com/openai/codex/main/codex-rs/core/src/compact.rs), [`compact_remote_v2.rs`](https://raw.githubusercontent.com/openai/codex/main/codex-rs/core/src/compact_remote_v2.rs)+- Coding agents: [Amp Handoff](https://ampcode.com/news/handoff), [Factory: evaluating compression](https://factory.com/news/evaluating-compression), [Cursor: dynamic context discovery](https://cursor.com/en-US/blog/dynamic-context-discovery)+- OpenClaw: [dreaming](https://docs.openclaw.ai/concepts/dreaming), [compaction](https://docs.openclaw.ai/concepts/compaction)+- Hermes: [memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory), [#5563](https://github.com/NousResearch/hermes-agent/issues/5563)+- Letta: [memory blocks](https://docs.letta.com/guides/agents/memory-blocks), [sleep-time compute](https://www.letta.com/blog/sleep-time-compute), [benchmarking agent memory](https://www.letta.com/blog/benchmarking-ai-agent-memory)+- Mem0: [token-efficient memory](https://mem0.ai/blog/mem0-the-token-efficient-memory-algorithm)+- Zep/Graphiti: [Graphiti](https://github.com/getzep/graphiti), [Zep](https://arxiv.org/abs/2501.13956)++**Research**++- Benchmarks: [LongMemEval](https://arxiv.org/abs/2410.10813), [MemoryAgentBench](https://arxiv.org/abs/2507.05257), [LoCoMo audit](https://penfieldlabs.substack.com/p/we-audited-locomo-64-of-the-answer)+- Memory systems: [A-MEM](https://arxiv.org/abs/2502.12110), [Context Rot](https://www.trychroma.com/research/context-rot)+- Attacks: [MINJA](https://arxiv.org/abs/2503.03704), [AgentPoison](https://arxiv.org/abs/2407.12784), [multi-agent spread](https://arxiv.org/abs/2407.07791), [Gemini delayed tool invocation](https://embracethered.com/blog/posts/2025/gemini-memory-persistence-prompt-injection/), [Microsoft: AI recommendation poisoning](https://www.microsoft.com/en-us/security/blog/2026/02/10/ai-recommendation-poisoning/)+- Defenses: [CaMeL](https://arxiv.org/abs/2503.18813), [design patterns for securing LLM agents](https://arxiv.org/html/2506.08837)++**Community**++- [r/ChatGPT project-only memory leak](https://old.reddit.com/r/ChatGPT/comments/1rdei2p/)+- [r/ChatGPT turning off memory](https://old.reddit.com/r/ChatGPT/comments/1ve7jch/)+- [HN: Claude Memory](https://news.ycombinator.com/item?id=45684134)++**ACP**++- [RFD updates](https://agentclientprotocol.com/rfds/updates), [proxy chains](https://agentclientprotocol.com/rfds/proxy-chains), [client-provided system prompt](https://agentclientprotocol.com/rfds/client-system-prompt)+- [`codex-acp`](https://github.com/agentclientprotocol/codex-acp), [`agent-client-protocol` 2.0 proxies](https://docs.rs/agent-client-protocol/2.0.0/agent_client_protocol/concepts/proxies/index.html)++**Local**++- `@agentclientprotocol/claude-agent-acp` 0.92.0 (`acp-agent.js`, `context-compaction.js`)+- `@anthropic-ai/claude-agent-sdk` 0.3.300 (`sdk.d.ts`, bundled Claude Code 2.1.300)diff --git a/docs/features/context-and-memory.md b/docs/features/context-and-memory.mdindex 413a2e7f..d90afb4a 100644--- a/docs/features/context-and-memory.md+++ b/docs/features/context-and-memory.md@@ -2,6 +2,7 @@How a bot keeps its instructions, context and long-term memory. Engram owns durable memory; Codync managescapture, recall and the keeper. The ACP harness owns the conversation and compaction.+A replacement is proposed in [bot memory and compaction](../design/bot-memory.md) (not implemented).## Transcript, context and memory