Memory Fortress 🏰#

A unified memory system that prevents agents from forgetting what they did yesterday and ensures work survives session boundaries in written form.

Built from five proven patterns:

• Compaction-aware saving, disk is truth
• Boot sequence + state files, Dory-proof capture
• Domain organization, keeping MEMORY.md small and useful
• Memory types + priority, for durable recall
• Promote / demote lifecycle, so memory can evolve over time

---

Mental model#

text

┌─────────────────────────────────────────────────────┐
│                   MEMORY FORTRESS                   │
├─────────────────────────────────────────────────────┤
│  🔴 SESSION RAM   → temporary, lost on compaction   │
│  🟡 STATE/        → active task, blockers, decisions│
│  🟢 DAILY LOG     → memory/YYYY-MM-DD.md            │
│  🔵 MEMORY.md     → curated durable knowledge       │
│  ⚪ DOMAINS/       → topic-specific detail           │
│  📦 ARCHIVE/      → older logs                      │
│  🧱 PROJECT FILES → task_plan.md + notes.md + output│
└─────────────────────────────────────────────────────┘

Core principle: session memory is temporary, files are truth.

---

1. Boot sequence — run at the start of every session#

Order matters.

text

1. state/HOLD.md        — what is blocked? do not do these
2. state/ACTIVE.md      — is there an active task?
3. state/DECISIONS.md   — recent decisions, last 48h
4. state/CLOSED.md      — durable closed decisions, not to be reopened casually
5. IDENTITY.md          — who the agent is
6. SOUL.md              — learned style and operating principles
7. USER.md              — who the agent serves
8. memory/YYYY-MM-DD.md — today + yesterday
9. MEMORY.md            — long-term knowledge, main session only

Post-boot status line:

text

🏰 Boot: ACTIVE=[task|none] | HOLD=[n] | DECISIONS=[n last 48h]

Not a boot step#

• Domain files, load on demand with memory_search
• Archive, only when needed
• Other agents' memory, never by default

---

2. Dory-proof pattern — when a task arrives#

When the user gives you a task:

1. Immediately write their exact words to state/ACTIVE.md
2. Then interpret the request
3. Then do the work
4. When done, update or clear ACTIVE

state/ACTIVE.md format#

markdown

## Active task
**User said:** "[exact quote]"
**Interpretation:** [what you believe it means]
**Status:**
- [ ] Step 1
- [ ] Step 2
**Updated:** YYYY-MM-DD HH:MM

state/HOLD.md format#

markdown

[YYYY-MM-DD HH:MM | session] Item — reason for blocking

state/DECISIONS.md format#

markdown

[YYYY-MM-DD HH:MM | session] Decision — context / rationale

state/CLOSED.md format#

markdown

[YYYY-MM-DD | decider] Topic keyword — short final decision

Use CLOSED.md for issues that were definitively settled and should not keep resurfacing as open questions.

---

3. Write Before Lose — compaction-aware saving#

Session RAM can disappear. Save important things before that happens.

EventWhere to writeDecision madestate/DECISIONS.md + daily logPreference discoveredMEMORY.md or daily logTask receivedstate/ACTIVE.mdSomething blockedstate/HOLD.mdError + lessondaily log + .learnings/Important fact discovereddaily log, later promote if durableWork completedstate/ACTIVE.md + daily log

Rule: if it matters, write it immediately.

---

4. Memory scoring — what belongs in MEMORY.md?#

Score each candidate on 4 axes from 0 to 3.

Axis0123DurabilityGone tomorrowWeeksMonthsYears+ReuseOne-timeOccasionalFrequentEvery sessionImpactTrivialHelpfulChanges outputChanges decisionsUniquenessObviousMildly usefulHard to re-deriveIrreplaceable

Put it in MEMORY.md if:

• total score ≥ 8, or
• any axis = 3 and total score ≥ 6

Everything else belongs in the daily log or a domain file.

---

5. Domain organization — keep MEMORY.md ≤10KB#

