Cross agent memory

Cross-Agent Memory

Let every harness keep its own model-optimized native memory while all agents share one verified, repository-owned understanding of the project. Never merge or mirror proprietary native-memory stores.

Keep the shared memory broad but retrieval narrow

The shared layer may contain:

• semantic knowledge: architecture, system maps, integrations, feature behavior;
• distilled episodic knowledge: verified outcomes, incidents, and failed approaches;
• reflective knowledge: decisions, rationale, patterns, and reusable lessons.

Keep mandatory procedural rules in the repository's agent instructions. Keep raw session history and client-specific preferences in native memory.

MEMORY.md is a routing index, not the whole memory. Read only the topic files needed for the task. Do not collapse the complete memory into startup context.

Choose the operation

• Recall: route through the index and load relevant durable context.
• Promote: verify a new candidate and add it to shared memory.
• Reconcile: correct drift, conflicts, or changed facts.
• Consolidate: link, split, merge, and synthesize topics without losing evidence.
• Retire: mark obsolete knowledge historical or superseded.
• Audit: validate structure, freshness, evidence, routing, and secret hygiene.

Unfinished work is not durable memory. For an explicit transfer or continuation of work in progress, invoke cross-agent-handoff. Do not enumerate or open handoffs during a new, unrelated task.

Resolve truth and scope

1. Read the repository's agent instructions first.
2. Use the shared-memory path named there. Otherwise look for docs/agent-memory/MEMORY.md from the Git root.
3. Do not invent or probe another client's native-memory path.
4. If no shared layer exists, continue from repository instructions and live evidence. Create one only when project changes are authorized.

For mutable facts use:

1. live code, Git, tests, CI, APIs, databases, or production evidence;
2. shared project memory;
3. the current client's native or auto-memory.

When sources disagree, verify reality before acting. Treat native-memory claims as candidates, never as silent authority.

Initialize only when requested

If the repository has no shared layer and project changes are authorized:

1. inspect existing repository instructions and privacy boundaries;
2. create docs/agent-memory/MEMORY.md, topics/, handoffs/active/, and handoffs/archive/;
3. give the index type: index, a concise trust order, links to every topic, and an Active handoffs block containing the exact marker pair from the handoff schema with - None.;
4. create at least one narrow, verified topic from the topic template;
5. route repository instructions to the shared index while keeping normative rules in those instructions;
6. run the memory validator and, if handoff directories are enabled, the separate handoff validator.

Do not import a native-memory dump. Promote only reviewed knowledge that belongs in the repository.

Recall

1. Inspect repository root, worktree, branch, HEAD, and dirty state.
2. Read the compact MEMORY.md index.
3. Select topics from their routing descriptions, paths, and links.
4. Read selected topics completely.
5. Re-verify high-volatility or stale claims before relying on them.
6. Report mismatches instead of blending incompatible versions.

Prefer deterministic index routing first. Use repository search for ambiguous queries. Treat any semantic or vector index as a derived fallback, never the source of truth.

Promote

Promote only knowledge that multiple future agents will need, such as:

• a durable owner or architecture decision;
• a verified feature merge, release, or behavior change;
• a costly incident with a reusable prevention lesson;
• a stable system map or integration boundary;
• a corrected belief that would otherwise cause repeated mistakes.

Read references/memory-schema.md, verify the candidate, then update the narrowest existing topic or create one from assets/topic-template.md. Add an index entry only for a new topic.

Do not promote temporary plans, speculative diagnoses, command transcripts, full logs, broad inventories, secrets, or cheaply derivable facts.

Reconcile

1. Re-read the current index and target topic to preserve concurrent edits.
2. Verify the disputed or changed fact with the strongest available evidence.
3. Preserve dated context when it explains an important decision.
4. Update last_verified and verified_against.
5. Mark uncertainty explicitly when current verification is unavailable.
6. Repair the shared entry; do not resolve conflicts by voting between memories.

Consolidate

Consolidate after meaningful growth or during a scoped maintenance audit:

• merge near-duplicate topics;
• split topics whose domains or concurrent owners have diverged;
• add useful links between related decisions, incidents, and systems;
• synthesize repeated evidence into a concise reusable conclusion;
• keep trace-back to the detailed topic and evidence;
• remove duplicate index prose without hiding reachable knowledge.

Do not repeatedly summarize summaries. Preserve source topics or dated history when further compression would make the result unverifiable.

Retire

• Use historical for a useful dated checkpoint that must be re-verified.
• Use superseded when a named replacement exists.
• Link the replacement and state what changed.
• Remove obsolete claims from active routing, but preserve evidence that explains past decisions or prevents repeated mistakes.
• Never keep a known-invalid fact active merely because it was once correct.

Audit

Check:

• every topic is reachable from the index;
• routing descriptions say when to read the topic;
• metadata, links, evidence locators, and replacement pointers are valid;
• high-volatility topics have recent verification or an explicit stale warning;
• duplicates and contradictions are resolved or recorded;
• no secrets, unnecessary personal data, or client-native absolute paths exist;
• a representative set of repository questions routes to the expected topics without loading the entire memory tree.

Run:

pwsh -NoProfile -File `
  .agents/skills/cross-agent-memory/scripts/validate-memory.ps1

On Windows PowerShell 5.1, use powershell -ExecutionPolicy Bypass instead of pwsh -NoProfile.

Work safely with concurrent agents

• Keep topics domain-scoped.
• Re-read a topic immediately before editing it.
• Preserve unrelated entries and user changes.
• Prefer a new dated historical note over rewriting evidence.
• Reconcile after durable events, not after every message or on a blind timer.