Skip to content

v0.3.0 — Memory v2: guardrails against bloat and drift

Latest

Choose a tag to compare

@jigripokri jigripokri released this 26 Oct 04:09
d830ae0

Memory v2: memory that stays small, stays current, and remembers the past

v0.3.0 rebuilds POHA's memory layer. It's still plain markdown with no database, vector store or RAG. What's new is that the rules that keep it healthy are now enforced by a script instead of hoped for in a prompt.

Why

After about six months of daily briefings on a busy, real life, the v0.1 memory rule ("read everything, update at the end, prune weekly") drifted in four predictable ways:

  1. One file played two roles. Every scheduled run appended a "here's what I did" note to commitments.md. The worklist became mostly log, every briefing paid to read it, and runs started running out of room. The first step to get dropped was the optional "write an insight" step, so insights quietly stopped.
  2. Insights had no lifecycle. The same stuck situation produced dozens of near-identical "insights", IDs got reused, and new entries landed at the bottom where nobody read them.
  3. Pruning depended on memory. The 3-week rule was flagged week after week and never done.
  4. Files rotted silently. "Current quarter" sections named quarters long gone. Nothing said which file was stale or whose job it was.

None of these is a model problem. Each one is a missing mechanism. The fix is boring on purpose: budgets that are numbers, checked by a script, not adjectives in a prompt.

What changed

Two kinds of files that never mix

  • Curated state (commitments, insights, people, life, finances, health): small, rewritten in place. Each has a byte budget, an owner and a max age, plus a Last updated header.
  • Append-only history: a monthly event journal (memory/journal/YYYY-MM.md) for lookbacks, per-run notes in logs/run-notes/, and monthly or quarterly archives. Nothing is ever deleted. Things leave curated files only by being archived first.

tools/memory_maint.py (Python 3.9+, stdlib only, nothing to install) runs at the close of every briefing: check → rotate → journal-diff → index.

  • check: budgets, freshness, table and insight schemas, forbidden patterns (run notes, day counters, "STATUS" lines in curated files), missed scheduled runs.
  • rotate: flips 21-day-old items to CHRONIC, archives closed items after 7 days, and archives retired insights with their full text.
  • journal-diff: logs any change a run forgot to record, so the history stays complete.
  • index: writes memory/INDEX.md, which every briefing reads first. It shows what's stale, what's over budget, how old each commitment is, and what each briefing should read.
  • Plus lookback, novelty, section, next-id, journal and run-note.

Worklist and insights

  • commitments.md is now a 9-column table with permanent C-NNNN IDs, ≤3 pinned projects, and a 7-day Closed section.
  • The 3-week rule now runs itself. Items open 21+ days become CHRONIC, get one compact line in briefings, and get one Keep / Accept / Reframe question in the weekly review.
  • insights.md holds ≤25 active lenses (≤3 per subject) with permanent I-NNNN IDs and evidence counts. A deterministic novelty gate blocks near-duplicates; a repeat bumps the evidence count instead.
  • The evening reflection makes an insight decision every night: new, evidence, or none — <reason>.

Briefings and docs

  • New briefings/_memory-contract.md holds the read and write rules once. All eight briefings reference it.
  • tools/memory_contract.json holds every budget, owner, max age, tag, the timezone, the schedule and the read plans in one editable file.
  • Rewritten: CLAUDE.md, ARCHITECTURE.md, README.md, SETUP.md, and docs/memory-system.md, which now has the full rationale, lookback recipes and an upgrade guide.
  • 16 tests, including one that runs the shipped templates through a first maintenance pass and expects a clean result.

Upgrading from v0.2

  1. Pull, then set "adopted" and "timezone" in tools/memory_contract.json.
  2. Move run logs out of commitments.md, convert rows to the new table, and restructure insights into lenses.
  3. Run python3 tools/memory_maint.py all --job manual and fix what it reports.

Step-by-step guide: docs/memory-system.md → Upgrading from v0.2.

New requirement: Python 3.9+. memory/ and logs/ remain gitignored, so no personal data ships.

Full details: CHANGELOG · PR #4