Agent Memory OS#

Build an agent that gets more organized over time instead of more chaotic.

Turn an agent's memory from "a pile of chat history" into a long-term working memory operating system.

What problem this solves#

A lot of agents look impressive in short conversations, then collapse under real work:

• they forget what matters
• active projects pollute long-term memory
• useful lessons never become reusable rules
• the system looks good for a week, then decays

This skill exists to fix that.

It helps the agent move from:

• "I remember fragments"

to:

• "I have a stable global brain, project-specific working brains, reusable lessons, validation logic, and a maintenance loop that keeps the whole system healthy."

What makes this different#

This is not just:

• note-taking guidance
• a vector-search recipe
• a memory dump strategy

It is a workflow for building an agent memory system with:

• separation of concerns
• promotion paths for reusable knowledge
• validation cases
• operational maintenance rules

Use this skill when#

The user says or implies things like:

• "My agent keeps forgetting"
• "Once projects pile up, everything gets messy"
• "I want long-term memory for my AI agent"
• "I need project memory separated from global memory"
• "I want reusable lessons, not just logs"
• "I want to share or standardize an agent memory setup"

Example trigger prompts#

This skill should feel natural on prompts like:

• "Help me design long-term memory for my coding agent."
• "My AI assistant keeps mixing projects and forgetting context."
• "I need a reusable memory architecture for multi-project agents."
• "How do I separate durable agent memory from active project memory?"
• "Help me turn chat history into a reusable working-memory system."

What the user gets#

By the end of this workflow, the user should have:

1. a memory architecture that separates global and project concerns
2. a minimum project-memory structure
3. routing and promotion rules
4. validation cases to prove the system works
5. a maintenance runbook so it does not decay immediately

Privacy and publishing rule#

When using this skill for sharable/public output:

• never expose real user names, private IDs, workspace-specific secrets, session paths, internal message IDs, or private document URLs
• rewrite examples into generalized patterns
• replace personal/project-specific references with neutral placeholders
• do not bundle private memories, raw chat excerpts, or personally identifying workflow traces into the skill

If the user explicitly wants a public/shareable version, treat privacy-preserving abstraction as mandatory, not optional.

Recommended workflow#

Step 0 — Decide whether to use a full memory system#

Not every agent needs this full setup.

Read references/architecture-decision-guide.md when the user is unsure whether they need a full global / project / bridge system, or whether a simpler setup is enough.

Step 1 — Diagnose the real memory problem#

Classify the user's issue before proposing architecture.

Typical failure modes:

• single-brain overload: everything is dumped into one place
• project pollution: local project state contaminates long-term memory
• retrieval confusion: the agent doesn't know where to look first
• knowledge stagnation: lessons never graduate into reusable rules
• maintenance decay: the structure exists but slowly becomes stale

Read references/failure-modes.md when you need a sharper diagnosis rubric.

Step 2 — Choose the architecture#

Default recommendation: a three-part system

• global memory for durable rules, preferences, SOPs, stable principles
• project memory for local complexity and active work
• bridge/promotions for candidate → promoted → canonical evolution

Read references/architecture.md when you need the design rationale.

Step 3 — Create the minimum working structure#

For each project, start with 5 files:

• PROJECT.md
• STATUS.md
• DECISIONS.md
• ASSETS.md
• LESSONS.md

Use the bundled templates in:

• assets/project-templates/
• assets/bridge-templates/

Step 4 — Define routing and promotion rules#

Make sure the agent knows:

• what belongs to global memory
• what stays project-local
• what becomes a candidate for reuse
• what evidence is required before promotion

Read:

• references/routing.md
• references/promotion.md

Step 5 — Validate with concrete cases#

Do not stop at design. Test the system with at least 3 case types:

• continuous project execution
• interruption and recovery
• cross-project reuse

Use measurable criteria: recovery accuracy, unnecessary follow-up questions, reuse success, structure completeness, etc.

Read references/validation.md for a compact validation model.

Step 6 — Add a maintenance runbook#

A memory system is not done when designed. It is done when it can be maintained.

Define:

• when to update daily logs
• when to update project status
• when to record lessons
• when candidates get promoted
• when to deprecate outdated rules
• how often to review global/project/bridge memory

Read references/maintenance.md when writing or reviewing the runbook.

Minimal success path#

A good first run of this skill usually looks like:

1. identify the dominant failure mode
2. choose the global/project/bridge architecture
3. create the 5 core project files
4. define one promotion rule and one routing rule
5. validate with one interruption-recovery case and one reuse case
6. write a simple maintenance rhythm

If the agent can recover better, reuse more, and stay cleaner over time, the system is working.

Packaging guidance#

Keep the public skill:

• short in SKILL.md
• practical in workflow
• generalized in examples
• private details removed

Do not include:

• personal identifiers
• real workspace paths tied to an individual
• raw private conversation excerpts
• internal-only document links
• unredacted project-specific evidence

Read references/publish-checklist.md before publishing or sharing widely.

Output style for public-facing use#

If the user wants something that attracts attention, write with this shape:

• start from a painful, recognizable problem
• name the failure mode clearly
• present the architecture as a relief pattern
• show a small, concrete workflow
• prove it with validation cases
• end with operational simplicity, not abstract theory

Make it feel like a usable system, not an academic essay.