agentmemory-rrs 4.0.2

Persistent memory for AI coding agents. Correct once, remembered forever. Every design decision validated by experiment before shipping to production.

agentmemory

Correct your AI agent once. It remembers forever.

---

You correct your AI agent. It says "got it." Next session, it makes the same mistake. You correct it again. And again. And again.

agentmemory makes the next correction your last. It captures what matters from your conversations (corrections, decisions, preferences), stores them locally, and injects them into every future session. Silently. Automatically. You stop repeating yourself.

pip install agentmemory-rrs
agentmemory setup

Restart Claude Code. In any project: /mem:onboard .

That's it. Three commands. Your agent now remembers permanently.

---

What It Actually Does

Here's a real example. You type push the release to github. Before the agent sees your message, agentmemory's hook fires and runs a multi-layer search in ~50ms:

Layer 0: Structural analysis    -> task type: deployment, target: github
Layer 1: FTS5 full-text search  -> 4 hits (publish script, CI checks, remote config)
Layer 2: Entity expansion       -> "github" links to 3 beliefs about repo setup
Layer 3: Action-context         -> "push to github" triggers activation condition
Layer 4: Supersession check     -> old remote URL excluded (superseded)
Layer 5: Recent observations    -> correction from 2 days ago about publish script
Layer 6: Cross-project scopes   -> checks shared infra beliefs

The agent receives this context injection alongside your message:

== OPERATIONAL STATE ==
[!] GitHub account renamed (changed 2d ago)

== STANDING CONSTRAINTS ==
- NEVER use git push github directly. Use scripts/publish-to-github.sh
- Pre-push hook scans for PII; direct push bypasses safety checks
- To release with tag: bash scripts/publish-to-github.sh --tag vX.Y.Z

== BACKGROUND ==
- Remote 'github' points to [e-mail]:robotrocketscience/agentmemory.git

Without agentmemory, the agent takes "push to github" literally and runs git push github main, bypassing every safety check. With it, the agent heard three words and executed the full procedure: publish script, PII guards, pre-push hook. That procedure was never taught in one session. It accumulated from corrections over weeks. Why this matters: from low-context to high-context.

---

You Need This If

Your problem	What keeps happening	How agentmemory fixes it
Complex deploy workflows	You built a 29KB runbook with dispatch gates and safety checks. The agent skips the runbook and runs raw commands. You re-explain the procedure ~3 times a day. A manual CLAUDE.md reference reduced failures by 67% but plateaued.	The runbook becomes locked beliefs injected every session. The agent can't skip what's already in its prompt. Zero re-explanations after the first correction.
Long stateful projects	Context drift across sessions kills multi-step work. The agent forgets which approach was abandoned, re-suggests dead ends, or loses track of where you are in a 10-phase roadmap. You spend more time re-orienting the agent than doing work.	Decisions, corrections, and project state persist across sessions. The agent starts every session knowing what was tried, what failed, and what's current.
Multi-repo or multi-project work	Knowledge learned in one project doesn't transfer. You explain your infrastructure setup separately in every repo. The same mistakes happen in each project because each context window starts fresh.	Cross-project shared scopes (v3). Beliefs about your deploy pipeline, team conventions, or infrastructure flow between projects without duplication.
The "I already told you" loop	You correct the agent. It acknowledges. Next session, same mistake. You correct again. After the fifth time you write it in a config file. The agent reads the config file and still doesn't follow it.	Corrections are stored with 92% detection accuracy (zero LLM cost), tracked with Bayesian confidence, and mechanically injected. The agent doesn't choose to read them. They're part of the prompt.

---

What It Remembers

You say	It stores
"Never commit .env files"	Permanent rule. Injected every session.
"The endpoint moved to /v2"	Correction. Replaces the old belief.
"I prefer terse commits"	Preference. Shapes behavior silently.

Beliefs accumulate over time. Each one carries a Bayesian confidence score that strengthens when the belief proves useful and fades when it doesn't. After a few weeks:

/mem:stats
Beliefs: 312 (18 locked, 294 learned)
Sessions: 47
Corrections surfaced this session: 3
Last locked: "never force-push to main" (4 weeks ago)

---

The Problem Is Bigger Than You Think

Most power users end up building the same workaround: a growing collection of markdown files. STATE.md for current position. ROADMAP.md for what's next. DECISIONS.md for why you stopped doing it that way. Cross-references in your config file pointing to runbooks, registries, and troubleshooting guides. Some projects have 7+ mandatory external reads the agent is supposed to follow.

Every prompt is a bet. You write "see docs/deploy-runbook.md for deployment steps" and hope the agent actually reads it, finds the right section, and follows it. When it doesn't (and it often doesn't), you get silent failures: re-suggested dead approaches, guessed credentials, skipped safety checks.

agentmemory makes every prompt a contract. Relevant context is found through a multi-layer search and injected as part of your prompt before the agent sees it. The agent doesn't choose to read it -- it's already there. No cross-references to follow, no files to remember to check. The knowledge is selected by relevance and delivered mechanically, every time.

