Skill: aslan-ai-labs/agent-memory-os (version 0.1.0)

--- name: agent-memory-os description: Stop agents from "forgetting, mixing projects, and rotting over time" by giving them a practical memory operating system: global memory, project memory, promotion rules, validation cases, and a maintenance loop. --- # 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.

path: assets/bridge-templates/candidate.template.md
content: # candidate

## Purpose
Track a potentially reusable lesson that is not fully proven yet.

## Minimum fields
- title
- source
- why it might matter
- current evidence
- boundary
- next validation needed


path: assets/bridge-templates/canonical.template.md
content: # canonical

## Purpose
Track a rule, SOP, or principle that is stable enough to become a default global reference.

## Minimum fields
- title
- canonical statement
- evidence base
- scope / boundary
- replacement / downgrade rule if needed


path: assets/bridge-templates/promoted.template.md
content: # promoted

## Purpose
Track a reusable lesson that has enough evidence to be elevated beyond one project.

## Minimum fields
- title
- source
- evidence
- reusable pattern
- scope / boundary
- validation history


path: assets/project-templates/ASSETS.template.md
content: # ASSETS.md

## Purpose
Index the project's important documents, files, tables, scripts, and outputs.

## Recommended sections
- Core documents
- Supporting documents
- Structured tracking tables
- Repositories / paths
- Deliverables


path: assets/project-templates/DECISIONS.template.md
content: # DECISIONS.md

## Purpose
Record important decisions so they do not remain trapped in chat history.

## Recommended sections
- Decision title
- Context
- Options considered
- Final choice
- Impact scope
- Evidence links
- Status


path: assets/project-templates/LESSONS.template.md
content: # LESSONS.md

## Purpose
Capture lessons, effective patterns, failed approaches, and candidate reusable knowledge.

## Recommended sections
- Lessons learned
- Effective patterns
- Failed approaches
- Candidate items for promotion
- Evidence/source


path: assets/project-templates/PROJECT.template.md
content: # PROJECT.md

## Purpose
Describe what this project is, why it exists, what success looks like, and where to go next.

## Recommended sections
- Project goal
- Scope
- Constraints
- Success criteria
- Navigation to STATUS / DECISIONS / ASSETS / LESSONS


path: assets/project-templates/STATUS.template.md
content: # STATUS.md

## Purpose
Track where the project currently stands.

## Recommended sections
- Current stage
- Completed
- In progress
- Next step
- Risks / blockers
- Last updated


path: references/architecture-decision-guide.md
content: # Architecture Decision Guide

Use this guide when the user is unsure whether they need a full memory system.

## Start simple if
- work is mostly one-off chat
- there are no long-lived projects
- durable lessons are not yet important
- maintenance overhead would exceed the value

## Upgrade to a memory system if
- the agent repeatedly loses context
- multiple projects are active at once
- the user wants reusable lessons, not just logs
- project-local state keeps polluting long-term memory
- people want something sharable or standardizable

## Use the full global / project / bridge model when
- long-term memory and active work must stay separate
- multiple projects need independent working brains
- reusable knowledge should flow upward over time
- validation and maintenance matter, not just storage

## Rule of thumb
If the pain is "my agent forgets once in a while," do not overbuild.
If the pain is "my agent becomes chaotic as work scales," this skill is likely a strong fit.


path: references/architecture.md
content: # Architecture

## Recommended default

Use a three-part memory system:
- **global memory**
- **project memory**
- **bridge/promotions**

## Why this works

### Global memory
Use for:
- durable preferences
- stable operating rules
- long-lived SOPs
- architecture principles
- high-confidence lessons

### Project memory
Use for:
- active project state
- local decisions
- project assets
- project-specific lessons
- temporary complexity

### Bridge/promotions
Use for:
- candidate lessons worth tracking
- promoted patterns with evidence
- canonical rules that proved reusable

## Core rule

The global brain is the parent brain.
Project memory is an attached working brain.
Reusable knowledge can flow upward, but project-local clutter must not overwrite the global layer.


path: references/failure-modes.md
content: # Failure Modes

Use this reference when the user says their agent has "memory issues" but the real failure mode is unclear.

## Common failure modes

### 1. Single-brain overload
Symptoms:
- everything goes into one place
- long-term memory contains active project clutter
- retrieval gets slower and noisier over time

### 2. Project pollution
Symptoms:
- project-specific state leaks into global rules
- temporary constraints are treated like stable principles
- long-term memory becomes untrustworthy

### 3. Retrieval confusion
Symptoms:
- the agent does not know where to search first
- the same question leads to different memory paths each time
- semantic search is overused without structure

