Skip to content
Flows
Library Paths Vault Generate Progress Run Demo Flow
Memory & Context Intermediate · 60-90 minutes

Design a Memory Index Loaded Every Session

Build the pattern behind minimalist memory systems: a compact index file the agent always loads, pointing to detail files it loads on demand.

Start Route · 3 steps

The route

3 steps to Done

  1. 01

    Structure the index and details

    The index is a map; the details are the territory.

    Preview prompt + verify gate ▾

    Design the two-layer memory structure. INDEX (memory/INDEX.md, hard cap ~400 tokens): a header stating its role, then one line per topic: `- topic-name: one-line description of what the detail file contains and when to load it -> memory/topics/topic-name.md`. DETAIL FILES (memory/topics/*.md): focused documents per topic (auth-system.md, deployment.md, user-preferences.md...), each starting with a 2-line abstract matching its index description. Migrate my existing memory content into this structure now, writing index descriptions that state WHEN to load ('load when working on login, sessions, or permissions'). Deliver the populated index and at least three real detail files.

    • ✓ Index within its token cap
    • ✓ Every description says when to load
    • ✓ All detail files reachable from the index
  2. 02

    Wire loading: index always, details on demand

    Constant context cost with reach into everything.

    Preview prompt + verify gate ▾

    Implement the loading mechanics. At session start: load INDEX.md into the system context under a header explaining 'this is your memory index - load topic files with memory_read when a task touches them'. Implement memory_read(topic) returning the detail file content (with a token cap and truncation note for oversized files). Add index-integrity checks at load: warn on pointers to missing files and on files not in the index. Prove the flow: give a task about authentication and verify the agent loads auth-system.md before acting; give an unrelated task and verify no detail loads happen.

    • ✓ Index loaded with usage instructions
    • ✓ Relevant task triggers the right memory_read
    • ✓ Irrelevant task loads nothing
  3. 03

    Maintain the index as memory evolves

    An index that drifts from reality is worse than no index.

    Preview prompt + verify gate ▾

    Implement index maintenance. Extend the memory tool so that: creating a new detail file requires an index entry in the same operation (atomic pair); updating a detail file's scope prompts a description refresh; removing a topic removes both file and pointer. Add a session-end sweep: verify index-file bijection (every pointer resolves, every file is pointed at), flag descriptions whose detail files changed substantially since the description was written, and keep the index under cap by merging the two least-recently-loaded topics when over (tracked via a small access log). Run a multi-session simulation adding four topics and retiring one, then verify the index matches the directory exactly.

    • ✓ File+pointer operations are atomic
    • ✓ Session-end sweep catches drift
    • ✓ Over-cap merge uses access recency

Research-backed

Sources behind this flow

Tier 3 · memory

Octopus_mem

An agent memory system built on a skill + memory index architecture following a radical-minimalism principle ('jsonl, md, at most sqlite'), with a dual-repo split: open framework, private data.

Tier 3 · memory

KAS Memory

An agent memory system that auto-extracts insights from coding sessions, recalls relevant memories in future conversations, and builds a growing reusable knowledge base - aimed squarely at not repeating the same mistakes across sessions.