agent-memory-os

# 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.