Tier 3 project memory: the file-based second brain

Project memory is what makes the agent useful at hour zero of a new session. The agent wakes up, reads its files, and knows the project: where the data lives, what the conventions are, what was decided, what must not be done.

Most agents get this wrong by either remembering nothing (the agent asks the same question every run) or remembering everything in one giant blob (the agent picks the wrong thing from a 10,000-line file).

The fix is a small set of files with sharp rules. Both LlamaIndex and LangChain explicitly recommend starting with simple in-memory or file backends for small projects and only graduating to vector stores when the corpus or query shape demands it.

Where this comes from: Marvin’s 2026-07-20 original. Sources verified 2026-07-22 against LlamaIndex and LangChain storage / memory docs.

The four files

project/
  MEMORY.md        # durable facts
  USER.md          # operator prefs
  DECISIONS.md     # timestamped decision log
  RUNBOOK.md       # how to do the recurring things

That is it. Resist the urge to add a fifth file.

MEMORY.md — durable facts

A flat list of facts the agent must know on every run.

# Project memory — <your project name>
- Three active stores: store-A (primary), store-B, store-C.
- Image generation: provider-X for masters; provider-Y for previews only.
- Master-size pipeline: W×H source → upscale → final. Provider-Y caps at W2×H2.
- Canonical storage: object-store bucket `<bucket-name>`, prefix `<path>/`.
- Approval gates: spend > $X requires messenger approval; posting requires approval; cron edits require approval; vendor support tickets require approval.
- Closed stores / deprecated tools: list them. Do not auto-generate for closed stores.
- Hard memory budget: 99% of N chars. Trim before adding.

The rule: a fact goes here if a future agent will need it on a cold start, and it has not changed in 30 days. If it changes weekly, it does not belong here.

USER.md — the operator

# Operator profile — <operator name>
- Prefers concise, operator-grade output. Bullet points + tables when structured.
- Frustrated by guesswork; values durable continuity. Long-term storage required, not local-only.
- Time zone: <tz>.
- Local LLM stack: <hardware>, <model>; local tokens free, time matters.
- Workflow: <agent-A> for X, <agent-B> for Y.
- Wants honest blockers > theatric wired-up claims.
- Never re-auth / regen / re-explain covered material.

The rule: a fact goes here if the operator would say “yes, of course” if asked. If it is a one-time preference, it does not belong here.

DECISIONS.md — the log

# Decisions log

## 2026-07-18 — <project> pilot
Decision: Pilot <choice> first. No <alternative> until <signal>.
Why: Avoid building infra before first dollar.
Reversible if: First listing goes 4 weeks with no sales.

## 2026-07-12 — Close <store-X>
Decision: Drop <store-X> from active generation list.
Why: <reason>.
Reversible if: never.

## 2026-06-17 — Close <store-Y>
Decision: Drop <store-Y>.
Why: Same.

The rule: every non-trivial decision gets one entry, dated, with the “why” and the “reversible if.” When the agent is about to do something that contradicts a past decision, this file is what it checks.

RUNBOOK.md — how to do the things

# Runbook

## Daily 04:30 — Social QA
Run `<script-path>`. Silent on pass, alert on failure.
Script logic: only FAIL lines trigger messenger; WARN lines are informational.

## Weekly Mon 06:00 — Sales report
Run `<script-path>`. Posts summary to operator messenger.

## On new art batch
1. Verify storage upload: `<bucket-prefix>/<batch-id>`
2. Update ingest manifest.
3. Sift for winners (vision check).
4. Do NOT auto-publish.

The rule: a procedure goes here if it is run more than once and the steps are non-obvious. If it is a one-shot, it does not belong here.

What does NOT belong in project memory

• Recent activity. “Yesterday we shipped X” — belongs in a changelog or a daily summary, not in project memory.
• Tool output. Belongs in Tier 2.
• Operator’s mood today. Belongs in Tier 4, optionally, if at all.
• Speculative plans. “We might add a Slack bot next quarter” — belongs in a roadmap doc, not memory.

