memory-bank

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/ — active events (last 7 days)
./memory/semantic/ — durable facts and current state
./memory/procedural/ — repeatable workflows and how-tos
./memory/archive/ — compressed episodic memories (auto-managed)
./memory/summaries/episodic/weekly/ — weekly digests of archived episodic files
./memory/summaries/episodic/monthly/ — monthly rollups of weekly digests
./memory/INDEX.md — auto-maintained living map

Core Philosophy

Three memory types, one system: Store experiences as episodic, durable facts and evolving state as semantic, and repeatable workflows as procedural.
Episodic = diary. Semantic & Procedural = wiki. episodic gets new dated entries. semantic and procedural are living reference pages that should usually be updated over time instead of duplicated per session.
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.
INDEX.md is the map: After creating or updating memories, rebuild INDEX.md so future sessions (and you) can scan the whole landscape in seconds.

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
Short version: episodic = what happened, semantic = what is true, procedural = what works next time
If the answer is more than one of those, and each would be retrieved differently -> save in multiple forms (but in most cases, one file is enough)

Mini examples:

"We had a nasty auth incident today" -> episodic
"The client prefers weekly async updates" -> semantic
"Here is the release checklist" -> procedural
"The user dislikes meetings when hungry" -> semantic; "avoid scheduling important meetings when they're hungry" -> procedural
"A failed deploy taught us a safer rollout order" -> episodic + procedural (the event and the new workflow are both worth preserving)
"A conversation revealed a lasting user preference" -> episodic

Most knowledge fits cleanly into one memory type. Only create multiple files when the same information genuinely needs to be retrieved in two or more fundamentally different ways.

Do not overfit one weak moment into a lasting fact or rule too quickly.

Memory Types

These three types are universal — they work for code, business, personal life, creative work, research, and any domain where you need to remember things. The examples below span many contexts to show that flexibility.

Episodic

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

This answers: what happened?

Examples across domains:

Code: A debugging session that revealed the root cause
Business: A client call and the decisions made during it
Personal: A travel day where something went wrong
Creative: A songwriting session where the chorus finally clicked
Research: A lab experiment that produced an unexpected result
Relationship: A conversation that clarified a misunderstanding

Semantic

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

This answers: what is currently true?

Think of semantic memory as a wiki page, not a diary entry. Prefer one stable file per subject that accumulates updates over time. Do not create a new semantic file just because a new session happened.

Examples across domains:

User/Client: Communication preferences, timezone, dietary restrictions, preferred meeting times
Project: Current architecture constraints, active risks, tech stack choices
Personal: Health metrics, financial goals, location, current reading list
Creative: Established world-building rules, character traits, thematic constraints
Behavioral: How the user likes to be addressed, tone preferences, boundaries

Important: Semantic is not just "project facts" — it is any durable truth about the world you operate in, including people, projects, and yourself.

Think: semantic stores what is true.

Procedural

Use for repeatable methods, behavioral guidance, checklists, workflows, instructions, playbooks, routines, and standard ways of doing things — including how to approach situations, how to adapt to a person, and how to behave in the future.

This answers: how do we do this? and how should I behave?

Think of procedural memory as a wiki page for behavior and workflows. It stores not only productivity steps, but also the learned ways to navigate recurring human situations well. Keep the canonical checklist, playbook, or adaptation guide in one stable file and revise it as the process improves, instead of creating a fresh procedural note per conversation.

Examples across domains:

Code: How to deploy safely, code review checklist, incident response playbook
Business: Weekly reporting workflow, client onboarding steps, negotiation prep routine
Personal: Travel packing checklist, morning routine, weekly reflection process
Behavioral: How to approach sensitive topics with this user, tone guidance for difficult conversations, when to escalate vs. handle independently
Adaptive assistant: If the user hates meetings when hungry, choose better meeting times; if the user is angry, start with calming acknowledgment before problem-solving; if a user shuts down under overload, reduce options and keep replies short
Creative: The revision checklist, how to critique a draft without crushing morale

Important: Procedural is not just "task execution." It is any repeatable pattern of behavior — including how you (or the system) should act in specific contexts, how to adapt to this user, and what response patterns tend to work. If semantic memory stores what is true, procedural memory stores what works.

Multiple types from one interaction

An interaction might span multiple memory types — but don't force it. Usually, one well-chosen file is enough.

Example of when multiple files are warranted:

