~/app How it works
A semantic tree, versioned with git — that's the whole trick.
Memory has a lifecycle: formation, evolution, retrieval. Memoir gives each one a primitive — classify on write, branch and merge to evolve, walk paths to recall. No embedding model. No vector index. No black box.
- 01
Classify
Incoming facts are routed via hierarchical text classification — pattern match in 1–5ms, LLM fallback for ambiguous cases. The taxonomy is not static: as new memories arrive, an LLM can rename, rearrange, merge, or generate nodes to keep the hierarchy aligned with how the model actually reasons. Recent work shows LLM-refined taxonomies outperform hand-curated ones by up to +2.9 F1 points.
preferences.coding.testing - 02
Store
Each change is captured as a commit. One commit may bundle a single write or a whole branch merge. SHA-256 hashes make the history tamper-evident, and structural sharing keeps storage flat.
commit 7f3a2b1 — 42 bytes - 03
Recall
Query by exact path for <10ms direct hits, or use tiered semantic drill-down that walks the taxonomy top-down. Every result carries its source path — retrieval is never a mystery.
recall "testing setup" → preferences.coding.testing - 04
Branch & rewind
Create branches to test hypotheticals without touching main. Merge what works. Checkout any past commit to reproduce agent state exactly as it was when a bug surfaced.
memoir checkout HEAD~5
See it in action
Three branches. One memory store. Zero contamination.
Three coding agents working in parallel on the same repo, each in a different worktree. As they hit decisions, Memoir commits to their branch — not yours. Watch the tree grow without poisoning anyone's context.
~/app/worktree/auth ~/app/worktree/mig
memoir.store
- branches
- 1
- paths
- 2
- commits
- 2
- main
-
api.v2.errors.retrytreat 429 as retryable; backoff 250ms -
workflow.testingvitest with @testing-library/react; jsdom env
-
Built on the research
Two papers. One memory architecture.
Memoir is not just a clever CLI — it is a production answer to two active research lines in agent memory.
Forms, functions, and dynamics.
A recent survey organizes agent memory along three axes — forms (token, parametric, latent), functions (factual, experiential, working), and dynamics (formation, evolution, retrieval). Memoir occupies the structured-construction corner that vector-DB-based systems cannot reach: factual and experiential memory with explicit formation and evolution operators.
"Memory in the Age of AI Agents: A Survey" · arXiv:2512.13564The taxonomy itself can learn.
LLMs can reshape a taxonomy — renaming, rearranging, merging, generating nodes — to align it with how the model itself reasons, beating human-curated hierarchies by up to +2.9 F1 points. This is the technique under memoir's classifier: your taxonomy does not ossify, it learns alongside the agent.
"Hierarchical Text Classification with LLM-Refined Taxonomies" · arXiv:2601.18375