# agentmemory

> **Correct your AI agent once. It remembers forever.**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/agentmemory-rrs)](https://pypi.org/project/agentmemory-rrs/)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](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: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.](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 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 7-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](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 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. **794 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, temporal sequence, semantic similarity).</em></p>

---

## Obsidian Integration (Optional)

agentmemory can sync its belief graph to an [Obsidian](https://obsidian.md) 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](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

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/robotrocketscience/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/robotrocketscience/agentmemory},
  license   = {MIT}
}
```

## License

[MIT](LICENSE)