An incident happens -> save an episodic note (the event)
It reveals a durable constraint different from the event -> also update a semantic note (the constraint)
It teaches a better workflow -> also update a procedural note (the procedure)

If the same takeaway can be captured in one file, stop there. Multiple files are only useful when retrieval differs materially.

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 truly span multiple categories in ways you'd search for differently?
- Only then save in multiple forms. In most cases, one file is enough — don't create extra files just because the knowledge technically touches more than one category.

Simple promotion rule:

If it matters as what happened -> episodic
If it changes what is true -> semantic
If it changes what to do next time -> procedural

Examples across domains:

Code: "We debugged auth and found the cookie domain was wrong"
- episodic: the debugging session
- semantic: auth depends on the correct parent-domain cookie setting
Business: "The client prefers weekly async updates"
- semantic: client preference
Business: "Here is our monthly reporting process"
- procedural: recurring workflow
Code: "Friday's failed deploy taught us to run migrations before workers"
- episodic: failed deploy
- procedural: safer release workflow
Personal/Behavioral: "The user gets overwhelmed by long explanations; they prefer concise bullet points"
- semantic: user's communication preference
Personal/Behavioral: "When the user is stressed, acknowledge their feelings first before proposing solutions"
- procedural: behavioral approach for stressed-user interactions
Creative: "The protagonist's backstory was finalized: orphan, raised by wolves, afraid of fire"
- semantic: character profile (durable fact)
Creative: "Songwriting sessions work best when I start with the melody, not lyrics"
- procedural: creative process guidance

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:

Code: 2025_03_09_auth_bug_root_cause.md
Business: 2025_03_10_q1_marketing_decisions.md
Personal: user_preferences.md, health_tracking_setup.md
Business: client_acme_profile.md, project_helios_status.md
Code: how_to_rotate_api_keys.md, incident_response_playbook.md
Behavioral: how_to_approach_stressed_user.md, tone_guidance_for_sensitive_topics.md
Creative: character_ariel_backstory.md, songwriting_process.md
Business: 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.

Rule of thumb:

episodic/ = many dated files over time
semantic/ = one evolving file per topic
procedural/ = one evolving file per workflow or behavior pattern

Optional YAML Fields (Obsidian-Compatible)

The shared frontmatter supports extra fields. Use any, all, or none — they are optional.

---
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 | decision | person | project
tags: [optional, tags]
status: active | superseded | draft | archived
confidence: certain | likely | tentative | deprecated
related: [other_file.md, another.md]
aliases: [alt-name]
source: "where this came from"
---

status: mark outdated files with superseded instead of deleting them
confidence: signal how solid this knowledge is
related: backlinks to other memory files for graph traversal
aliases: alternate names to search by
source: URL, conversation ID, document name, or person

These fields make the memory graph richer without adding complexity for simple notes.

Templates

Templates live in skills/memory-bank/templates/. Copy the one matching your memory type and fill it in.

Template	Use when
`templates/episodic.md`	Recording an event, meeting, incident, or session
`templates/semantic.md`	Capturing durable facts, state, preferences, or constraints
`templates/procedural.md`	Writing a repeatable workflow, checklist, how-to, or behavioral guidance
`templates/decision.md`	Documenting an architectural or strategic decision (ADR style)
`templates/person.md`	Profiling a person — client, colleague, contact
`templates/project.md`	Tracking a project's current state, risks, and milestones

How to use:

Pick the template that matches what you're saving
Copy it into the correct memory/<type>/ folder with a meaningful filename
Fill in the frontmatter and body
Run the index script (see below)

Use only the sections that fit. A memory for a client call looks different from a debugging session — that's fine.

Dream / background maintenance reference

If you want to run memory-bank in a recurring, background, or semi-autonomous "dream mode" pass, see:

skills/memory-bank/references/dream-mode.md

That reference explains how to:

treat dream as a retrieval-first operating mode, not a new memory type
decide what matters in prior material
sort information into episodic, semantic, and procedural
handle ambiguity, conflict, and update thresholds
update existing canonical files instead of duplicating them

Use the normal memory-bank templates and file types during dream mode. The reference is just the shortcut path for how to operate when the task is "dream / background consolidation / review prior context".

Scripts

Helper scripts live in skills/memory-bank/scripts/. Run them from the project root.

Script	Purpose
`scripts/init.py`	Scaffold `./memory/` with core folders and a starter `INDEX.md`
`scripts/index.py`	Scan all memories and rebuild `memory/INDEX.md` with links, summaries, and tag indexes