When to graduate to a vector DB

Files win for most projects. You will know it is time to add a vector DB when all three of these are true (the consensus from LlamaIndex’s storage docs and HN builder reports):

1. You have > 50 long-form documents you want the agent to search across (PRs, Notion pages, transcripts).
2. The relevant document is rarely the entire document — you want “the two paragraphs that mention X.”
3. You are willing to maintain embeddings, freshness, and a second storage layer.

If you do not have all three, stay with files. Files are auditable, diff-able, deletable, and you can read them in cat. The cost of a vector DB is not the storage — it is the loss of inspectability.

If you cannot list the contents of your agent’s memory in one screen, you cannot debug it.

The injection pattern

Project memory is read at the start of every run, not on every prompt.

session start
  → read MEMORY.md (full)
  → read USER.md (full)
  → read DECISIONS.md (full)
  → read RUNBOOK.md (full)
  → inject into context with stable prefix
  → proceed

If MEMORY.md exceeds your model’s context budget for the stable prefix, split it: MEMORY.md (essentials) + MEMORY-EXTENDED.md (loaded only when needed). Do not let memory grow until context collapses.

Trade-offs

Choice	What it costs	What it saves
4 fixed files vs. 1 giant blob	Strict editing discipline.	Agent picks the right fact at session start.
Files vs. vector DB	Manual grep / read.	Inspectability, auditability, deletion simplicity.
Read all 4 files at session start	~2-5 KB of context per run.	Agent knows the project from turn 1.
Split MEMORY into essentials + extended	Two files to maintain.	Stable prefix stays under context budget.

Failure modes

• MEMORY.md grows unbounded. Eventually it does not fit in the stable prefix. Fix: enforce a char budget (e.g. 99% of 2,200 chars), trim monthly.
• DECISIONS.md never gets written. Decisions live in chat history and evaporate. Fix: every non-trivial decision gets one entry, dated.
• RUNBOOK.md drifts from actual scripts. Procedures change, the file doesn’t. Fix: link the file to the script header comment (# See RUNBOOK.md § Daily 04:30).
• Operator profile (USER.md) becomes a confessional. Preferences creep in, then “the agent said something weird.” Fix: a fact belongs in USER.md only if the operator would say “yes, of course” if asked. Anything else: drop.

What you will have at the end

• Four files (MEMORY.md, USER.md, DECISIONS.md, RUNBOOK.md) with sharp rules on what belongs in each.
• An injection pattern (read all four at session start, stable prefix).
• A graduation rule for when to add a vector DB.
• A “what does NOT belong” anti-list.

Where to get unstuck

• LlamaIndex storage module for the file → vector DB graduation path: docs.
• LangChain memory concepts for the framework implementation: docs.
• OpenAI ChatGPT memory controls (a real-world reference for what “memory” looks like in a deployed product): OpenAI help.

Sources

• LlamaIndex — Storage module guide — used for: the file → vector DB graduation path, the “start with files” recommendation. Verified 2026-07-22.
• LangChain — Memory concepts — used for: the framework implementation, the file-backend defaults. Verified 2026-07-22.

Last verified: 2026-07-22. Adapted from Marvin’s original “B4. Tier 3 — Project Memory: The File-Based Second Brain” (2026-07-20). Drafter and source-notes author are the same model (MiniMax-M3). Tips category — no subagent review required per the v2.4.0 skill rule (Setup/Playbook only).

Public-safety note: the original example content referenced specific store names (NATT, SoloSwagCo, PoliticalSwagCo), vendor specifics (ChatGPT Codex, SuperGrok), and operator timezone (America/Denver). v1 of this guide replaces those with placeholder shapes (store-A, provider-X, <tz>, etc.) per the ABS Public-Safety Checklist.