text

memory/
├── domains/
│   ├── projects.md
│   ├── infrastructure.md
│   ├── people.md
│   ├── skills-tools.md
│   ├── lessons.md
│   └── policies.md
├── .learnings/
├── archive/
└── YYYY-MM-DD.md

Rules#

• MEMORY.md stores summaries, references, and the most important durable knowledge
• memory/domains/*.md stores detailed topic-specific material
• memory/archive/ stores old logs
• memory/.learnings/ stores structured mistakes, corrections, and requests

---

6. Memory types and priority#

PrefixTypeDECDecisionPREFPreferenceFACTDurable factPOLICYRuleLESSONLesson learnedERRKnown error

Use priority 1 to 10. Reserve 9 to 10 for truly critical items.

---

7. Promote / Demote — memory lifecycle#

Promote when#

• the memory becomes relevant again
• the user references it
• it supports an important decision

Demote when#

• it has not been used in 30+ days
• it is outdated
• a newer memory contradicts it

Contradiction handling#

1. Prefer the newer memory
2. Mark the older one [STALE]
3. Record why it changed in the daily log

---

8. Search strategy#

Always use:

1. memory_search
2. memory_get

Search order:

1. state/
2. MEMORY.md
3. memory/domains/*.md
4. memory/YYYY-MM-DD.md
5. memory/archive/

Do not read entire memory trees "just in case."

---

9. Multi-agent rules#

RuleDetailsOwn workspaceEach agent writes in its own workspaceNo cross-readDo not read another agent's memory by defaultCommunicationUse direct agent messaging, not memory filesShared stateOnly explicitly shared foldersPrivate contextKeep private conversations private

---

10. Anti-patterns#

Don'tDo instead"I'll remember this mentally"Write it to a file immediatelyPaste chat logs into MEMORY.mdUse daily log + summaryLet MEMORY.md bloatSplit into domain filesAnswer past-context questions from memory aloneSearch firstKeep many tasks in ACTIVE.mdOne active task, rest in project filesParaphrase the user's taskKeep the exact quoteStore secret valuesRecord only that they exist

---

11. .learnings/ — mistakes, corrections, and growth#

Recommended files:

• memory/.learnings/LEARNINGS.md
• memory/.learnings/ERRORS.md
• memory/.learnings/FEATURE_REQUESTS.md

Triggers#

• User correction → LEARNINGS.md / correction
• Outdated knowledge → LEARNINGS.md / knowledge_gap
• Better method discovered → LEARNINGS.md / best_practice
• Command or tool failure → ERRORS.md
• Missing capability requested → FEATURE_REQUESTS.md

ID format#

text

TYPE-YYYYMMDD-XXX

Promotion logic#

• behavioral pattern → persona / operating docs
• workflow improvement → operational manual
• tool gotcha → tool docs
• broadly reusable lesson → new skill

---

12. Documentation-first workflow — mandatory project continuity#

Memory is not enough. The work itself must also exist in files.

Core principle#

If it's not written down, it doesn't exist.

What to document, and where#

WhatWhereIncoming taskstate/ACTIVE.md, exact user wordsDecisionstate/DECISIONS.md + daily logBlockerstate/HOLD.mdPermanently closed decisionstate/CLOSED.mdReorientation snapshotstate/ORIENT.mdResearch notesnotes.mdProject progresstask_plan.mdFinal outputa dedicated deliverable fileGeneral lesson.learnings/ or a domain file

Project detection#

Treat work as a project immediately if any of these are true:

• it has 3 or more steps
• it has a name, slug, or concrete deliverable
• it may span multiple sessions
• it includes research, building, and review

Required 3-file pattern#

For any non-trivial task, create:

text

projects/<project-slug>/
├── task_plan.md
├── notes.md
└── deliverable.md   or another suitable output file

Minimum task_plan.md#

markdown

# Task Plan: [name]

## Goal
[one-sentence end state]

## Phases
- [ ] Phase 1: setup
- [ ] Phase 2: discovery / research
- [ ] Phase 3: execution
- [ ] Phase 4: review / deliver

## Decisions Made
- [decision]: [why]

## Errors Encountered
- [error]: [resolution]

## Status
**Currently in Phase X** - [current focus]

Role of notes.md#

Use it for sources, raw findings, analysis, and anything too large for the live context window.

Documentation rules#

1. Plan first
2. Read the plan before major decisions
3. Update the plan after each phase
4. Store large content in files, not in chat context
5. Log errors as they happen

Cron and automation prompts#

If you write a cron or automation prompt, include a dedicated section like this:

markdown

### Documentation (MANDATORY)
- Append a short run summary to: [exact file path]
- Format: YYYY-MM-DD | type | slug | summary
- This must be the last step before finishing

Why this belongs in Memory Fortress#

Because project files are memory too. task_plan.md, notes.md, and state/ORIENT.md together form the operational memory of ongoing work.

---

13. Failsafe / reorientation layer#

When an agent suddenly loses the thread, starts following the wrong branch of work, or needs to recover the real task from a long conversation, it should create a focused reorientation summary before doing more execution.

Proven recovery prompt pattern#

text

Read back the full thread content and summarize what we have done so far, where the task is documented, and what the next step is. Do not go further, only produce this detailed summary.

When to activate it#

• the agent is unsure where the work actually stands
• too many side-tracks were followed
• after handoff or a long pause
• when thread state and file state must be reconciled
• before the context window becomes too noisy

Reorientation protocol#

1. Read back the relevant thread or documented context
2. Check state/HOLD.md, state/ACTIVE.md, state/DECISIONS.md, state/CLOSED.md
3. Open the canonical task_plan.md and notes.md
4. Produce a short factual summary
5. Write the compressed version to state/ORIENT.md
6. Only then resume execution

Recommended state/ORIENT.md format#

markdown

## Reorientation snapshot
**Thread / Context:** [which thread or task this is]
**What we did so far:**
- ...
- ...

**Where it is documented:**
- `state/ACTIVE.md`
- `projects/<slug>/task_plan.md`
- `projects/<slug>/notes.md`

**Actual next step:**
- ...

**Do not do instead:**
- ...
- ...

**Closure criteria:**
- ...
- ...

**Last updated:** YYYY-MM-DD HH:MM

Important rules#

• a failsafe summary is not execution, it is reorientation
• do not jump into a new project or side-track first
• identify the real next step before acting
• send it to chat only for handoff, decision points, or explicit user request
• the canonical version should live in files, not only in chat

Why not periodic Discord summaries?#

Because they create noise, duplicate the file-based source of truth, and consume context themselves. The correct model is: file-first summary, chat-only when useful.

When to make this a separate mini-skill#

If the recurring task is thread readback + summary + documented next-step recovery, use a dedicated context-rescue mini-skill.

---

14. Maintenance schedule#

FrequencyTaskEvery sessionrun boot sequenceEvery taskupdate ACTIVEImportant eventwrite immediatelyDailyreview daily log and clean stateWeeklysize-check MEMORY.md and update domainsBiweeklyarchive old logsMonthlydemote stale memories and resolve contradictionsOn errorwrite to .learnings/ERRORS.mdOn correctionwrite to .learnings/LEARNINGS.md

---

15. Installation#

1. Create state files#

bash

mkdir -p state
touch state/ACTIVE.md state/HOLD.md state/DECISIONS.md state/CLOSED.md

2. Create ORIENT file#

bash

touch state/ORIENT.md

3. Create memory structure#

bash

mkdir -p memory/domains memory/archive memory/.learnings

4. Create projects convention#

bash

mkdir -p projects

5. Update your agent manual#

Add the boot sequence, the write-before-lose rule, the documentation-first project pattern, and the failsafe ORIENT.md reorientation layer.

---

"Memory is what separates a tool from an ally."