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 setupRestart Claude Code. In any project: /mem:onboard .
That's it. Three commands. Your agent now remembers permanently.
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 7-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 git@github.com:robot-rocket-science/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.
| 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. |
| 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)
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 cross-reference 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 replaces that entire chain with a mechanism. Relevant context is found through a 7-layer search and injected as part of your prompt before the agent sees it. The agent doesn't have to remember to check a file. It doesn't have to follow a cross-reference. The knowledge is already there, selected by relevance, 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. |
- 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.
agentmemory works in the background:
- It listens. Picks up decisions, corrections, and preferences from your conversations.
- It retrieves. Injects relevant beliefs before the agent responds to each prompt.
- 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.
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.
Conversations are broken into individual beliefs stored in a local SQLite database. Retrieval uses full-text search, graph traversal, and vocabulary bridging. Nothing to install, nothing to host, nothing that phones home.
98 experiments drove every design decision. 954 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).
Currently supports Claude Code via MCP (Model Context Protocol). The architecture is agent-agnostic. Any MCP-compatible client can use agentmemory as a memory backend.
- Getting Started: Installation | Workflow
- Reference: Commands | Obsidian Integration | Privacy
- Technical: Architecture | Benchmarks | Case Studies | Philosophy
git clone https://github.com/robot-rocket-science/agentmemory.git
cd agentmemory
uv sync --all-groups
uv run pytest tests/ -x -qContributions welcome. See CONTRIBUTING.md.
@software{agentmemory2026,
author = {robotrocketscience},
title = {agentmemory: Persistent Memory for AI Coding Agents},
year = {2026},
url = {https://github.com/robot-rocket-science/agentmemory},
license = {MIT}
}
