Agent Memory Skill

AI agents forget what matters.

Agent Memory Skill gives agents an adaptive project-level continuity layer: curated context, user preferences, topic stack, handoff packets, candidate memory review, session health, and model/runtime migration without transcript dumps.

It works as a Codex skill, a Python CLI, a JSON memory schema, and a small set of adapters for Codex-style workspaces, ordinary AI chat, autonomous agent runs, and multi-agent workflows.

The current version is best used as a local sidecar for long-running projects, model handoffs, and existing-agent migrations. It is not meant to replace every memory system globally or store raw transcripts.

Why This Exists

Current agent memory often fails in five places:

• Model or architecture migration: a new model receives lots of old context but cannot tell what matters.
• User preference transfer: a new agent does not quickly learn the user's style, priorities, and disliked behaviors.
• Topic interruption handling: a side idea appears during an active thread, then the agent forgets to return to the main thread or fails to store the side idea for later.
• Memory bloat: agents store raw transcripts instead of concise, reusable operating state.
• Memory trust: external or agent-inferred notes can silently become durable guidance without review.

This project treats memory as curated operating state:

• important decisions
• durable user preferences
• active and parked topics
• side episodes
• relevant artifacts
• candidate memories that need review
• next actions and risks
• migration packets for handoff

What You Get

• A bundled Codex skill in agent-memory/.
• A local CLI: agent-memory or python -m agent_memory.
• A structured state.json schema for preferences, facts, decisions, threads, episodes, artifacts, and migration notes.
• Short startup briefings plus full migration packets for model or runtime handoff.
• Adaptive integration modes: bootstrap when no memory exists, augment when memory already exists, and audit when trust is unclear.
• Session health checks for long-session slowdown before cutting a fresh session.
• Candidate memory flow: propose first, promote only after review.
• Topic stack support for side ideas, parked threads, and safe resume cues.
• Existing-agent sidecar guidance so current memory is not overwritten by default.
• Atomic local writes plus state.json revision checks in the reference filesystem backend.
• Adapters for Codex, chat assistants, autonomous agent runs, and multi-agent memory.
• Deterministic behavior scenarios and release validation for open-source iteration.

Quick Start

Install locally for development:

python -m pip install -e .

Recommended project path:

python -m agent_memory integration-mode --existing-memory-exists
python -m agent_memory init --path .agent-memory
python -m agent_memory session-health --messages 365 --session-bytes 1048576
python -m agent_memory brief --path .agent-memory
python -m agent_memory propose --path .agent-memory --collection preferences --id pref-candidate --text "User may prefer short progress updates." --scope user
python -m agent_memory select --path .agent-memory --status candidate --include-candidates
python -m agent_memory handoff --path .agent-memory

For an existing agent, start in sidecar mode: create .agent-memory/, import uncertain old memory as candidates, and do not overwrite existing memory or agent configuration. See docs/existing-agent-integration.md.

Run the demo:

python scripts/demo_memory_flow.py

Prepare a handoff from an example memory directory:

python -m agent_memory handoff --path examples/codex-memory

Install the Codex skill into your local skills directory:

python scripts/install_skill.py --dry-run
python scripts/install_skill.py

By default this installs agent-memory/ into $CODEX_HOME/skills when CODEX_HOME is set, otherwise into ~/.codex/skills.

Run the end-to-end memory demo:

python scripts/demo_memory_flow.py
python scripts/demo_memory_flow.py --path .tmp-agent-memory-demo --force

This demonstrates preference transfer, topic interruption recovery, and handoff artifact generation.

Run behavior-level memory evaluations:

python scripts/evaluate_memory_scenarios.py
python scripts/evaluate_memory_scenarios.py --path .tmp-agent-memory-eval --force --json

This checks model handoff migration, portable bundle roundtrip, preference filtering, candidate review, memory update supersession, opening plan preservation, targeted memory selection, memory compaction planning, topic interruption resume, memory review, sensitive-memory redaction, user-controlled forgetting, and multi-agent separation.