After creating or updating memories, rebuild the index:

python skills/memory-bank/scripts/index.py

This keeps INDEX.md as a living map of everything saved. Future sessions should check INDEX.md first for orientation.

Never update INDEX.md by hand. It is a generated artifact. If you want the index to read better, update the underlying memory files (especially their summary, tags, status, or filenames) and then run the index script again.

INDEX.md Maintenance

INDEX.md lives at ./memory/INDEX.md. It is auto-generated — do not hand-edit it.

Treat INDEX.md like build output:

do not manually add notes there
do not manually fix links there
do not manually rewrite entries there
anything written there by hand can be wiped out the next time index.py runs

If the index looks wrong or incomplete:

fix the actual memory files
then rerun python skills/memory-bank/scripts/index.py

What it contains:

Table of contents by memory type
Every memory file as a link + its summary line
Status badges (e.g., [superseded]) for quick filtering
A full tag index at the bottom

When to rebuild:

After creating a new memory
After updating a memory with a changed summary, tags, or status
After batch cleanup or reorganization
Before ending a session where memory work happened

How to rebuild:

python skills/memory-bank/scripts/index.py

If you updated one or many memory files, call the script. Do not try to keep INDEX.md in sync manually.

Orientation shortcut for future sessions:

# See the whole landscape
bat ./memory/INDEX.md

# Or just the summaries
grep "^\- \[" ./memory/INDEX.md

Episodic Compression

The index script automatically compresses old episodic memories to keep the active folder lean.

How it works:

Weekly: episodic files older than 7 days are moved to archive/
A weekly digest is generated at summaries/episodic/weekly/YYYY-WNN.md listing all archived files for that week with summaries and tags
Monthly: once a month completes, a monthly digest is generated at summaries/episodic/monthly/YYYY-MM.md linking to its 4–5 weekly digests

Why:

Active episodic/ stays scannable (no 100-file noise)
You can still find anything by searching archive/ or summaries/
Weekly/monthly summaries give you the "what happened that week/month" overview without opening individual files

This is automatic — just run index.py and it handles housekeeping. Do not manually move files into archive/.

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.

Read the index

cat ./memory/INDEX.md

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

Search archived episodic memories (deep dive)

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

Search weekly/monthly summaries (overview)

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

Search everything at once (nuclear option)

rg "keyword" ./memory/ --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, checklist, or behavioral pattern you'll likely reuse
A bug, config detail, or environment-specific gotcha that could bite again later
Behavioral guidance — how to approach a situation, tone rules, interaction patterns that work well with this user or context

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
Do not turn one weak incident into a lasting semantic belief or procedural law too quickly
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
rebuild INDEX.md so the map reflects reality

When to Create vs Update a File

One-line rule: episodic creates history; semantic and procedural maintain canonical pages.

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

Practical default:

If a matching semantic or procedural file already exists, update it
Only create a new semantic or procedural file when the topic is genuinely new or the existing file has become meaningfully different in scope
Do not create duplicate semantic/procedural files just because today's conversation added another fact or tweak
When information conflicts, newer knowledge usually takes precedence, but update gently and preserve uncertainty when needed

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 ONLY if the retrieval needs differ materially (rare)

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/ — active events only (files >7 days auto-move to archive/)
./memory/semantic/ — durable facts and state
./memory/procedural/ — workflows and how-tos
./memory/archive/ — auto-managed; do not manually edit
./memory/summaries/episodic/weekly/ — auto-generated weekly digests
./memory/summaries/episodic/monthly/ — auto-generated monthly rollups

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.

New types: Decision, person, and project memories may live in their respective type folders or in a flat structure — consistency matters more than depth. If you create ./memory/decision/, ./memory/person/, or ./memory/project/, the index script will find and catalog them automatically.

About this skill

Core Philosophy

Quick Routing Cheat Sheet

Memory Types

Episodic

Semantic

Procedural

Multiple types from one interaction

Tags

How to Route New Information

Proactive Saving

File Naming

Optional YAML Fields (Obsidian-Compatible)

Templates

Dream / background maintenance reference

Scripts

INDEX.md Maintenance

Episodic Compression

Searching Memories

Quick orientation (run this first when memories feel relevant)

Read the index

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

Search archived episodic memories (deep dive)

Search weekly/monthly summaries (overview)

Search everything at once (nuclear option)

Related links

When to Check Memories

When to Save

Cleanup and Distillation

When to Create vs Update a File

File Organization