Agent Memory Bank

A persistent memory system for storing knowledge that survives across conversations — for any domain: code, business, personal, research, creative work, client management, and more.

Default location: ./memory/ (create if it doesn't exist)

Default structure:

./memory/episodic/
./memory/semantic/
./memory/procedural/

Core Philosophy

Three memory types, one system: Store experiences as episodic, durable facts and evolving state as semantic, and repeatable workflows as procedural.
Use the shape that matches future retrieval: Save things based on how you'll want to find them later — what happened, what is true, or how to do it.
Prefer history over rewrites: When an event or decision matters in its own right, preserve it as a dated record rather than erasing what came before.
But don't spam: Update living records when the goal is to maintain current state or current instructions.
Never delete memory files — mark outdated ones with status: superseded instead.
Write for resumption: Notes should be self-contained — a future session with zero context should still understand them.
Bias toward usefulness: Save things that may matter later, especially details that are easy to forget but annoying to rediscover.
Tags are first-class: Tag memories so they can be searched quickly across domains, projects, people, and topics with rg.

Quick Routing Cheat Sheet

Use this fast decision tree when deciding what to save:

Ask: what will future-you want back?
If the answer is what happened? -> save episodic
If the answer is what is true now? -> save or update semantic
If the answer is how do we do this? -> save or update procedural
If the answer is more than one of those -> save it in more than one form

Mini examples:

"We had a nasty auth incident today" -> episodic
"The client prefers weekly async updates" -> semantic
"Here is the release checklist" -> procedural
"A failed deploy taught us a safer rollout order" -> episodic + procedural
"A conversation revealed a lasting user preference" -> episodic + semantic

Memory Types

Episodic

Use for events, moments, decisions-in-context, meetings, incidents, milestones, discoveries, failed attempts, and progress snapshots.

This answers: what happened?

Examples:

A debugging session that revealed the root cause
A client call and the decisions made during it
A travel day where something went wrong
A negotiation update or milestone reached

Semantic

Use for durable knowledge, evolving facts, preferences, profiles, constraints, current project state, and anything that may be updated many times over.

This answers: what is currently true?

Examples:

User communication preferences
Current architecture constraints
Client profile and standing preferences
Active project status and known risks

Procedural

Use for repeatable methods, checklists, workflows, instructions, playbooks, routines, and standard ways of doing things.

This answers: how do we do this?

Examples:

How to deploy safely
Weekly reporting workflow
Travel packing checklist
How to onboard a new client

One interaction may produce more than one memory type. That's good.

Example:

An incident happens -> save an episodic note
It reveals a durable constraint -> update a semantic note
It teaches a better workflow -> update a procedural note

How to Route New Information

Ask these questions:

Is this mainly an event or time-bound moment?
- Save episodic
Is this a durable fact, preference, constraint, or current state?
- Save or update semantic
Is this a repeatable method or instruction?
- Save or update procedural
Does it fit more than one?
- Save it in more than one form when future retrieval would differ

Examples:

"We debugged auth and found the cookie domain was wrong"
- episodic: the debugging session
- semantic: auth depends on the correct parent-domain cookie setting
"The client prefers weekly async updates"
- semantic: client preference
"Here is our monthly reporting process"
- procedural: recurring workflow
"Friday's failed deploy taught us to run migrations before workers"
- episodic: failed deploy
- procedural: safer release workflow

Proactive Saving

Since this skill is loaded, memory is clearly valued here — lean into it. Save without being asked when you encounter:

Something that took real effort to figure out (research, debugging, negotiation, comparison)
A decision with non-obvious reasoning — why X over Y
Information that would be painful to reconstruct if this conversation ended
Dead ends and failed approaches — saves future sessions from repeating them
In-progress work with clear next steps
Anything the user seems to care about that isn't obvious from context alone

Applies to any domain — code, business, personal, creative, research, client work, anything.

File Naming

episodic:   YYYY_MM_DD_meaningful_name.md
semantic:   stable_subject_name.md
procedural: how_to_meaningful_name.md

Examples — notice these span many domains:

2025_03_09_auth_bug_root_cause.md
2025_03_10_q1_marketing_decisions.md
user_preferences.md
client_acme_profile.md
project_helios_status.md
how_to_rotate_api_keys.md
weekly_client_reporting_workflow.md

Multiple episodic files per day are normal and encouraged. Semantic and procedural files should usually keep stable names so they can be updated over time.

Creating a Memory File

Use your native file tools to create and edit memory files.

Shared frontmatter fields:

---
summary: "One line — specific enough to know if you need to read this"
created: YYYY-MM-DD
updated: YYYY-MM-DD
memory_type: episodic | semantic | procedural
tags: [optional, tags]
---

Episodic template:

---
summary: "Debugging session that found the auth cookie domain mismatch"
created: YYYY-MM-DD
updated: YYYY-MM-DD
memory_type: episodic
tags: [code, auth, debugging, incident]
---

# Title

[Write the event clearly enough that a future session understands what happened and why it mattered]

Semantic template:

---
summary: "Current auth configuration constraints for production"
created: YYYY-MM-DD
updated: YYYY-MM-DD
memory_type: semantic
tags: [code, auth, configuration, project-helios]
---

# Title

[Write the current known state, preferences, constraints, or facts that should remain current over time]

Procedural template:

---
summary: "Safe production deploy workflow"
created: YYYY-MM-DD
updated: YYYY-MM-DD
memory_type: procedural
tags: [code, deploy, workflow, operations]
---

# Title

[Write the repeatable process clearly enough that someone can follow it later]

Some section ideas (use only what fits):

Context — why this matters, background
Key Decisions — what was decided and why
Details / Findings — the actual content worth saving
Current State — the up-to-date truth right now
Procedure / Checklist — ordered steps or repeatable instructions
Lessons Learned — what this teaches for future work, mistakes to avoid, or patterns worth reusing
People / Contacts — who's involved
Next Steps — what to do next
Didn't Work — dead ends to avoid

There's no required structure. A memory for a client call looks different from a debugging session — that's fine.

Editing an Existing Memory

Use your native file editing tools to update memory files.

Update episodic when:

You're still actively adding details to the same event or session
You want to complete or correct the record of what happened

Update semantic when:

The current state, preference, fact, or constraint has changed
You learned something that refines a long-lived record
You want one stable file to represent the latest understanding

Update procedural when:

The workflow changed
A checklist was improved
You discovered a safer, faster, or clearer way to do the task

When a change deserves both history and current state, do both:

create or update an episodic file for the event
update the relevant semantic or procedural file for the lasting takeaway

Searching Memories

Quick orientation (run this first when memories feel relevant)

rg --files ./memory | sort

This shows the files that exist across all memory types — a fast orientation to what's here.

Search by memory type

rg "^memory_type: episodic$" ./memory/ --no-ignore
rg "^memory_type: semantic$" ./memory/ --no-ignore
rg "^memory_type: procedural$" ./memory/ --no-ignore

Read summaries across all files

rg "^summary:" ./memory/ --no-ignore

Search by keyword (full text)

rg "keyword" ./memory/ --no-ignore -i

Search summaries only

rg "^summary:.*keyword" ./memory/ --no-ignore -i

Search by tag

rg "^tags:.*keyword" ./memory/ --no-ignore -i

Search by tag combination

rg "^tags:.*auth.*project-helios|^tags:.*project-helios.*auth" ./memory/ --no-ignore -i

Search semantic memories for current state

rg "keyword" ./memory/semantic/ --no-ignore -i

Search procedural memories for how-to guidance

rg "keyword" ./memory/procedural/ --no-ignore -i

Search episodic memories for what happened

rg "keyword" ./memory/episodic/ --no-ignore -i

After finding relevant files, read them using your native file tools. The summary tells you if it's worth reading; reading gives you the actual context.

When to Check Memories

Default behavior: check memories when the task feels like it might connect to prior work — e.g. the user references a past decision, says "like we discussed", or you're about to re-research something familiar.

This default can be overridden by the environment. A system prompt may instruct you to always check memories, or only check when explicitly asked — follow those instructions. This skill describes the fallback when no such instruction exists.

When checking:

orient quickly to what exists
choose the memory type that matches the question
search by tags, keywords, and summaries
read the most relevant files for actual context

Use this retrieval pattern:

episodic for "what happened?"
semantic for "what do we know now?"
procedural for "how do we do this?"

When to Save

No strict rules — use judgment. Good candidates:

Something that took real effort to figure out
A decision with non-obvious reasoning behind it
Information you'd lose if this conversation ended now
Anything the user explicitly wants remembered
A preference, profile, or constraint likely to matter again
A workflow or checklist you'll likely reuse
A bug, config detail, or environment-specific gotcha that could bite again later

Not worth saving:

Easily googleable facts
Transient scratchpad work
Anything the user will obviously remember themselves

Cleanup and Distillation

Do not aggressively reorganize or distill memories by default.

Only do memory cleanup when:

The user asks to organize, clean up, archive, consolidate, or review memories
You are already working inside the memory folder and obvious cleanup is part of the task

When cleaning up memories:

Prefer marking outdated files with status: superseded or moving them into an archive/ folder if such a structure already exists or the user asks for it
Avoid deleting memory files unless the user explicitly requests deletion
Preserve historical context; do not collapse distinct events into one vague note
Merge or simplify only when duplicates are clearly redundant and the result is more useful than the originals
Keep tags consistent so search stays clean

Distill carefully:

Promote repeated or clearly durable facts into semantic memory when you have good evidence they should be long-lived
Promote repeatable workflows into procedural memory when they are clearly meant to be reused
If you are not confident, preserve the original memory and avoid over-distilling

If the user asks to "clean up my memories", a good default is:

review for stale or superseded files
archive or mark outdated material
tighten titles and tags
leave meaningful history intact

When to Create vs Update a File

Create a new file when:

You are recording a distinct event, session, decision point, incident, or milestone
You are starting a new topic with no current memory for it
You want to preserve a dated snapshot of what happened at a specific point in time

Update an existing file when:

You are maintaining an ongoing semantic record of current state
You are improving an existing procedure or checklist
A stable file for this subject already exists and should remain the source of truth

The goal is to avoid both extremes: don't spam new files for every tiny change, but don't flatten meaningful history into one endlessly edited document either.

When in doubt:

choose episodic if the value is historical context
choose semantic if the value is current truth
choose procedural if the value is repeatable guidance
choose more than one if needed

When something evolves across clearly distinct phases, new files tell a useful story:

2025_03_09_supplier_negotiation_initial.md
2025_03_10_supplier_negotiation_counteroffer.md
2025_03_11_supplier_negotiation_final_terms.md

To mark a file as outdated, add status: superseded to its frontmatter — don't delete it.

File Organization

By default, organize memory by type:

./memory/episodic/
./memory/semantic/
./memory/procedural/

You may also encounter or be instructed to use a more structured layout such as ./memory/semantic/clients/ or ./memory/procedural/operations/. Follow whatever structure exists; if none exists, use the default type-based layout.

memory-bank

Agent Memory Bank

Core Philosophy

Quick Routing Cheat Sheet

Memory Types

Episodic

Semantic

Procedural

Tags

How to Route New Information

Proactive Saving

File Naming

Creating a Memory File

Editing an Existing Memory

Update episodic when:

Update semantic when:

Update procedural when:

Searching Memories

Quick orientation (run this first when memories feel relevant)

Search by memory type

Read summaries across all files

Search by keyword (full text)

Search summaries only

Search by tag

Search by tag combination

Search semantic memories for current state

Search procedural memories for how-to guidance

Search episodic memories for what happened

When to Check Memories

When to Save

Cleanup and Distillation

When to Create vs Update a File

File Organization