Check adaptive mode and session pressure:

python -m agent_memory integration-mode
python -m agent_memory integration-mode --existing-memory-exists
python -m agent_memory integration-mode --existing-memory-exists --trust-unclear
python -m agent_memory session-health --messages 365 --session-bytes 1048576

Use this before installing into an existing assistant or before cutting a fresh session from a long-running chat.

Initialize memory in a workspace:

python agent-memory/scripts/memory_packet.py init --path .agent-memory
# or
python -m agent_memory init --path .agent-memory
# or, after install
agent-memory init --path .agent-memory

Set project handoff metadata:

python agent-memory/scripts/memory_packet.py meta --path .agent-memory --project-name "Agent Memory Skill" --objective "Create a memory skill that preserves preferences, topic state, and migration context." --summary "Prototype continuity skill for agent handoffs." --render

Validate the state:

python agent-memory/scripts/memory_packet.py validate --path .agent-memory

Render a migration packet:

python agent-memory/scripts/memory_packet.py render --path .agent-memory

Print or write a short startup briefing for a new model or agent:

python -m agent_memory brief --path .agent-memory
python -m agent_memory brief --path .agent-memory --write

Capture an opening or phase plan as a handoff artifact:

python -m agent_memory plan --path .agent-memory --id plan-opening --title "Opening Implementation Plan" --body "Phase 1: inspect context. Validation: run tests." --next-action "Run phase 1 validation."

Select targeted high-signal memory records:

python -m agent_memory select --path .agent-memory --query "model migration" --min-salience 4
python -m agent_memory select --path .agent-memory --tag migration --json

Propose a memory candidate and promote it only after review:

python -m agent_memory propose --path .agent-memory --collection preferences --id pref-candidate --text "User may prefer short progress updates." --scope user
python -m agent_memory select --path .agent-memory --include-candidates --status candidate
python -m agent_memory promote --path .agent-memory --id pref-candidate

Plan or apply conservative memory compaction:

python -m agent_memory compact --path .agent-memory
python -m agent_memory compact --path .agent-memory --apply

Prepare a model or agent handoff in one step:

python -m agent_memory handoff --path .agent-memory
python -m agent_memory handoff --path .agent-memory --strict

Export or import a portable memory bundle for runtime migration:

python -m agent_memory export --path .agent-memory --output agent-memory-export.json --strict
python -m agent_memory import --path .agent-memory-next --input agent-memory-export.json

Audit memory quality:

python -m agent_memory doctor --path .agent-memory

Review or repair a flagged memory record:

python -m agent_memory review --path .agent-memory --id fact-001 --reviewed --trusted --render
python -m agent_memory review --path .agent-memory --id fact-002 --status stale --clear-expires-at

Replace outdated memory with a newer record:

python -m agent_memory supersede --path .agent-memory --collection preferences --id pref-new --text "User prefers concise direct updates." --evidence "User corrected the old preference." --scope user --confidence high --salience 5 --replaces pref-old

Redact sensitive memory and refresh handoff artifacts:

python -m agent_memory redact --path .agent-memory --id fact-secret-001

Forget a revoked memory record and refresh handoff artifacts:

python -m agent_memory forget --path .agent-memory --id pref-temp-001

Print the JSON Schema:

python -m agent_memory schema

Capture an interruption and resume the previous thread:

python agent-memory/scripts/memory_packet.py interrupt --path .agent-memory --episode-id episode-001 --episode-text "User raised a side idea worth remembering." --thread-id thread-side-001 --thread-text "Explore the side idea." --evidence "User introduced this during an active topic." --salience 5 --confidence high --render
python agent-memory/scripts/memory_packet.py cue --path .agent-memory --text "back to the previous topic" --auto-resume --render
python agent-memory/scripts/memory_packet.py resume --path .agent-memory --current-destination closed --render

Try the example memory state:

