Your agent doesn't respect your git state.
Context contamination happens every time you git checkout. Without branch-aware memory, your agent tries to apply experimental refactor patterns to stable production hotfixes.
Memory infrastructure for AI agents
Git for AI Memory
Memory your agents can explain, rewind, and branch.
Memoir replaces opaque vector memory with a taxonomy-structured, Git-versioned store. Recall by path, not by similarity. Time-travel to reproduce bugs. Branch to test risky strategies. Built for coding agents and custom runtimes alike.
memoir.recall( " what's my coding style? " )
Python install for the SDK or CLI.
Claude Code plugin install. Run inside a Claude Code session.
Using Codex instead? See the Codex install →
Why Memoir
Today's AI memory is a Global Variable anti-pattern.
Every production agent hits the same three walls: context contamination, token rent, and memory drift. Memoir brings version control to your agent's mind.
You’re paying "token rent" on a flat file.
Using CLAUDE.md or MEMORY.md as a global store is a cache-killer. Every minor memory update invalidates your entire prefix cache, forcing you to pay full price to re-process your entire conversation.
Memory is a codebase without version control.
One bad session poisons every future retrieval. Without memoir blame or memoir checkout, there is no way to audit who taught the agent a rule or revert a hallucination without wiping the entire store.
The solution
Git for memory.
Memoir replaces fuzzy retrieval with version-controlled, branch-aware memory. It ships as a Claude Code plugin — a set of automatic skills and hooks that follow your git workflow.
Semantic path retrieval.
Instead of "vibe search" (vector DB), Memoir uses hierarchical paths like api.v2.auth to fetch the exact 10 tokens needed — keeping your prompt cache stable.
memoir get api.v2.auth
→ "JWT, 15-min expiry, refresh on 401"Automated branch shadowing.
Memoir branches follow your git branches automatically via Claude Code hooks. No manual sync, no contamination across checkouts.
$ git checkout migrate-to-deck-gl
→ memoir · switched to migrate-to-deck-glThe merge workflow.
Lessons learned on a feature branch can be reviewed and merged into the main knowledge base — just like code.
memoir merge feature/deck-gl → main
3 paths added · 1 conflict resolved Quickstart
From zero to persistent memory in 60 seconds.
Three entry points. Pick your runtime — Memoir stores are compatible across all of them.
Memoir installs as a first-class Claude Code plugin. Auto-capture on session end, context injection on start.
# Inside a Claude Code session:
/plugin marketplace add zhangfengcdt/memoir
/plugin install memoir@memoir
# That's it. Next session starts with:
# • auto-capture of session memories
# • context injection on start
# • slash commands (/memoir-remember, /memory-recall, /memoir-ui)Codex's marketplace plugin. Same skills as Claude Code — onboard, recall, remember, status, UI — plus Codex-native transcript parsing.
# In Codex, run /plugins:
# add marketplace from zhangfengcdt/memoir
# choose Memoir Plugins → install memoir
# (Restart Codex if prompted.)
# Or register the marketplace from the CLI:
codex plugin marketplace add zhangfengcdt/memoir
# Enable hooks once in ~/.codex/config.toml:
# [features]
# hooks = true
# Or for a smoke run:
# codex --enable hooks
# Skills shipped: memoir-onboard, memory-recall,
# memoir-remember, memoir-status, memoir-ui
# CLI resolution: memoir on PATH → uvx → uv tool run
# (no manual pip install needed if uv is on PATH)Drop into LangGraph, LangChain, CrewAI, AutoGen — or any Python runtime. Async-first API.
pip install memoir-ai
# remember.py
from memoir import MemoryClient
memory = MemoryClient(store="./my_store")
await memory.remember(
"user prefers pytest with parametrize",
namespace="user-123",
)
results = await memory.recall(
"what's my testing setup?",
namespace="user-123",
)Every command returns --json. Stable exit codes. Pipe into any agent runtime that shells out.
pip install memoir-ai
memoir new ./my_store
export MEMOIR_STORE=./my_store
memoir remember "prefer pytest, parametrize aggressively"
memoir recall "testing setup" --json
memoir branch create experiment
memoir time-travel HEAD~5
memoir ui # opens the web explorer at :8080 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
Real session
Memoir, running in Claude Code
A real Claude Code session — same plugin, same store, same commands.
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 ~/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 Ship it
Give your agents memory they can trust.
Architecture grounded in 2026 agent-memory research.
Open source under Apache 2.0. Production-tested on coding agents. Free for any use. Install in under a minute.