Agents Remember
About
`Agents Remember` is a Drift-aware repository memory for coding agents in complex codebases. Captures what code can't say on its own! Retrieves memory by path, semantic search, and relationship (code-graph).
Details
- Author
- foxfire1st
- Categories
- AI, Developer Tools, Knowledge Base, Other
Jump to
Setup
Install Agents Remember in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/foxfire1st/agents-remember
Follow the installation instructions in the repository README, then restart your MCP client.
Git-verified records for what your coding agents know. A control plane for what they do.
📖Current docs:https://foxfire1st.github.io/agents-remember/
🤖Machine-readable summary:https://foxfire1st.github.io/agents-remember/llms.txt
Note: caches and search snippets may serve an outdated copy of this README — the docs site above is canonical and always current.
- Why It Exists
- Core Features
- What It Looks Like In Practice
- Live Demo
- Requirements
- Quickstart
- Run The Dashboard
- Documentation
- Repository Layout
- Status
- Stability
- Contributing
Modern coding agents can make clean, plausible edits while missing the project-specific rules that make those edits safe. A top-level instruction file can help, but it does not naturally reappear when the agent is deep in a file and deciding what to change.
Agents Remember fixes that: the matching note is reachable at the moment of the edit — most often by the very path the agent is already working in — so project rules surface exactly when a change is being made, not buried in a top-level file.
Agents Remember gives coding agents project memory they can verify and act on.It turns local invariants, naming rules, migration scars, cross-repo contracts, and "this looks safe but is not" facts into versioned Markdown beside the code, checks that memory against Git before use, and updates it only after approved work lands.
src/orchestrator/core_editor.py ar-memory/onboarding/src/orchestrator/core_editor.py.md
- Path-addressed memory:A source file's note lives at a deterministic mirror path, so an agent holding a file can reach the right context without search, ranking, or guesswork.
- Git-proven freshness:File notes, route overviews, and entity catalogs are drift-checked against source commits, route scopes, or deterministic fingerprints before they are trusted.
- Search that finds, not decides:Optional semantic memory and code-graph providers help locate relevant files, callers, dependencies, and concepts, but verified Markdown and source code remain the truth.
- Memory that lands with code:External memory repos use amemory.mdledger, isolated dual worktrees, preview/apply closeout, and all-or-nothing integration so code and memory stay synchronized.
- Repo-owned agent behavior:Each memory repo carriessystem/files for path rules, tools, coding guidelines, documentation sources, branch policy, and reporting shape, so the same project rules load across harnesses.
- Harness-ready first run:Starter packages for Claude Code, Codex, Cursor, Antigravity, VS Code Copilot, Hermes, Pi.dev, and OpenClaw carry the native MCP, skills, hooks, rules, and instruction files each harness needs.
The default setup stores durable memory in the target repository underar-memory/. Teams that need separate memory repositories can use external memory underar-coordination/memory-repos/ar-<repo>/. For the full tour, seeFeatures.
A source file has an onboarding note beside it, reached by path:
mcp/src/agents_remember/mcp/server.py ar-memory/onboarding/mcp/src/agents_remember/mcp/server.py.md
At task start the agent orients and checks memory health:
context_packet(repo_id="my-app") memory_quality_check(repo_id="my-app")
It then reads the source file and its onboarding note together before proposing a change. After the change is approved and lands, the onboarding is refreshed and re-verified against the new commit — so the note stays true to the code.
Agents Remember runs on itself. The companion memory repo is:https://github.com/Foxfire1st/ar-agents-remember
That repo contains the live onboarding layer, so you can inspect how by-path memory, drift-aware updates, and contribution-time onboarding look in practice.
Before the Quickstart, make sure the host has:
- uv(foruvx) or pip, andPython 3.11+— the agent runs the MCP server withuvx, which picks a compatible interpreter.
- Git, withuser.name/user.emailconfigured (memory and worktree commits need an author; otherwise a placeholder identity is used).
- Dockerrunning, only if you enable the optional providers. The semantic-memory provider (grepai) also uses a Dockerized Ollama and pulls an embedding model (nomic-embed-text) on first setup — no host Ollama install needed.
Providers, Docker, and Ollama are only needed for the optional Docker-backed providers; the core by-path memory works without them. Claude Code hooks do not requirejq; the current starter package uses a Python hook. Full detail and troubleshooting live in theMCP package README.
This is the short path for a new workspace. The detailed walkthrough lives inGetting Started.
-
Wire the MCP server— Register Agents Remember MCP from[PyPIwithuvx:
uvx agents-remember-mcp@latest --config /absolute/path/to/agents-remember-settings.json
Use theagents-remember-settings.jsonpath from the copied harness package. Thenrestart the harness onceso it loads the MCP server, native skills, and package hooks/rules/instructions.
Onboard your project— Invoke the copied skillc-13-install-and-onboard. It runs or verifiesruntime_install(), asks whether to scaffold a new memory repo or use an existing one, bootstraps onboarding when needed, and starts provider indexing when providers are enabled.
That is the normal first-run path.skills_install()remains available as a maintenance/manual MCP tool, but the starter packages already provide the initial skills and harness files.
After that, normal work runs through thel-01-agent-lifecyclesskill: developer-facing free chat answers research inline and launches a sprint-bound architect after the durable sprint and first leaf exist; spawned backend seats follow their role briefs. The agent resolves the active context withc-08-ar-coordination-context-resolver, checks memory quality withc-02-memory-quality-control, reads relevant onboarding beside code, and updates onboarding after approved changes.
The mission-control dashboard ships inside the MCP package. Install the CLI once with uv — latest stable, no version pin — then start the cockpit from anywhere in your workspace:
uv tool install agents-remember-mcp agents-remember dashboard
--configis optional: the CLI walks up from the current directory and uses the nearest.claude/mcp/agents-remember-settings.json, or the--configrecorded in an.mcp.jsonagents-rememberentry — the same settings file the MCP server boots from.
For a dashboard that survives closing the terminal, use daemon mode:
agents-remember dashboard --daemon # detach; state + log under <coordinationRoot>/logs/dashboard/ agents-remember dashboard --status # exit 0 when running, 1 when not agents-remember dashboard --stop
…
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