python agent-memory/scripts/memory_packet.py validate --path examples/codex-memory
python agent-memory/scripts/memory_packet.py render --path examples/codex-memory
python agent-memory/scripts/memory_packet.py validate --path examples/topic-interruption-demo

See docs/demo-topic-interruption.md for a runnable end-to-end demo.

See docs/demo-chat-memory.md for a chat-specific demo.

Use the Codex-style workspace adapter:

python -m agent_memory.adapters.codex init --workspace .
python -m agent_memory.adapters.codex context --workspace .
python -m agent_memory.adapters.codex checkpoint --workspace . --summary "Ready for handoff." --handoff
python -m agent_memory.adapters.codex handoff --workspace .

Use the ordinary chat adapter:

python -m agent_memory.adapters.chat init --path .agent-memory
python -m agent_memory.adapters.chat remember --path .agent-memory --kind preference --id pref-001 --text "User prefers concise Chinese progress updates." --evidence "User stated this preference." --confidence high --salience 5 --note
python -m agent_memory.adapters.chat note --path .agent-memory
python -m agent_memory.adapters.chat handoff --path .agent-memory

Use the autonomous agent adapter:

python -m agent_memory.adapters.agent checkpoint --path .agent-memory --summary "Finished a useful step." --next-action "Continue from the validated result." --note --handoff
python -m agent_memory.adapters.agent tool-result --path .agent-memory --id tool-001 --tool tests --result "Tests passed." --evidence "Local run." --confidence high --salience 4 --note
python -m agent_memory.adapters.agent note --path .agent-memory
python -m agent_memory.adapters.agent handoff --path .agent-memory

Use the multi-agent adapter:

python -m agent_memory.adapters.multi_agent init --path .agent-memory-multi --role planner --role researcher
python -m agent_memory.adapters.multi_agent shared-decision --path .agent-memory-multi --id decision-001 --text "Use shared memory only for confirmed decisions." --evidence "Team agreement." --confidence high --salience 5 --role planner
python -m agent_memory.adapters.multi_agent note --path .agent-memory-multi
python -m agent_memory.adapters.multi_agent handoff --path .agent-memory-multi

Repository Layout

SECURITY.md
ROADMAP.md
agent_memory/
  core.py
  cli.py
  adapters/agent.py
  adapters/codex.py
  adapters/chat.py
  adapters/multi_agent.py
agent-memory/
  SKILL.md
  agents/openai.yaml
  references/
  scripts/memory_packet.py
examples/
  agent-run-demo/{state.json,memory-briefing.md,migration-packet.md,agent-run-note.md}
  chat-memory-demo/{state.json,memory-briefing.md,migration-packet.md,chat-memory-note.md}
  codex-memory/{state.json,memory-briefing.md,migration-packet.md}
  multi-agent-demo/{multi-agent-note.md,shared/,roles/}
  topic-interruption-demo/{state.json,migration-packet.md}
docs/
  agent-adapter.md
  adapter-contract.md
  adaptive-integration.md
  architecture.md
  handoff.md
  memory-briefing.md
  chat-adapter.md
  demo-chat-memory.md
  demo-agent-run.md
  demo-multi-agent.md
  codex-adapter.md
  evaluation.md
  existing-agent-integration.md
  json-schema.md
  memory-candidates.md
  memory-compaction.md
  memory-doctor.md
  memory-selection.md
  memory-updates.md
  multi-agent-adapter.md
  opening-plans.md
  privacy-and-safety.md
  portable-bundles.md
  release.md
  demo-topic-interruption.md
  problem-map.md
  research-pain-points.md
tests/
  test_memory_packet.py
schemas/
  state.schema.json
scripts/
  demo_memory_flow.py
  evaluate_memory_scenarios.py
  install_skill.py
  validate_release.py

Problem Coverage

See docs/problem-map.md for the mapping between current agent-memory pain points and the mechanisms in this project.

See docs/research-pain-points.md for the broader public pain-point scan that informs the roadmap.

