agent-memory
A no-code AI memory system, AI-enablement tool, and migration tool —
all in one repo. Markdown only. No code to run. No API keys.
Three things in one:
-
A memory system — clone it, open with your agent, work normally.
Context persists across sessions and across different AI agents — and it
evolves: frequently-used facts strengthen, unused ones fade to an archive,
and the live continuity.md stays lean (see "Evolving Memory" below).
-
An enablement tool — point your agent at any existing repo and it
gets a tailored memory system set up automatically.
-
A migration tool — if the target repo already uses vendor AI files
(Cursor, Aider, Continue, Cline, Roo, Windsurf, Copilot, etc.), they get
migrated into the unified format. Steering files folded in, chat history
converted to dated session logs, originals preserved under legacy/.
Part of the Mercury family — Accenture's advanced software foundations for human–AI
collaboration — since September 10, 2026, having proven itself across multiple field
installations (see The Mercury Family below). Official home:
github.com/Accenture/mercury-go · documentation:
accenture.github.io/mercury-go · Apache-2.0.
The tool kept its name and its version at graduation (v4.39.2 at the time) — graduation recognized
the tool's state, it did not change it; enabled repositories needed no action for it.
The Mercury Family
Advanced software foundations for human–AI collaboration — Accenture open source,
Apache-2.0. Composable engines whose applications are assembled from self-contained functions
and YAML-configured event flows — a shape human developers and AI agents read equally well —
plus the shared memory layer (this tool) that keeps every human and every AI agent on a
project oriented on the same intent and state. Full page:
The Mercury Family.
Quickstart
Three short phases: install the tool, enable a repo, then work in that repo.
1 · Install agent-memory (one-time)
git clone https://github.com/Accenture/mercury-go agent-memory
cd agent-memory
Open the cloned folder with your AI agent (Claude Code, Gemini CLI, Cursor, Kiro, …), and make
your first prompt:
"Start from AGENTS.md."
This loads the one-line universal shim, which points to memory/PROTOCOL.md before any
substantive work. It is the reliable entry point on every vendor — and is required in enterprise IDEs
(e.g. Kiro) that otherwise self-bootstrap from their own onboarding before reading AGENTS.md.
2 · Enable a target repo
VS Code / Kiro: add the target repo to the same workspace as this tool, so the agent can
read both. Other CLIs (Claude Code, Gemini CLI, …) work fine without this.
Then ask:
"AI enable /path/to/your-project."
The agent will detect any existing AI footprint (Cursor, Aider, Copilot, Kiro, …) and offer
migration (with a dry-run option), analyse the repo (language, stack, type), generate tailored
memory/ files, install bootstrap files for all major agents, preserve originals under legacy/,
and report exactly what happened.
3 · Work in your AI-enabled repo
# Commit the freshly enabled repo
cd /path/to/your-project
git add . && git commit -m "chore: AI-enable repo"
From now on, open the target repo with any AI agent and just work — it reads memory/
automatically, orients without re-explaining, and records decisions as it goes. Commits stay
deliberate and human-initiated, with a self-identifying Co-Authored-By: trailer.
Note for enterprise IDEs (e.g. Kiro). Per-machine vendor dirs (.kiro/, .claude/, …) are
gitignored, so a fresh clone won't have them — after the agent loads the protocol, run
sync skill adapters to regenerate your local skill adapters. Anything the IDE later deposits
in .kiro/ (hooks, steering) stays gitignored and per-machine, so it never touches the shared
memory/ layer; human-gated commit hooks (like Kiro's) align with agent-memory's
deliberate-commit model.
Design Philosophy — Two Layers That Coexist
There are two distinct AI memory layers in a developer's life, and this tool
treats them as separate by design:
| Layer | Where it lives | Who owns it | What it holds |
|---|
| Personal | ~/ (your home folder) | You | Your chosen vendor's chat history, model preferences, global settings — your own AI workflow |
| Shared (team) | The repo's memory/ directory | The team, via git | Project rules, decisions, session logs — collaboration context across contributors |
The tool only ever touches the team layer. Your personal ~/.claude/,
~/.cursor/, ~/.aider/, Application Support folders, AppData — none of it
is read, modified, or moved. Whatever vendor you prefer keeps working exactly
as it did before.
This matters because:
- Users keep their workflow. If you love Cursor, you keep using Cursor
with all your personal history and tweaks. Enablement does not migrate or
disturb that.
- Teams get a shared layer. Contributors using different vendors —
one on Claude Code, one on Cursor, one on Aider — all read and write to
the same
memory/ folder in the repo. Common ground without forcing a
common tool.
- Migration only touches repo-committed artifacts. If a vendor's chat
history happened to be checked into the repo (e.g.
.aider.chat.history.md,
.continue/sessions/), that gets converted. Anything in your home folder
stays in your home folder.
Evolving Memory (Long-Term)
Memory doesn't just accumulate — it evolves, the way human memory does:
frequently-used facts strengthen, unused ones fade, important ones stay
permanent. It stays 100% markdown; the agent does the work, no code runs.
- Each fact carries metadata in an HTML comment (
id, created, last_used,
uses, tier) — invisible when rendered, maintained by the agent.
- Usage is event-sourced. Session logs record a
## Memory References list of
the fact ids they touched; that log is the ledger. A periodic review ritual
recomputes uses/last_used from it — so the numbers are reproducible by any
agent, on any vendor.
- No floating-point scoring. Tiers (
core → active → working → archive-candidate → archived) are decided by counting session files against integer windows, so
Claude, Gemini, and Cursor all reach the same decision. Tunable in
memory/decay-policy.md.
- Nothing is deleted. Faded facts move to
memory/archive/ (cold storage,
greppable via INDEX.md); referencing one again pulls it back to active.
core is human-set and ## Architectural Invariants + open work never decay.
Reference: DECAY.md (the rules) and REVIEW.md (the ritual), installed at the
root of every enabled repo.
Fresh-Context Second Opinion
A long AI session over-trusts its own trajectory — the agent that built a solution is the
least likely to challenge it. The highest-value antidote is a reviewer with clean memory:
a fresh session or a different vendor that didn't live the work. agent-memory ships this as two
built-in skills, installed into every enabled repo:
second-opinion — at a milestone (or when blocked or facing a risky change), it distills
a compact snapshot from continuity.md + recent session logs (never a parallel state
file) and, behind a security advisory you must acknowledge, hands it to a clean-context
reviewer to challenge.apply-critique — takes the reviewer's critique back through a bounded, validated,
human-gated loop: a few scoped fixes, then deterministic checks (build/tests + memory-lint),
then a summary of what was applied vs. rejected and why.
The reviewer is a hypothesis generator, not an authority — its critique is advisory and
gated by deterministic checks and your decision. (That's the lesson the memory layer learned when
a clean-context reviewer once over-archived still-referenced facts — so the guardrail is built
in.) Snapshots and critiques are personal, gitignored scratch (review-scratch/); sharing one
with another AI is your conscious decision, which the advisory makes explicit. Like the rest of
the tool: zero overhead by default — nothing runs unless you invoke it.
Also installed: memory-lint, the deterministic Python-3 verifier the review ritual relies
on (see Evolving Memory above). All three built-ins are tool-managed — fork under a new skill
name to customize, since upgrades overwrite them.
Versioning & Upgrades
The tool is versioned (root VERSION, semver). Each enabled repo stamps
.agent/version.md with the version it's on, so re-running enablement can upgrade
it in place — additively, never destructively.
Recent releases — the 10 most recent. The complete, official record is in
CHANGELOG.md; the full in-place upgrade ladder — every rung, including the
foundational milestones (1.0.0 fresh enable · 2.0.0 vendor migration · 3.0.0 evolving
memory · 4.0.0 the VBDI cognitive loop · 4.1.0 the cross-vendor skills layer) — lives in
UPGRADE.md.
| Version | Capability |
|---|
| 4.42.3 | The step-6 commit check, measured in the field: mercury-composable ran v4.42.2's check on its first real candidates. It caught a release-sweep convention the v4.12.20 release applied without declaring, but missed the Snyk placeholder rule the same release applied: the retired modules' paths were busy over all history (15%) and quiet in the window (1 of 112 commits — the release itself), so the all-history 5% cut dropped exactly the rare commit the check exists for. A path is now a hub only when busy over all history and in the window, and a path the window touched once is never one. Also: the window starts at the full timestamp of the log before it (git completes a bare --since date with the current time of day), commits map to the log carried by the next log-carrying commit in history, and the schema asks a fact that governs files to name them in backticks. No protocol change |
| 4.42.2 | The step-6 subject read starts with the window's commits: RFC-0006's measurement on this repo's history (every fact ever archived as faded — nine; one wrongful, git-hook-fragment-dispatch) showed that sessions describe their work in prose, not by the paths a fact names: the v4.42.1 log search found neither true session, while the window's commits touching the fact's paths found both, with no flag on any correct archival once hub files are left out (paths touched by ≤ 5% of all commits). REVIEW.md step 6 now checks commits first, then logs, and holds every hit to the decision test — a fact recording an event (a release shipped) is not kept alive by later work on the same code. No protocol change |
| 4.42.1 | Declare a fact consulted to make a decision — and check for declaration gaps before archiving one: field report (mercury-composable and mercury, on v4.42.0): three in-use facts archived in five weeks, each consulted to make a decision but never declared, so refresh-metadata read reliance as non-use and memory-lint reported clean — a consultation leaves no diff for [undeclared-reference] to see. The protocol now defines relied on with a decision test (you would have decided differently without it; a read that shaped nothing is not a use), DECAY.md §2 sharpens Referenced to match, and REVIEW.md step 6 gains the fact-level twin of step 5's thread rule: before archiving a fact as faded, read the window's logs for its subject; an exercised-but-undeclared subject is a declaration gap — keep the fact, declare it. This repo's own git-hook-fragment-dispatch archival (2026-09-18) was a fourth instance. Protocol text changed → semantic row |
When you "AI enable" a repo that's already on an older version, Mode B detects the
drift and reconciles it against the current target state (MANIFEST.md) — one
diff-and-apply pass plus the few version-gated semantic steps, with UPGRADE.md as the
per-version record (the user's entry point stays the single "AI enable this repo"
command). A missing .agent/version.md is treated as a pre-versioning install and
upgraded from the 2.x baseline.
The tool detects and migrates from these vendors:
| Vendor | Detected via | What's migrated |
|---|
| Claude Code | CLAUDE.md (non-ours), .claude/, .claude/skills/ | Steering, JSONL session history, skills → agent-skills/ |
| Cursor | .cursorrules, .cursor/rules/*.mdc | All steering files |
| Cline | .clinerules, .cline/ | Steering, history |
| Roo Code | .roorules, .roo/ | Steering, history |
| Aider | .aider.conf.yml, .aider.chat.history.md, CONVENTIONS.md | Steering, full chat history |
| Continue.dev | .continue/config.json, .continue/sessions/*.json | Steering, JSON sessions |
| Codeium / Windsurf | .windsurfrules, .codeiumrc, .windsurf/ | Steering, history |
| GitHub Copilot | .github/copilot-instructions.md (non-ours), .github/skills/, .agents/skills/ | Steering, skills → agent-skills/ (no history) |
| GPT / Codex | AGENTS.md (non-ours), .codex/ | Steering, history |
| Zed AI | .rules, .zed/ | Steering, history (with safety check) |
| Gemini CLI | GEMINI.md (non-ours), .gemini/ | Steering, history |
Google Antigravity (agy) | .agents/ (skills/, mcp_config.json), ~/.gemini/antigravity-cli/ | Steering, skills → agent-skills/ (Antigravity is the Gemini CLI successor; reads .agents/skills/, not .gemini/commands/) |
| Kiro | .kiro/ (steering/, skills/, ); also auto-reads root |
Migration rules per vendor: see MIGRATE.md.
Migration Behaviour
- Target repo only. Every read, move, and write is scoped to the target
repository. The user's
~/, AppData, Application Support, and global vendor
config are never touched. See "Design Philosophy" above.
- Originals preserved. Every vendor file is moved (not deleted) to
legacy/<vendor>/ in the target repo, with its relative path preserved.
- Steering folded in. Vendor rules become a
## Migrated rules from <vendor>
section inside memory/instructions.md. Nothing is discarded.
- History becomes sessions. Chat logs and JSONL files are parsed and split
into dated
memory/sessions/YYYY-MM-DD-HHMMSS.md files in our standard format.
- Skills promoted. Vendor skill bundles (e.g.
.claude/skills/, .kiro/skills/, .github/skills/) become
neutral, committed agent-skills/<name>/SKILL.md capabilities — not flattened into steering —
with Claude/Gemini/Cursor/Kiro/Copilot adapters regenerated. See docs/DESIGN-skills-layer.md.
- Contradictions surfaced. If two vendors had conflicting rules, both are
preserved and an Open Thread is added asking the user to resolve.
- Idempotent. Running enable on an already-migrated repo detects our format
and exits cleanly without changes.
- Dry-run supported. Answer
dry-run when prompted to see what would happen
without writing anything.
Use as a Memory System Directly
If you want this repo to be your project's memory layer (not a tool):
git clone https://github.com/Accenture/mercury-go my-project-memory
cd my-project-memory
# Edit memory/instructions.md and memory/continuity.md for your project
# Then open with your agent — it reads the memory files automatically
claude
Supported Agents (Bootstrap Files Installed)
| Agent | Bootstrap file installed |
|---|
| Claude Code | CLAUDE.md |
| Gemini CLI | GEMINI.md |
Google Antigravity (agy) | AGENTS.md (Agent Skills standard; reads .agents/skills/) |
| ChatGPT / Codex | AGENTS.md |
| Cursor | .cursorrules |
| Windsurf | .windsurfrules |
| GitHub Copilot | .github/copilot-instructions.md |
Repo Structure
agent-memory/
VERSION ← tool version (semver)
ENABLE.md ← protocol: detect, migrate, generate, upgrade
MIGRATE.md ← per-vendor migration rules (tool-only)
UPGRADE.md ← in-place version-upgrade ladder: per-version record + semantic-step detail (tool-only)
MANIFEST.md ← declarative install target state + semantic-steps index (tool-only, v4.35.0)
scripts/ ← reconcile helper: reconcile.py / reconcile.mjs + mirror tests (tool-only)
DECAY.md ← evolving-memory rules (installed into targets)
REVIEW.md ← the review ritual (installed into targets)
SKILLS.md ← skills reference: author/sync/adopt/sanity (installed; on-demand)
MERGE.md ← git-conflict resolution protocol (installed; on-demand)
AGENTS.md ← one-line universal pointer to memory/PROTOCOL.md
CLAUDE.md / GEMINI.md ← vendor bootstraps for this repo
.cursorrules / .windsurfrules ← Cursor / Windsurf bootstraps
.github/copilot-instructions.md ← GitHub Copilot bootstrap
.github/pull_request_template.md ← PR description convention: What / Why (installed on GitHub-hosted targets)
.github/workflows/agent-memory.yml ← CI floor: memory-lint + session-log check (GitHub half; GitLab twin under templates/.gitlab/)
.githooks/ ← composable ritual triggers (committed; agent-activated)
pre-commit / post-commit ← deterministic fragment dispatchers
pre-commit.d/ / post-commit.d/ ← ordered hook fragments (managed behavior at 50-*)
init.sh · README.md
.gitignore / .gitattributes ← AI-infra ignores + LF pinning (merged into targets)
CHANGELOG.md / LICENSE ← official release notes / Apache-2.0
templates/ ← installed into target repos
AGENTS.md, CLAUDE.md, GEMINI.md, ...
memory/PROTOCOL.md ← canonical target-only memory protocol
.gitlab-ci.yml ← GitLab CI floor root wiring (v4.31.0; installed when target has none)
.gitlab/agent-memory-ci.yml ← GitLab CI floor job (advisory; forge twin of the GitHub workflow)
.gitlab/merge_request_templates/Default.md ← MR What / Why template (GitLab)
docs/arch-decisions/ADR.md, RFC.md ← the optional governance pair (skeletons; adopted on request, never imposed — v4.42.0)
.azuredevops/agent-memory-ci.yml ← Azure DevOps CI floor (own pipeline; one-time activation)
.azuredevops/pull_request_template.md ← PR What / Why template (Azure DevOps)
memory/
instructions.md ← with {{placeholders}}
continuity.md ← with {{placeholders}}
decay-policy.md ← evolving-memory windows/triggers
sessions/.gitkeep
.agent/schema.md ← canonical file format (verbatim)
.agent/version.md ← install manifest (with {{placeholders}})
memory/ ← this tool's own memory layer
PROTOCOL.md ← dual-mode tool protocol + session lifecycle
instructions.md
continuity.md
decay-policy.md
sessions/ ← dated logs (immutable event log)
archive/ ← faded facts (cold storage, never deleted)
agent-skills/ ← portable skills: neutral source of truth (vendor adapters gitignored)
memory-lint/ ← built-in: deterministic memory verifier (Python + Node, at parity)
second-opinion/ ← built-in: snapshot the task for a clean-memory reviewer
apply-critique/ ← built-in: apply a critique via a gated, human-approved loop
sync-adapters/ ← built-in: regenerate per-vendor adapters (bash · node · python)
harvest-knowledge/ ← built-in: re-scan docs → fold durable facts into memory (on-demand)
archive-fact/ ← built-in: safe deterministic archive-move for the review (Python + Node)
refresh-metadata/ ← built-in: recompute fact footers (last_used/uses/tier) from the log (Python + Node)
hello-world/ ← dogfood demo skill
(the seven built-ins ship provenance: agent-memory-builtin and install into every enabled repo)
docs/ ← design rationale + governance (human-facing, on-demand)
arch-decisions/
ADR.md ← Architecture Decision Records (optional convention; dogfooded here)
RFC.md ← the proposal register (RFC-NNNN; an ADR is written only on acceptance)
DESIGN-*.md ← long-form per-feature design narratives
agent-cognitive-framework.md ← the VBDI source framework
examples/
rust-event-bus/ ← Mode A: REAL fresh enable on a Rust repo
memory/ ← actual generated output (unedited)
instructions.md
continuity.md
sessions/.gitkeep
ENABLE_OUTPUT.md ← real terminal output of the enablement
migrated-cursor-aider-project/ ← Mode C: migration from Cursor + Aider
legacy/ ← originals preserved
cursor/.cursorrules
cursor/.cursor/rules/api.mdc
aider/.aider.chat.history.md
memory/
instructions.md ← real output with migrated rules folded in
continuity.md ← real output with migration summary
sessions/
2026-06-08.md ← Aider session migrated to our format
2026-06-09.md
2026-06-10.md
ENABLE_OUTPUT.md ← terminal output of the migration
evolving-memory-example/ ← the review ritual in action
continuity-before.md ← live state before a review
continuity-after.md ← same file after (lean: archived + reactivated)
decay-policy.md ← the windows used in the example
archive/2026-Q2.md ← facts moved to cold storage
archive/INDEX.md
sessions/2026-06-20-141503.md ← session log with Memory References + review summary
Customising the Tool
The agent's behaviour is controlled entirely by ENABLE.md and MIGRATE.md —
plain markdown files. Edit them to:
- Change how detection works
- Add support for a new vendor (add a row to the table + a per-vendor section)
- Adjust conflict-handling defaults
- Change the report format
No code changes ever required.
Three Modes at a Glance
ENABLE.md Step 3 → Mode A: Fresh Enable (nothing detected → templates fill from analysis)
Mode B: Already Ours (memory/ exists → up-to-date skips; older → reconcile vs MANIFEST.md + semantic steps)
Mode C: Migrate Vendor (vendor files found → MIGRATE.md takes over)
Changelog
Notable changes are recorded in the CHANGELOG.md.
Contributing
Contributions are welcome. Please read CONTRIBUTING.md and the
CODE_OF_CONDUCT.md before opening a pull request; our
Inclusive Language Guidebook describes the language we use.
License
Copyright 2026 Accenture. Licensed under the Apache License, Version 2.0. See the LICENSE file for the full text.
