Agent Memory is a project-local Workspace Memory for AI coding agents — a versioned recall layer in .agents/memory/. It points at the project's canonical sources (AGENTS, README, specs, ADRs, code) and keeps only what agents need to continue work across sessions: active state, recent deltas, decision pointers, and evidenced learnings that have no better home. No chat history dependency and no external infrastructure (no server, vector DB, or embeddings).
Agents read and write that memory. A manual skill (/agent-memory) bootstraps and maintains it; optional lifecycle hooks add deterministic git checkpoints while you work.
Supported harnesses: Cursor, Claude Code, Codex, OpenCode, Copilot, Gemini CLI.
- Project recall, not a docs mirror. Files in Git beat paste-from-yesterday chats. Canonical docs stay canonical; memory stores links and deltas.
- Plain Markdown. Searchable with
grep, reviewable in PRs, no new runtime. - Progressive disclosure. Always-load files stay short; detail lives in canonical sources or on-demand recall (
learnings.md, …). - Inspired by Karpathy's llm-wiki (index, log, lint, small cross-linked files), adapted from source ingestion to project memory.
Memory lives at .agents/memory/ and separates canonical project sources from operational recall and durable recall:
| File | Role |
|---|---|
instructions.md |
Method: how agents read and maintain the memory. |
index.md |
Map of canonical sources + recall files (loading policy). |
current.md |
Shared active state (in progress / blockers / handoff). |
active-work/<branch>.md |
Per-branch resume scratchpad (next step, validation, assumptions). |
decisions.md |
Decision pointers (or local fallback when no ADR system). |
log.md |
Recent semantic session deltas (append at the bottom). |
Optional on demand: learnings.md or learnings-<topic>.md — evidenced learnings/pitfalls with no better source; optional when editing: hints in index.md. Capture explicitly with /agent-memory learn. Do not create parallel vision/architecture/patterns/domains copies; link the project's own docs instead.
Workflow: before a task, agents read index.md, current.md, and their branch's active-work file when it exists (plus any recall file whose when editing: hint matches task paths — contract in instructions.md); primary write is in-turn (resume fields + semantic log.md outcomes); catch-up at checkpoints via /agent-memory sync (or follow the skill's references/sync.md without invoking the skill); /agent-memory learn to capture a gated learning now; periodically /agent-memory consolidate to promote useful facts and prune closed-session noise. Hooks store ephemeral path/session evidence in .hook-sync-state only — never Markdown.
Full method: skills/agent-memory/vendor/README.md and instructions.md.
# Install skill + hooks
npx @dosx/agent-memory install
# Install skill only
npx @dosx/agent-memory install skill
# Install hooks for one harness (or omit harness for a TTY multi-select):
npx @dosx/agent-memory install hooks cursor
# Interactive install (skill + hooks / skill only / hooks only):
npx @dosx/agent-memory install cursor
# or: npx @dosx/agent-memory install
# Later: refresh skill + installed hooks (then run /agent-memory update in-agent)
npx @dosx/agent-memory updateIn your agent:
/agent-memory init # auto-detect harnesses, or: init cursor
/agent-memory bootstrap # optional: inventory sources + gaps
/agent-memory install hooks cursor # print hook-install commands (skill never runs them)
From a checkout you can also run bash hooks/install-hooks.sh cursor.
init wires each harness's native instruction file (for example Cursor .cursor/rules/agent-memory.mdc, Copilot .github/instructions/agent-memory.instructions.md, or AGENTS.md / CLAUDE.md / GEMINI.md).
It does not create harness roots (.cursor/, .claude/, …) unless you ask — and it never copies hook scripts.
Use init <harness> when you already know the agent.
/agent-memory is manual-only (never auto-triggers):
| Command | Does |
|---|---|
/agent-memory help |
List commands. |
/agent-memory init |
Create .agents/memory/; wire native instruction file(s). |
/agent-memory install hooks |
Print how to install/refresh hooks (user-run installer). |
/agent-memory update |
Migrate scaffolding; never overwrites your content blindly. |
/agent-memory bootstrap |
Inventory canonical sources and gaps; populate pointers. |
/agent-memory sync |
Refresh current.md / active-work / log.md / index.md. |
/agent-memory lint |
Broken links, orphans, duplication, stale branches, consistency. |
/agent-memory learn |
Capture one gated learning/pitfall (learn [>topic] <clue>). |
/agent-memory consolidate |
Promote useful facts; prune closed-session noise (guided). |
Optional lifecycle hooks keep ephemeral evidence current during agent work with deterministic checkpoints (no LLM loops): session binding and session-cumulative touched paths in .hook-sync-state. Hooks never write Markdown, never copy docs, and never consolidate.
Semantic content stays agent-owned: resume fields and log outcomes are written in-turn (primary); /agent-memory sync / consolidate are catch-up and promotion.
Install steps, event matrix, and project-dir resolution: hooks/README.md.
npx skills add diegoos/agent-memory --skill agent-memorygit clone --branch 0.1.1 --depth 1 \
https://github.com/diegoos/agent-memory /tmp/agent-memory
mkdir -p .agents/skills/
cp -R /tmp/agent-memory/skills/agent-memory .agents/skills/
cp -R .agents/skills/agent-memory/vendor/memory .agents/memoryThen paste the agent-memory block from skills/agent-memory/references/agent-block.md into your agent instructions file (keep the <!-- <agent-memory> --> … <!-- </agent-memory> --> markers so update can refresh only that block).
agent-memory/
├── install.ts # CLI source (Bun → bin/cli.js)
├── bin/cli.js # npx CLI (skill + hooks)
├── package.json # SoT: package / skill / hooks version
├── hooks/ # installer + harness configs (outside the skill)
└── skills/agent-memory/ # SKILL.md + vendor/ + references/
└── vendor/ # SoT: memory skeleton + UPDATE.md + method README
MIT. See LICENSE.
Security and trust model: SECURITY.md.