See ROADMAP.md for planned adapter hardening, expanded retrieval, compaction policy work, and runtime integration work.

See docs/architecture.md for the skill/core/adapter split.

See docs/adaptive-integration.md for bootstrap/augment/audit modes, session health, and the Yanheng long-session slowdown case.

See docs/existing-agent-integration.md for adding Agent Memory to an agent that already has memory without overwriting its current system.

See docs/adapter-contract.md for the required behavior of new runtime adapters.

See docs/codex-adapter.md for the first runtime adapter.

See docs/chat-adapter.md for ordinary AI conversation memory.

See docs/agent-adapter.md for autonomous agent run memory.

See docs/multi-agent-adapter.md for shared and role-local memory.

See docs/memory-doctor.md for memory quality audits.

See docs/privacy-and-safety.md for privacy, source/scope, review, retention, and adapter safety guidance.

See docs/memory-briefing.md for the short startup context used before a fuller migration packet.

See docs/opening-plans.md for preserving complex task plans, phases, acceptance criteria, and validation commands.

See docs/memory-selection.md for selecting targeted high-signal records without loading the full packet.

See docs/memory-candidates.md for candidate memories that stay out of startup context until review.

See docs/memory-updates.md for replacing outdated preferences, facts, or decisions without keeping conflicting active memory.

See docs/memory-compaction.md for reviewable cleanup plans that mark low-signal memory stale without deleting audit history.

See docs/portable-bundles.md for exporting and importing memory between runtimes.

See docs/evaluation.md for behavior scenarios that validate the project's core memory claims.

See docs/handoff.md for the one-command handoff workflow.

See docs/json-schema.md for state.json schema usage.

See docs/release.md for the GitHub release checklist.

Security And Privacy

Memory files can contain sensitive project context or personal preferences. Keep them local unless an adapter explicitly documents remote storage, avoid storing secrets or raw transcripts, tag unreviewed external records with untrusted, and run doctor before sharing examples.

See SECURITY.md for vulnerability reporting and docs/privacy-and-safety.md for memory-specific safety guidance.

Skill Or Library?

The first version is a skill because the most important behavior is procedural:

• when to read memory
• what deserves to be remembered
• how to handle topic switches
• how to prepare a model handoff
• how to avoid transcript dumping

The long-term shape can be:

• skill: the agent-facing operating guide
• agent_memory.core: schema, scoring, validation, topic stack operations, and packet rendering
• adapters: Codex, chat, autonomous agent, and multi-agent integrations

Publishing Checklist

Before publishing on GitHub:

• Run python scripts/validate_release.py.
• Run python scripts/evaluate_memory_scenarios.py if you want to inspect behavior checks directly.
• Review SECURITY.md and docs/privacy-and-safety.md.
• Follow docs/release.md.
• Optionally record a short screencast or GIF of the topic interruption demo.
• Decide whether examples should be English-only, Chinese-only, or bilingual.
• Add a version tag such as v0.2.0.

Development

Run tests:

python -m unittest discover -s tests

Run the full release validation used by CI:

python scripts/validate_release.py

Run the behavior evaluator directly:

python scripts/evaluate_memory_scenarios.py

Validate examples:

python -m agent_memory validate --path examples/chat-memory-demo
python -m agent_memory validate --path examples/agent-run-demo
python -m agent_memory validate --path examples/codex-memory
python -m agent_memory validate --path examples/topic-interruption-demo
python -m agent_memory validate --path examples/multi-agent-demo/shared
python -m agent_memory validate --path examples/multi-agent-demo/roles/planner
python -m agent_memory validate --path examples/multi-agent-demo/roles/researcher
python -m agent_memory doctor --path examples/chat-memory-demo
python -m agent_memory handoff --path examples/codex-memory
python -m agent_memory schema

License

MIT License. See LICENSE.

Status

Prototype v0.2. The current version is suitable for early local testing of adaptive integration, session health, and handoff workflows.