agentmemory

# agentmemory > **Correct your AI agent once. It remembers forever.** [](LICENSE) [](https://pypi.org/project/agentmemory-rrs/) [](https://www.python.org/downloads/) --- 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. ```bash pip install agentmemory-rrs agentmemory setup ``` Restart Claude Code. In any project: `/mem:onboard .` That's it. Three commands. Your agent now remembers permanently. <p align="center"><img src="https://robotrocketscience.com/projects/agentmemory/comics/01-no-implementation-cs002cs006.png" width="480" alt="Comic: user says 'no implementation, we're in research.' Agent says 'got it!' Next session: 'Ready to implement?' User: 'I TOLD YOU. TWICE.' Agent: '...three times, actually!'"></p> --- ## 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 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.](docs/PHILOSOPHY.md) --- ## 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](https://en.wikipedia.org/wiki/Bayesian_inference) 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 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](docs/BENCHMARK_RESULTS.md) | | 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](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** ```text 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](docs/internal/case-study-positioning.md). --- ## Under the Hood 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](docs/ARCHITECTURE.md). <p align="center"><img src="https://robotrocketscience.com/projects/agentmemory/obsidian-graph-full.jpg" width="600" alt="Knowledge graph visualization showing thousands of interconnected beliefs built up over weeks of use"></p> <p align="center"><em>The knowledge graph after a few weeks of daily use. Each dot is a belief. Lines are relationships (supports, contradicts, supersedes).</em></p> --- ## Compatibility 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. --- ## Documentation - **Getting Started:** [Installation](docs/INSTALL.md) | [Workflow](docs/WORKFLOW.md) - **Reference:** [Commands](docs/COMMANDS.md) | [Obsidian Integration](docs/OBSIDIAN.md) | [Privacy](docs/PRIVACY.md) - **Technical:** [Architecture](docs/ARCHITECTURE.md) | [Benchmarks](docs/BENCHMARK_RESULTS.md) | [Case Studies](docs/internal/case-study-positioning.md) | [Philosophy](docs/PHILOSOPHY.md) ## Development ```bash git clone https://github.com/robot-rocket-science/agentmemory.git cd agentmemory uv sync --all-groups uv run pytest tests/ -x -q ``` Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md). ## Citation ```bibtex @software{agentmemory2026, author = {robotrocketscience}, title = {agentmemory: Persistent Memory for AI Coding Agents}, year = {2026}, url = {https://github.com/robot-rocket-science/agentmemory}, license = {MIT} } ``` ## License [MIT](LICENSE)