collabmem: The File System That Teaches Claude Code to Remember
A plain-text memory stack for AI collaborators. It turns context into a versioned world model, episodic notes, and explicit memory maintenance commands.
- collabmem argues that AI memory should be legible first, with plain text, Git diffs, and explicit maintenance steps instead of hidden retrieval layers.
- Its real innovation is a two-layer memory model that separates episodic notes from a world model, so the system can stay compact without losing shared context.
- Tier 1 and Tier 2 create a cache hierarchy for cognition, keeping high-signal files always present and pushing detail into searchable storage.
- The trade-off is discipline: the approach works best when the model follows instructions reliably and the team keeps the memory files well maintained.
Why memory is the wrong word
Most AI memory tools promise recall. collabmem aims higher. It is trying to maintain a shared project state across sessions, not just recover a fragment of old conversation.
That shift matters. A retriever answers, “What did we say before?” A memory operating system answers, “What do we believe now, what changed, and where should that live?”
The two-layer memory model
The repo splits memory into two different jobs. Episodic memory tracks what happened. World model memory tracks what is true, stable, or preferred.
That separation is the project’s real discipline. It keeps history from getting confused with state, and it gives the AI a place to store facts that should survive one long conversation and still make sense in the next.
The most important idea: Tier 1 vs Tier 2
Tier 1 is the active working set. It stays in context because it is small, high-signal, and constantly relevant. Tier 2 is the archive, searched only when Tier 1 points to something worth pulling in.
That is a cache hierarchy for cognition. It is also the repo’s most opinionated move: instead of asking a vector index to guess relevance, it asks the model to follow a strict reading and updating method.
Through the use of in-context memory index files, the AI can maintain a global awareness of what's in the memory.
Sentinel tokens as a tiny command language
The user-facing control surface is deliberately small: readmem, updatemem, and maintainmem. Those tokens are not decoration. They turn memory into an explicit operation instead of an ambient guess.
That choice changes the contract. The AI is not free to rewrite the past whenever it feels like it. It has to read, propose, and maintain under named rules.
How memory stays small enough to survive
The maintenance story is what makes the architecture sustainable. Mature knowledge gets consolidated upward into the world model. Overstuffed files get compacted. Old material is preserved in notes or archives instead of disappearing.
That means the system can grow without letting the active context collapse under its own weight. The goal is not maximum retention. The goal is useful retention.
| Mechanism | What it does | Why it matters |
|---|---|---|
| Consolidation | Moves durable knowledge into the world model | Keeps important context visible without rereading everything |
| Compaction | Shrinks oversized active files | Prevents Tier 1 from becoming junk drawer memory |
| Archiving | Preserves removed detail in notes or index archives | Retains history without bloating the working set |
Why Git matters here
Git is not just storage in this design. It is the audit trail, the merge strategy, and the explanation layer for how memory evolved over time.
That is why the project feels collaborative instead of personal. A shared repo can hold a shared world model, and the diff shows who changed what the AI believes.
| Layer | collabmem | Vector-first memory | Platform memory |
|---|---|---|---|
| Storage | Plain text files in Git | Embeddings and indexed chunks | Backend-managed memory store |
| Retrieval | Read, search, then update | Semantic nearest-neighbor search | Platform-specific retrieval |
| Transparency | Fully inspectable | Opaque similarity scores | Limited visibility |
| Collaboration | Team-readable world model | Usually session-centric | Tied to one ecosystem |
The memory is file-based and represented as plain text (easy to inspect), can be git-tracked (storage & versioning) and can be used to build up knowledge within a team of users. So no databases, no vector stores, no infrastructure. Just files and a methodology that the AI follows.
What it trades off
This approach is elegant, but it is not forgiving. The repo’s own framing makes the dependency clear: it works best when the model can reliably follow the methodology and maintain the files with discipline.
That is the central risk. The system is transparent because it asks for structure. If the structure slips, the memory slips with it.
| Strength | Weakness | Implication |
|---|---|---|
| Legible files | Less automatic than vector search | Humans can inspect and repair the system |
| Explicit commands | Requires disciplined usage | The agent must follow instructions closely |
| Git history | More overhead than hidden storage | You get provenance and collaboration for free |
The project creator puts it plainly in the README:
Status: v1.8 — we are actively testing and developing this. The episodic memory (notes, index) is the more mature component; the world model memory is functional but earlier in its development.
Where it sits in the landscape
Compared with vector-first memory systems, collabmem is slower in the search-engine sense and stronger in the systems-design sense. It optimizes for clarity, editability, and shared authorship.
That makes it a good fit for AI collaborators that live inside a real codebase. It is less about magical recall and more about making the model’s world state something a team can inspect, change, and trust.