Manual approach	What breaks	agentmemory
Rules in config files	Agent reads them, doesn't follow them	Injected per-prompt, not per-session
Cross-references to docs	Agent skips the reference or reads the wrong section	Relevant content extracted and injected directly
State files updated by hand	One missed update and the chain is broken	State tracked automatically with 100% accuracy
Workaround frameworks	Add structure but still rely on the agent to voluntarily read files in the right order	No voluntary reads. Mechanical injection.

---

Your Data Stays Yours

• 100% local. SQLite on your machine. No network calls in the retrieval pipeline.
• No cloud, no accounts. No server, no signup, no telemetry by default.
• No GPU or vector database. Runs on any machine that runs Python.

---

What Happens After Install

agentmemory works in the background:

1. It listens. Picks up decisions, corrections, and preferences from your conversations.
2. It retrieves. Injects relevant beliefs before the agent responds to each prompt.
3. It learns. Beliefs that help get stronger; beliefs that don't, fade.

To explicitly lock a permanent rule:

/mem:lock "never commit .env files"

For deeper exploration:

Command	What it does
/mem:search <query>	Find specific memories
/mem:lock <rule>	Create a permanent rule
/mem:wonder <topic>	Deep parallel research across the memory graph
/mem:reason <question>	Test a hypothesis against stored evidence
/mem:stats	See what's in memory

Full command reference: docs/COMMANDS.md.

---

Emergent Behavior

These weren't planned features. They emerged from persistent memory + reasoning tools.

The agent audited its own memory and found a bug

user    Clean up the config file, I think agentmemory handles this now.

agent   [searches memory, compares against config]
        Found 2 redundant items. But also: this locked belief about
        your server setup is stale. It references infrastructure
        you removed. Every session is getting incorrect instructions.

user    Fix it.

agent   [corrects the belief, supersedes the old one]
        Done. Want to lock the updated version?

The system caught its own error because it had enough accumulated context to notice the inconsistency. More examples and a full session transcript showing wonder + reason in action.

---

It Gets Smarter Over Time

Early sessions are sparse. The system knows little, retrieves little, stays quiet. But the graph densifies as you work. v4 made this tangible:

"Didn't we already decide this?" Beliefs now link chronologically within sessions. When the agent retrieves a decision, it also knows what led up to it and what came after. No more re-suggesting an approach you abandoned three sessions ago because the graph carries the full arc.

"I said I'd fix that eventually." Say "we need to add progress bars to onboarding" and it becomes a TODO belief. Next time you're working on onboarding, it surfaces automatically. TODOs fade if never acted on -- no stale task lists.

"Wait, those two contradict each other." When the system retrieves beliefs that disagree, it flags them before the agent responds. You see "CONTRADICTIONS (resolve before proceeding)" instead of the agent silently picking one.

"I have no context on that." When the system finds nothing relevant, it says so. The agent sees "No beliefs found for this topic" instead of silently proceeding without memory -- which is how hallucination starts.

---

Under the Hood

Conversations are broken into individual beliefs stored in a local SQLite database. Retrieval uses full-text search, graph traversal with Thompson Sampling (explore/exploit), and vocabulary bridging. Beliefs are linked chronologically within sessions and cross-linked by multi-metric semantic similarity. Nothing to install, nothing to host, nothing that phones home.

294 experiments drove every design decision. 802 tests. 5 academic benchmarks. Architecture details: docs/ARCHITECTURE.md.

The knowledge graph after a few weeks of daily use. Each dot is a belief. Lines are relationships (supports, contradicts, supersedes, temporal sequence, semantic similarity).

---

Obsidian Integration (Optional)

agentmemory can sync its belief graph to an Obsidian vault. Each belief becomes a markdown note with wikilinks to related beliefs. This gives you:

• Browsable knowledge graph: see what the system knows, organized by topic and relationship type
• Manual curation: edit, delete, or reorganize beliefs directly in Obsidian
• Graph visualization: Obsidian's graph view renders the belief network as an interactive node graph

Setup: agentmemory sync-obsidian --vault ~/path/to/vault. See docs/OBSIDIAN.md for details.

Known limitation: The graph visualization becomes sluggish with large belief databases (1000+ nodes). Obsidian's graph renderer wasn't designed for graphs this dense. The beliefs and notes are fully functional regardless -- it's the visual graph view that struggles. A more performant visualization layer is on the roadmap.

---

Compatibility

Tested with Claude Code and Codex (OpenAI) via MCP (Model Context Protocol). The architecture is agent-agnostic. Any MCP-compatible client can use agentmemory as a memory backend. See Installation for Codex/Windows/WSL setup instructions.

---

Documentation

• Getting Started: Installation | Workflow
• Reference: Commands | Obsidian Integration | Privacy
• Technical: Architecture | Benchmarks | Case Studies | Philosophy

Development

git clone https://github.com/robotrocketscience/agentmemory.git
cd agentmemory
uv sync --all-groups
uv run pytest tests/ -x -q

Contributions welcome. See CONTRIBUTING.md.

Citation

@software{agentmemory2026,
  author    = {robotrocketscience},
  title     = {agentmemory: Persistent Memory for AI Coding Agents},
  year      = {2026},
  url       = {https://github.com/robotrocketscience/agentmemory},
  license   = {MIT}
}

License

MIT