agent-memory

Persistent, Git-backed memory for AI coding agents.

The Problem

Every time you start a new session with an AI coding agent, it starts from zero. It doesn't know your codebase architecture. It doesn't remember the mistake it made yesterday. It doesn't know that the weird pattern in AuthManager exists for a reason and should never be touched. It doesn't know it was halfway through a task when your last session ended.

You end up repeating context, re-explaining conventions, and watching the agent make the same mistakes across sessions.

The Solution

agent-memory gives your AI agent a persistent memory that survives across sessions. It stores what the agent learns — codebase structure, coding conventions, past mistakes, sacred patterns, in-progress work — as Markdown files on a dedicated Git branch, shared across your team.

The agent reads its memory at the start of every session and writes back what it learned after every push. No manual invocation needed — two hooks handle everything automatically.

What the Agent Remembers

File	What it captures
MAP.md	Architecture pattern, module responsibilities, key entry points, critical business flows, tech debt
SYMBOLS.md	Every class and function in the codebase — the agent's grep replacement
CONVENTIONS.md	Naming patterns, architecture patterns, utility usage, test conventions
LESSONS.md	Mistakes the agent made and was corrected on — so it never repeats them
SACRED.md	Patterns that look wrong but exist for a reason — protected from "helpful" refactoring
RULES.md	Project-specific constraints you want the agent to always respect
RESUME.md	What the agent was working on, where it left off, what's next (local-only, per developer)
CHANGELOG.md	Audit trail of every task the agent completed
CONFIG.md	Repo identity, platform, timestamps, blueprint connection

How It Works

Architecture

Memory lives on a separate Git branch (ai-memory), mounted as a worktree at .memory/ in your project. This keeps memory out of your feature branches while making it accessible as regular files.

your-project/
├── .memory/              ← git worktree on ai-memory branch
│   ├── CONFIG.md
│   ├── MAP.md
│   ├── SYMBOLS.md
│   ├── LESSONS.md
│   └── ...
├── src/
├── tests/
└── .gitignore            ← includes .memory/

The Loop

Two event-driven hooks create an automatic read-write loop:

Session starts
    → SessionStart hook fires
    → Agent reads all memory files (memory-fetch)
    → Agent works with full context
    → Agent pushes code
    → PostToolUse hook fires
    → Agent records what it learned (memory-record)
    → Memory is committed and pushed
    → Next session picks up where this one left off

memory-fetch (session start): Pulls the latest memory, reads every file, surfaces alerts — in-progress work from a previous session, uncommitted changes, knowledge bus entries from other repos. The agent cannot skip any files or start work until memory is fully loaded.

memory-record (after git push): Updates the changelog, symbol registry, architecture map, lessons learned, sacred patterns, and resume state. Commits and pushes memory so the next session (or another developer's agent) has the latest context.

Shared Across Your Team

Memory is stored on a Git branch, so it's shared via push/pull — the same way code is. When one developer's agent learns something, every developer's agent knows it next session.

Scenario	Shared?
Same repo, multiple developers	Yes — same ai-memory branch
Same repo, different AI tools (Claude Code, Cursor)	Yes — same .memory/ mount
Different repos (iOS vs Backend)	Via blueprint (coming soon)

The only local-only file is RESUME.md, which tracks each developer's in-progress task state.

Install

claude plugin install /path/to/agent-memory

Quick Start

First time (project lead, once per project):

> /setup-memory

The agent creates the ai-memory branch, initializes all memory template files, mounts .memory/, and adds it to .gitignore.

Then map the codebase:

> /cartographer

The agent reads every source file, builds the symbol registry and architecture map, discovers conventions, and triages findings with you (sacred vs tech debt). For large codebases, this can span multiple sessions — progress is tracked in RESUME.md.

After that — automatic. The hooks handle reading and writing memory every session. No commands to remember.

Teammates joining:

> /setup-memory

Or without the plugin: ./scripts/mount-memory.sh

Skills

Skill	Trigger	What it does
setup-memory	/setup-memory	Initialize .memory/ — create branch, write templates, mount worktree
memory-fetch	Automatic (session start)	Pull and read all memory files before any work begins
memory-record	Automatic (after git push)	Write what was learned — changelog, symbols, lessons, resume
cartographer	/cartographer	Deep-map the codebase into memory — read every file, build the symbol index

Multi-tool Support

agent-memory works with multiple AI coding tools:

• Claude Code — full support via .claude-plugin/, including if field filtering on PostToolUse hooks
• Cursor — via .cursor-plugin/ with graceful degradation (falls back to stdin parsing for push detection)
• Copilot CLI — via generic hook output format

Coming Soon

Knowledge Bus — cross-repo memory sharing via a blueprint repo. When the backend agent changes an API contract, the iOS and Android agents learn about it at their next session start. Designed but not yet implemented.

License

MIT