Skip to content
Flows
Library Paths Vault Generate Progress Run Demo Flow
Memory & Context Beginner · 45-75 minutes

Add File-Based Persistent Memory

Give your agent durable memory with plain files - the radical-minimalism approach production practitioners keep converging on.

Start Route · 4 steps

The route

4 steps to Done

  1. 01

    Design the memory file structure

    Structure is what keeps file memory useful at write 50.

    Preview prompt + verify gate ▾

    Design the project memory format. Create MEMORY.md with sections: ## Project Facts (architecture, key paths, stack choices), ## Preferences (user style and tool preferences, one per line), ## Working Recipes (commands and approaches that work, with context), ## Known Issues & Failed Approaches (what breaks and why), ## Decisions Log (dated one-liners: decision + reason). Define per-section caps (e.g. 30 lines each) and entry format rules (imperative one-liners, no paragraphs, date-stamped where useful). Write the format spec at the top of the file as an HTML comment so both humans and the agent see the rules.

    • ✓ Five sections with clear purposes
    • ✓ Caps and entry format defined
    • ✓ Rules embedded in the file itself
  2. 02

    Load memory at session start

    Reading is the easy half - do it first and prove it matters.

    Preview prompt + verify gate ▾

    Implement memory loading. At session start in a project: read MEMORY.md if present; include it in the system context under a clear 'PROJECT MEMORY - honor these facts and preferences' header; if the file exceeds the context budget allotted (default ~1000 tokens), include Preferences and Known Issues fully and summarize the rest. Handle the no-file case silently. Prove it works: hand-write a preference into the file ('all API routes use the /api prefix') and a known issue ('do not use library X, it conflicts with Y'), start a session, and give the agent a task where both should influence behavior - verify they do.

    • ✓ File loaded under a clear header
    • ✓ Over-budget handling prioritizes preferences and issues
    • ✓ Hand-written entries respected in the test
  3. 03

    Build the guarded memory_update tool

    One write path, validated, logged, duplicate-checked.

    Preview prompt + verify gate ▾

    Implement the memory_update tool. Interface: memory_update(section, action, entry, replaces?) where action is add | revise | remove. Validation: section must exist; entry must fit the format rules (single line, length cap); on add, check for near-duplicates in the section (normalized comparison) and reject with the existing entry shown; on revise/remove, 'replaces' must match an existing entry. The tool rewrites the file atomically and appends an audit line to memory-log.jsonl (timestamp, action, section, entry). Update the system prompt: record durable facts, preferences, decisions, and failures when discovered - and always prefer revising an outdated entry over adding a contradicting one.

    • ✓ All three actions validated
    • ✓ Near-duplicate adds rejected helpfully
    • ✓ Audit log captures every write
  4. 04

    Add consolidation and run the 20-write test

    Memory hygiene is scheduled work, not a hope.

    Preview prompt + verify gate ▾

    Implement consolidation and prove durability. Consolidation: when a section exceeds its cap, run a consolidation prompt over that section (merge overlapping entries, drop superseded ones, keep the newest phrasing, never drop unique facts) and rewrite it within cap - triggered automatically at session end when needed. The 20-write test: script a series of sessions performing 20+ memory updates including deliberate near-duplicates, a superseded decision, and a revised preference; verify at the end that the file is within caps, readable, deduplicated, the superseded decision shows only its latest form, and a fresh session correctly answers questions from early writes.

    • ✓ Cap-triggered consolidation works
    • ✓ Superseded entries show latest form only
    • ✓ Early facts still answered correctly at the end

Research-backed

Sources behind this flow

Tier 3 · memory

AI Memory Patterns

Production patterns for building AI agent memory systems, distilled from operating a real multi-tenant system (154K+ observations, 3-node cluster) that competes with commercial offerings like Mem0 and Zep - architectural patterns and lessons, not a tutorial.

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.