Agents Remember

Durable, git-verified repo memory for coding agents.

Agents Remember makes hard-earned lessons first-class infrastructure — the local invariants, naming rules, migration scars, cross-repo contracts, and "this looks safe but is not" facts that live in people's heads, old PRs, and team habits, exactly where coding agents miss them. It keeps that knowledge as versioned Markdown beside the code, drift-checked against Git and updated only after approved work lands.

src/orchestrator/core_editor.py
ar-memory/onboarding/src/orchestrator/core_editor.py.md

Agents reach that memory three ways:

• By path — a source file's own note, found directly from its path (as above). Needs nothing extra.
• By meaning — semantic search across the memory when you know the concept but not the file.
• By relationship — a code graph for callers, callees, and dependencies.

The by-path notes are the core; meaning and relationship are opt-in providers (see Concepts and Providers).

Why It Exists

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.

Core Model

The memory layer rests on a small, strict discipline:

• Onboarding units: Markdown notes derived from source paths. A file such as src/foo/bar.ts maps to ar-memory/onboarding/src/foo/bar.ts.md in the default repo-local mode.
• Memory quality control: Before an agent trusts onboarding, C-02-memory-quality-control checks whether the source changed since the onboarding was verified. During closeout it also covers new-file onboarding and final memory quality checks.
• Approval-gated updates: Onboarding records approved current state, not guesses or plans. Task-local notes stay task-local until the developer approves implementation.

The default setup stores durable memory in the target repository under ar-memory/. Teams that need separate memory repositories can use external memory under ar-coordination/memory-repos/ar-<repo>/.

Requirements

Before the Quickstart, make sure the host has:

• uv (for uvx) or pip, and Python 3.11+ — the agent runs the MCP server with uvx, which picks a compatible interpreter.
• Git, with user.name / user.email configured (memory and worktree commits need an author; otherwise a placeholder identity is used).
• Docker running, 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.
• jq, only for the Claude Code SessionStart hook: apt install jq (Debian/Ubuntu), brew install jq (macOS), pacman -S jq (Arch), dnf install jq (Fedora), or apk add jq (Alpine). Without it the hook installs but silently injects nothing.

Providers, Docker, Ollama, and jq are only needed for the optional Docker-backed providers and the Claude Code hook; the core by-path memory works without them. Full detail and troubleshooting live in the MCP package README.

Quickstart

This is the short path for a new workspace. The detailed walkthrough lives in Getting Started.

Ask your agent to:

1. Wire the MCP server — Install Agents Remember MCP from PyPI with uvx:

   uvx agents-remember-mcp --config /absolute/path/to/agents-remember-settings.json
   

   Have your agent follow the PyPI link for setup details and help you author the settings file. Then restart the harness so it loads the server.

2. Install Agents Remember — Run the mcp tool runtime_install, then skills_install (scaffolding, skills, and provider images when providers are enabled). Then restart the harness again so it discovers the skills skills_install just wrote (some harnesses hot-reload skills and skip this; restarting is the safe default).

3. Onboard your project — Run the skill C-13-install-and-onboard. It pre-checks the setup, installs the start hook (or places the directive for harnesses without one), sets up the memory repo (it asks: scaffold a new one or use an existing one), bootstraps onboarding, and starts the providers indexing. If it installed a session-start hook, restart the harness once more so the hook activates (hooks load at session start).

Those three restarts (load the server, discover the skills, activate the hook) are the only hands-on steps; between and after them, your agent continues on its own.

After that, normal work starts in chat mode. The agent resolves the active context with C-08-ar-coordination-context-resolver, checks memory quality with C-02-memory-quality-control, reads relevant onboarding beside code, and updates onboarding after approved changes.

Documentation

• Getting Started - a fuller first-run setup.
• Concepts - onboarding units, memory roots, drift, and approval gates.
• Architecture - runtime, coordination, internal memory, and external memory.
• Workflows - chat, light task, heavy task, and when to use each.
• Benchmark Methodology - how paired codex exec --json runs are captured and compared.
• FAQ - design principles, objections, and comparisons.
• External Memory Guide - separate memory repos for selected code repos.
• Cost-aware Bootstrap - model and wave-sizing choices for token-heavy repository bootstrap.
• Settings Reference - memory-layer system/settings.json and MCP authority settings.
• Skills Reference - the installed skill families.

Repository Layout

agents-remember-md/
  AGENTS.md                         # source checkout instructions
  README.md                         # public front door
  mcp/                              # package-local MCP server and services
    src/agents_remember/package_data/
      runtime/
        agents-md-files/            # installed AGENTS.md templates
        skills/                     # installed skill source tree
        providers/                  # provider runtime assets (images, runners)
        system/defaults/examples/   # scaffold examples used by initialization
      benchmarks/                   # optional benchmark package source
  docs/                             # user-facing documentation

The installed runtime lives in ar-coordination/, not in the source checkout:

ar-coordination/
  AGENTS.md
  skills/
  system/
  memory-repos/
  providers/                        # provider runtimes (images, runners, indexes)
  benchmarks/                       # optional, installed with --include-benchmarks
  tasks/
  notes/
  worktrees/
  temp/

Status

Agents Remember is at 1.0.0 and actively developed. The core path — by-path onboarding, drift checks, and approval-gated updates — is in real use and stable enough to rely on. The public contracts listed under Stability are held stable across minor releases; the internals beneath them and the optional semantic/relationship providers may still evolve, so pin a version and read the release notes before upgrading. The Claude Code path is the most exercised; other harnesses are supported but less battle-tested.

Stability

Following semantic versioning from 1.0.0, these public contracts will not change without a major version bump: skill IDs (e.g. C-08, W-02), MCP tool names and their inputs/outputs, the ar-coordination/ and ar-memory/ layout, and the settings schema. Internal modules, provider internals, and prompt wording are not part of this promise and may change in minor releases.

Contributing

Contributions should make the memory layer clearer, safer, and easier to apply consistently. Start with CONTRIBUTING.md and keep the core rules intact: drift check before planning, approval before implementation, and onboarding updates only after approved changes.

Agents Remember runs on itself, so the best way to contribute is with the memory layer active. Download or clone this project's own memory at Foxfire1st/ar-agents-remember-md and use it as the Agents Remember memory for your checkout: you get the project's by-path onboarding at the moment you edit, and your onboarding updates land alongside your code changes — the same loop this repo asks of every contribution.