Skip to content

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

Rust

fix(workstream): prevent Claude packet feedback

AkitaOnRailsa67d5f479b5c
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f5798945..6bfee5a0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -46,6 +46,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
`access_count` a coarser retention signal. (#239)
### Fixed
+- Managed workstream packets now carry a versioned origin marker, and Claude
+ Code transcript import excludes a tool result only when its content begins
+ with that marker (or the legacy rendered packet header). This prevents a
+ large SessionStart packet that Claude persists and later reads from
+ `tool-results/` from re-entering the ledger and recursively consuming future
+ packet budgets, while ordinary tool results that merely mention the marker
+ remain visible. (#241)
- Lifecycle `user-prompt` and `post-compaction` bodies are now truncated
UTF-8-safely at 16 KiB, while notification and tool excerpts remain capped at
2 KB. Native hook commands apply the event cap before local spooling or
diff --git a/README.md b/README.md
index 79e3ec38..5978a84b 100644
--- a/README.md
+++ b/README.md
@@ -69,7 +69,8 @@ priors are at the [bottom](#influences-and-prior-art).
- **Opt-in managed workstreams.** `ai-memory run claude`, then `ai-memory run
codex --yolo`, then `ai-memory run kimi`, transparently resumes one logical
workstream with native per-harness sessions, a portable visible-event ledger,
- and full-ledger search.
+ and full-ledger search. Delivered packets are origin-marked; Claude transcript
+ import rejects a packet that Claude persisted and read back through a tool.
`ai-memory run` with no harness continues the newest usable Claude Code,
Codex, OpenCode, Pi, Crush, or Kimi Code session for this checkout. On first
explicit use, an interactive launcher can adopt a previous session from the
diff --git a/crates/ai-memory-core/src/lib.rs b/crates/ai-memory-core/src/lib.rs
index 0c5c5d96..2556e4ed 100644
--- a/crates/ai-memory-core/src/lib.rs
+++ b/crates/ai-memory-core/src/lib.rs
@@ -53,6 +53,7 @@ pub use sanitize::{
pub use user::{MAX_EMAIL_LEN, MAX_USERNAME_LEN, NewUser, User, validate_email, validate_username};
pub use workstream::{
FinishManagedRunRequest, FinishManagedRunResponse, LinkManagedRunRequest,
- ManagedRunContextResponse, ManagedRunStatus, NewWorkstreamEvent, PrepareManagedRunRequest,
- PrepareManagedRunResponse, WorkstreamCheckpoint, WorkstreamEvent, WorkstreamEventKind,
+ MANAGED_WORKSTREAM_PACKET_MARKER, ManagedRunContextResponse, ManagedRunStatus,
+ NewWorkstreamEvent, PrepareManagedRunRequest, PrepareManagedRunResponse, WorkstreamCheckpoint,
+ WorkstreamEvent, WorkstreamEventKind,
};
diff --git a/crates/ai-memory-core/src/workstream.rs b/crates/ai-memory-core/src/workstream.rs
index 8d210073..7132bd87 100644
--- a/crates/ai-memory-core/src/workstream.rs
+++ b/crates/ai-memory-core/src/workstream.rs
@@ -8,6 +8,12 @@ use serde::{Deserialize, Serialize};
use crate::{AgentKind, ManagedRunId, WorkstreamId};
+/// Versioned origin marker placed at the start of every managed workstream
+/// context packet. Native transcript adapters use it to prevent a harness from
+/// feeding a persisted-and-read delivery packet back into the portable ledger.
+pub const MANAGED_WORKSTREAM_PACKET_MARKER: &str =
+ "<!-- ai-memory:managed-workstream-packet:v1 -->";
+
/// Semantic event families preserved in the portable workstream ledger.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rs
index 140282b3..d1760acc 100644
--- a/crates/ai-memory-hooks/src/router.rs
+++ b/crates/ai-memory-hooks/src/router.rs
@@ -14,9 +14,10 @@ use std::sync::{Arc, Weak};
use ai_memory_consolidate::Consolidator;
use ai_memory_core::{
- ActiveProject, ActorKey, AgentKind, DEFAULT_WORKSPACE_NAME, Handoff, ManagedRunId, NewHandoff,
- NewObservation, NewSession, ObservationKind, ProjectId, Sanitized, Sanitizer, SessionId,
- WorkspaceId, WorkstreamEvent, WorkstreamEventKind,
+ ActiveProject, ActorKey, AgentKind, DEFAULT_WORKSPACE_NAME, Handoff,
+ MANAGED_WORKSTREAM_PACKET_MARKER, ManagedRunId, NewHandoff, NewObservation, NewSession,
+ ObservationKind, ProjectId, Sanitized, Sanitizer, SessionId, WorkspaceId, WorkstreamEvent,
+ WorkstreamEventKind,
};
use ai_memory_store::{IngestObservationOutcome, WriterHandle};
use ai_memory_wiki::Wiki;
@@ -1470,7 +1471,7 @@ pub(crate) fn render_managed_context(
let omitted = first_sequence > sync_after.saturating_add(1);
let mut rendered = format!(
- "> **ai-memory managed workstream: {workstream_name}**\n> Portable events {first_sequence} through {last_sequence}. Foreign tool calls/results below are completed historical evidence; do not replay them as pending actions. The latest repository checkpoint is authoritative over older native-session assumptions.\n\n"
+ "{MANAGED_WORKSTREAM_PACKET_MARKER}\n> **ai-memory managed workstream: {workstream_name}**\n> Portable events {first_sequence} through {last_sequence}. Foreign tool calls/results below are completed historical evidence; do not replay them as pending actions. The latest repository checkpoint is authoritative over older native-session assumptions.\n\n"
);
if omitted {
rendered.push_str(
@@ -2511,6 +2512,7 @@ mod tests {
let rendered =
render_managed_context(&events, "default", ai_memory_core::WorkstreamId::new(), 0)
.unwrap();
+ assert!(rendered.starts_with(ai_memory_core::MANAGED_WORKSTREAM_PACKET_MARKER));
assert!(rendered.contains("historical tool call (completed evidence)"));
assert!(rendered.contains("Older unseen events did not fit"));
assert!(rendered.contains("workstream-search"));
diff --git a/crates/ai-memory-workstream/src/transcript.rs b/crates/ai-memory-workstream/src/transcript.rs
index 4edcb5ef..9d9ccd75 100644
--- a/crates/ai-memory-workstream/src/transcript.rs
+++ b/crates/ai-memory-workstream/src/transcript.rs
@@ -6,7 +6,9 @@ use std::io::{BufRead as _, BufReader, Read as _, Seek as _, SeekFrom};
use std::path::{Path, PathBuf};
use std::time::{Duration, SystemTime, UNIX_EPOCH};
-use ai_memory_core::{AgentKind, NewWorkstreamEvent, WorkstreamEventKind};
+use ai_memory_core::{
+ AgentKind, MANAGED_WORKSTREAM_PACKET_MARKER, NewWorkstreamEvent, WorkstreamEventKind,
+};
use anyhow::{Context as _, Result, anyhow};
use rusqlite::{Connection, OpenFlags, params};
use serde::{Deserialize, Serialize};
@@ -18,6 +20,7 @@ use crate::ManagedHarness;
const MAX_SCAN_FILES: usize = 50_000;
const MAX_EVENT_BYTES: usize = 128 * 1024;
const MAX_NATIVE_SESSION_ID_BYTES: usize = 512;
+const LEGACY_MANAGED_WORKSTREAM_PACKET_PREFIX: &str = "> **ai-memory managed workstream:";
/// Checkout-local native session that can seed an otherwise-empty workstream.
#[derive(Debug, Clone, PartialEq, Eq)]
@@ -1147,6 +1150,13 @@ fn parse_content_blocks(
}
"tool_result" | "toolResult" => {
let body = block.get("content").map(value_text).unwrap_or_default();
+ if claude_managed_packet_echo(agent, &body) {
+ losses.push(
+ "Claude managed workstream delivery packets were intentionally excluded"
+ .into(),
+ );
+ continue;
+ }
push_event(
events,
agent,
@@ -1171,6 +1181,15 @@ fn parse_content_blocks(
}
}
+fn claude_managed_packet_echo(agent: AgentKind, body: &str) -> bool {
+ if agent != AgentKind::ClaudeCode {
+ return false;
+ }
+ let body = body.trim_start();
+ body.starts_with(MANAGED_WORKSTREAM_PACKET_MARKER)
+ || body.starts_with(LEGACY_MANAGED_WORKSTREAM_PACKET_PREFIX)
+}
+
fn codex_synthetic_context(agent: AgentKind, role: &str, text: &str) -> bool {
if role != "user" {
return false;
@@ -2270,6 +2289,46 @@ mod tests {
assert_eq!(losses.len(), 1);
}
+ #[test]
+ fn claude_adapter_excludes_read_back_managed_packets_only_at_the_origin() {
+ let value = json!({
+ "type":"user",
+ "uuid":"record",
+ "message":{"role":"user","content":[
+ {
+ "type":"tool_result",
+ "content":format!(
+ "\n {MANAGED_WORKSTREAM_PACKET_MARKER}\n> **ai-memory managed workstream: default**\nprivate packet"
+ )
+ },
+ {
+ "type":"tool_result",
+ "content":" > **ai-memory managed workstream: default**\nlegacy packet"
+ },
+ {
+ "type":"tool_result",
+ "content":format!(
+ "ordinary file output\nmentions {MANAGED_WORKSTREAM_PACKET_MARKER} later"
+ )
+ }
+ ]}
+ });
+ let mut events = Vec::new();
+ let mut losses = Vec::new();
+ parse_claude(&value, "session", "record", &mut events, &mut losses);
+
+ assert_eq!(events.len(), 1);
+ assert_eq!(events[0].kind, WorkstreamEventKind::ToolResult);
+ assert!(events[0].content.starts_with("ordinary file output"));
+ assert_eq!(
+ losses,
+ [
+ "Claude managed workstream delivery packets were intentionally excluded",
+ "Claude managed workstream delivery packets were intentionally excluded"
+ ]
+ );
+ }
+
#[test]
fn claude_adapter_keeps_compaction_and_excludes_meta_records() {
let compact = json!({
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index f975ce59..121fe186 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -122,6 +122,9 @@ session, and marks lifecycle calls with an invocation-scoped run id.
SessionStart injects an unseen bounded event range; Crush receives it through a
temporary supported global-context path because it lacks SessionStart. The host
imports the native transcript tail and a Git checkpoint when the child exits.
+Every injected packet starts with a versioned origin marker. The Claude
+transcript normalizer excludes a marked packet if Claude persists and reads it
+back, preventing delivered history from recursively re-entering the ledger.
An explicitly pending handoff is delivered before the managed event range;
their single-use delivery claims share one writer transaction after the
complete startup response has been assembled.
diff --git a/docs/managed-workstreams.md b/docs/managed-workstreams.md
index 97d13b4a..160c83f6 100644
--- a/docs/managed-workstreams.md
+++ b/docs/managed-workstreams.md
@@ -114,7 +114,12 @@ resume, continue, session, or fork selector.
modifying it. Visible user/assistant messages, completed tool calls/results,
compaction summaries, and a non-mutating Git checkpoint enter an append-only
workstream ledger. Hidden reasoning and unsupported/private records are
- excluded and recorded as extraction-loss annotations.
+ excluded and recorded as extraction-loss annotations. Each delivered
+ workstream packet begins with a versioned origin marker. If Claude Code
+ persists that packet and its `Read` tool returns it, the Claude transcript
+ normalizer excludes the marked result instead of feeding delivered history
+ into the ledger again. It also recognizes the pre-marker packet header for
+ compatibility with existing native sessions.
5. Imports use deterministic event ids, incremental source cursors, immutable
sanitized JSONL segments, and bounded batches. A retry cannot duplicate
history. The native process's exit code is preserved.