### 4. Knowledge stagnation
Symptoms:
- lessons are written but never reused
- useful patterns never become SOPs or stable rules
- every new project starts almost from scratch

### 5. Maintenance decay
Symptoms:
- the system looked good when created
- status files go stale
- assets are missing from indexes
- outdated rules never get deprecated

## Diagnosis question
Ask: **Is the main problem storage, retrieval, separation, reuse, or maintenance?**

That answer usually determines the next move.


path: references/maintenance.md
content: # Maintenance

A memory system survives through maintenance, not just design.

## Minimum maintenance loop

### Daily / milestone-based
- update current project status
- record important decisions
- log meaningful lessons or errors

### Weekly
- review project lessons
- review bridge candidates
- fix missing asset indexes

### Every 2-4 weeks
- review global memory for stale rules
- promote what proved reusable
- deprecate what is outdated

## Core questions during review
- what is stale?
- what is missing from indexes?
- what proved reusable?
- what should not stay global?
- what project should be closed, paused, or archived?

## Rule
If maintenance is optional, decay is inevitable.


path: references/promotion.md
content: # Promotion

## Promotion path

Use this evolution path:
- `candidate`
- `promoted`
- `canonical`
- `deprecated` / `superseded` when needed

## Candidate
Use when something looks reusable but is not fully proven yet.

Typical triggers:
- a pattern appears multiple times
- a workflow succeeds once and looks reusable
- a failure creates a durable lesson
- the user explicitly says it should be remembered

## Promoted
Use when the lesson has:
- evidence
- at least one real validation
- some level of generality
- known scope or boundary

## Canonical
Use only when the lesson is:
- proven in multiple contexts
- stable in wording
- strong enough to serve as a default rule or SOP

## Do not promote
- raw chat fragments
- temporary project state
- local workarounds without general value
- unvalidated guesses


path: references/publish-checklist.md
content: # Publish Checklist

Use this checklist before publishing or widely sharing the skill.

## 1. Privacy check
- [ ] No real person names
- [ ] No private IDs
- [ ] No internal session/message IDs
- [ ] No personal workspace paths
- [ ] No private document URLs
- [ ] No raw private chat excerpts
- [ ] No examples that can be traced back to a specific person or team

## 2. Public usefulness check
- [ ] The opening describes a recognizable pain point
- [ ] The result promise is clear in one sentence
- [ ] The workflow is concrete, not abstract
- [ ] The skill includes a minimal success path
- [ ] The user can tell what they will get by the end

## 3. Reusability check
- [ ] Templates are generalized
- [ ] References are not tied to one project
- [ ] Rules are written as reusable patterns
- [ ] Validation guidance states tested scope and boundaries

## 4. Quality check
- [ ] SKILL.md stays concise enough to trigger well
- [ ] Detailed material lives in references/
- [ ] Assets are useful, not decorative
- [ ] Nothing in the skill depends on hidden private context

## 5. Positioning check
- [ ] This reads like a usable system, not a private project archive
- [ ] The title and description are memorable
- [ ] The skill solves a painful problem that many users recognize

If any privacy item fails, do not publish.
If usability is weak, tighten the opening and minimal success path before publishing.


path: references/routing.md
content: # Routing

## Core principle

Decide **scope first**, then choose retrieval path.

Do not default to searching everything.
Do not default to semantic search.

## Practical routing

### Search global memory first when
- the user asks about durable rules
- the question is about preferences, SOPs, or reusable methods
- the issue is cross-project by nature

### Search project memory first when
- the question is about current status
- the issue is clearly local to one project
- the user asks why a project-specific decision was made
- the user needs assets, files, or local milestones

### Use both when
- the question mixes stable rules with current project constraints
- a global method may need project-local adjustment
- a project pattern may need global validation

## Search order
1. structured/navigation-based lookup
2. keyword/full-text lookup
3. semantic recall as a supplement
4. evidence and status check before final answer


path: references/validation.md
content: # Validation

A memory system is not complete when documented. It is complete when tested.

## Minimum validation set

### 1. Continuous execution case
Question: does the system help a complex project keep moving coherently?

### 2. Interruption recovery case
Question: after interruption, can the agent recover stage, reasoning, and next step quickly?

### 3. Cross-project reuse case
Question: can structures, lessons, or templates help the next project start faster?

## Suggested metrics
- recovery accuracy
- follow-up question count
- stage identification accuracy
- reuse success
- structure completeness
- evidence completeness
- subjective usefulness improvement

## Rule
Do not claim broad success from one narrow case.
Always state the tested scope and the non-tested boundary.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)