Why It Exists
Core Features
What It Looks Like In Practice
Live Demo
Requirements
Quickstart
Run The Dashboard
Documentation
Repository Layout
Status
Stability
Contributing

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 Features

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 a memory.md ledger, isolated dual worktrees, preview/apply closeout, and all-or-nothing integration so code and memory stay synchronized.
Repo-owned agent behavior: Each memory repo carries system/ 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 under ar-memory/. Teams that need separate memory repositories can use external memory under ar-coordination/memory-repos/ar-<repo>/. For the full tour, see Features.

What It Looks Like In Practice

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.

Live Demo

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.

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.

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 require jq; the current starter package uses a Python hook. 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:

Copy the harness package — Pick your harness guide under docs/install, copy that harness's native starter files from this repo into the workspace, then render the copied package. The render-starter script is a convenience: it infers the workspace root from the copied harness folder and fills the copied package's path, repository, and hook-command placeholders from a single --repo list such as --repo my-app shared-lib. You can also do those replacements by hand. These packages include the harness-visible skills, hooks/rules/instructions, and MCP settings templates.
Wire the MCP server — Register Agents Remember MCP from PyPI with uvx:
```
uvx agents-remember-mcp@latest --config /absolute/path/to/agents-remember-settings.json
```
Use the agents-remember-settings.json path from the copied harness package. Then restart the harness once so it loads the MCP server, native skills, and package hooks/rules/instructions.
Onboard your project — Invoke the copied skill c-13-install-and-onboard. It runs or verifies runtime_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 the l-01-agent-lifecycles skill: a developer-facing session is the architect; spawned backend orchestrators and other role seats follow their role briefs. 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.

Run The Dashboard

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

--config is optional: the CLI walks up from the current directory and uses the nearest .claude/mcp/agents-remember-settings.json, or the --config recorded in an .mcp.json agents-remember entry — 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

Or let the MCP server supervise it: set "dashboard": {"autoStart": true} in the MCP settings JSON and every server boot ensures the daemon — adopting a healthy one, starting a missing one, and restarting on version mismatch so an upgrade is picked up by the next session (Settings Reference).

Pinning a version is the debugging/repro path, not the default: uv tool install 'agents-remember-mcp==3.0.0rc6', or one-shot without installing, uvx --from 'agents-remember-mcp==3.0.0rc6' agents-remember dashboard.

Pre-release note (until 3.0.0 final): the dashboard currently ships in 3.0.0rcN pre-releases, which default version resolution skips. Install with uv tool install --prerelease allow agents-remember-mcp, and register the MCP server with an explicit agents-remember-mcp==3.0.0rcN pin instead of @latest.

Documentation

Features - the concentrated tour of what Agents Remember gives users.
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 - the l-01-agent-lifecycles skill and its build modes (research-only exit / w-02-light-task-workflow skill task / master + light sub-task series), 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/
  AGENTS.md                         # source checkout instructions
  README.md                         # public front door
  skills/                           # canonical skill source tree
  scripts/sync-skills.py            # sync skills into package/harness copies
  scripts/sync-runtime.py           # sync runtime assets into package data
  agents-md-files/                  # canonical installed AGENTS.md templates
  benchmarks/                       # canonical optional benchmark package source
  providers/                        # canonical provider runtime assets
  system/defaults/examples/         # canonical scaffold examples
  mcp/                              # package-local MCP server and services
    src/agents_remember/package_data/
      runtime/
        agents-md-files/            # generated copy of root agents-md-files/
        skills/                     # generated package copy of root skills/
        providers/                  # generated copy of root providers/
        system/defaults/examples/   # generated copy of root system/defaults/examples/
      benchmarks/                   # generated copy of root benchmarks/
  docs/                             # user-facing documentation

Edit skills in root skills/, then run python3 scripts/sync-skills.py to refresh the MCP package data and every harness starter package. The pre-commit and pre-push hooks run python3 scripts/sync-skills.py --check.

Edit runtime assets in root agents-md-files/, benchmarks/, providers/, and system/, then run python3 scripts/sync-runtime.py to refresh MCP package data only. The pre-commit and pre-push hooks run python3 scripts/sync-runtime.py --check.

The installed runtime lives in ar-coordination/ — by default <workspace>/ar-coordination/, inside the workspace (never your home directory) — not in the source checkout. The c-13-install-and-onboard skill shows this and every other install path as a workspace-first default you can accept or override:

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 3.0.0rc6 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 and change only on a major bump; the internals beneath them and the optional semantic/relationship providers may still evolve, so pin a version and read the notes for your target version in GitHub Releases — the repository's canonical changelog — before upgrading. The Claude Code path is the most exercised; other harnesses are supported but less battle-tested.

The 3.0 arc: the working session itself is now observable and steerable — a system-managed agent lifecycle with durable approval gates and an event/projection layer, served as the mission-control browser cockpit directly from the MCP package (agents-remember dashboard; #2, #43). The rc tag means the cockpit surface is still settling toward the final 3.0.0 contract; the architecture beneath it is the one described above.

Stability

Following semantic versioning from 1.0.0, these public contracts will not change without a major version bump: skill IDs (e.g. the c-08-ar-coordination-context-resolver and w-02-light-task-workflow skills), 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 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.

Agents Remember

README

Table of Contents