Skip to content
kiloloopagent-memory
agent-memory · v0.1.0 · new

Your agents start blank.
Give them a record.

Cross-session memory for coding agents. Plain Markdown files, git-native, no server. Claude Code and Codex share one store.

Facts, decisions, and unfinished work — in files you can read and edit.

Install Source ↗PyPI ↗

no database · no daemon · no server · no runtime Python dependencies

Three dimensions03 AXES · 01 STORE

Between agents, projects, and machines.

Memory travels three ways. Each one is a directory, not a service.

Between agents01

Via project files. Claude Code and Codex read the same four files at session start, so one agent knows what the other decided yesterday.

projects/<name>/memory/

Between projects02

Via org rules. Three curated files sit beside the projects and are listed for every session. Most notes still belong to a project.

org-memory/

Between machines03 · optional

Via git sync, if you turn it on. The home becomes its own repository with an allowlist. Fast-forward only, push is explicit, no merges.

~/agent-memory ↔ one private remote

The four files04 FILES · ONE JOB EACH

Project memory is four Markdown files you can open.

OACP defines the layout; this tool implements it. Date entries, supersede decisions by adding new ones, close or pause threads, write for humans.

memory/04 files
Startup and recall read these four, then the three org files. archive/, events/ and debriefs/ are never loaded.
projects/my-app/memory/project_facts.mdstable facts
# project_facts — my-app

## Stack
- Backend: Python 3.12 · FastAPI 0.115 · SQLAlchemy 2.0 (async)
- Frontend: React 18 · Vite 5 · TanStack Query
- Database: Postgres 16 on Supabase; migrations via Alembic
- Queue: none. Background work runs in-process (see known_debt)
- Deploy: Cloudflare Workers (api) + Pages (web), `main` auto-deploys

## Layout
- `apps/api`        FastAPI service, one router per domain
- `apps/web`        React app; talks to api only via `src/lib/api.ts`
- `packages/db`     schema + Alembic env; the only place models live
- `packages/ui`     shared components; no business logic

## Conventions
- One migration per PR; migration name = PR slug
- Server returns ISO-8601 UTC; client converts
- Tests: `pytest -q` (api), `pnpm test` (web); both must pass in CI
- Feature flags via `settings.flags`, never env vars read at call sites

## Boundaries
- No PII in logs; `user_id` is fine, email is not
- No direct DB writes from web — all through the API
- No new runtime deps without an entry in decision_log

Stable facts. Edit directly; date nothing here.

Illustrative content for a fictional project. The file names, order and rules are the tool's; the notes are not.

Org memory

One tier up: what holds across repositories.

org-memory/ sits beside projects/. Three curated files carry shared context; events/ and debriefs/ hold records.

Most notes belong to a project. Use org memory only across repositories.

recent.md
Rolling context. Listed by startup for every project.
decisions.md
Decisions that span repositories.
rules.md
Standing rules every project inherits.
events/
Timestamped records. Excluded from startup and recall.
debriefs/
Session summaries published by debrief write. Immutable, never replaced.
~/agent-memorythe home
org-memory/
├── recent.md              curated · listed every session
├── decisions.md           curated · listed every session
├── rules.md               curated · listed every session
├── events/                records · never loaded
└── debriefs/              records · debrief write publishes here
projects/
├── my-app/memory/         04 files + archive/
└── api/memory/            04 files + archive/
setup/                     receipts · never synced
keys/                      refused by sync at any depth

Home resolution: --home → AGENT_MEMORY_HOME → OACP_HOME → nearest .agent-memory.json → workspace marker → ~/agent-memory. OACP is not required.

One sessionRECALL · CAPTURE · PUSH

Recall at the start. Capture as you go. Push when you mean it.

setup claude or setup codex installs a SessionStart hook and a memory workflow file, once. From then on the runtime follows this loop.

01 · startup
The hook runs startup --pull. It lists the four project files and three org files with size and mtime. It injects no content.
02 · recall
The workflow tells the agent to run recall: the listed files, in order, cut at 8,000 characters with a notice. Raise --max-chars or read the rest directly.
03 · capture
capture "decision" --why --agent appends one dated entry to decision_log.md, newest first, with provenance. It touches no other file.
04 · wrap up
Update threads and debt. Optionally publish a summary with debrief write: one immutable record, never replaced.
05 · push
Explicit. push --agent codex commits only what the allowlist selects. No push hook is installed.
$ agent-memory capture 'Use SQLite for the cache.' --why 'no daemon' --agent codex
captured: memory/projects/demo/memory/decision_log.md (## 2026-09-07)
- **Use SQLite for the cache.** Why: no daemon (codex, 2026-09-07T01:53:42Z)
$ agent-memory recall --max-chars 850
## 2026-09-07

- **Use SQLite for the cache.** Why: no daemon (codex, 2026-09-07T01:53:42Z)

Scratch run from the README, excerpted; the temp-dir prefix and --home/--project flags omitted. Recall reads a fixed file set. It is not a vector database, a RAG pipeline, or a chat-history store: no embeddings, no similarity queries, no indexing.

Between machines · optional

Plain git. One private remote. Fast-forward only.

Sync makes the home a git repository with an allowlist and a marker. Skip it and memory stays local; nothing else changes.

No merges. Keys and setup receipts stay local. Network verbs time out after 30 seconds.

enable
Makes the home a git repository, writes the allowlist, drops the marker, makes one commit. With --remote, pushes it.
push
Commits only allowlisted paths as a partial commit. Refuses a home that is behind or diverged.
pull
Fast-forwards only when the tree is clean, not ahead, not diverged, and has an upstream.
clone
Brings a memory repository down to a new home.
disable
Removes the marker. The files stay.
# first machine · an empty private remote
$ agent-memory enable --remote git@github.com:YOUR_ORG/agent-memory-store.git
$ agent-memory push --agent codex

# after another machine pushes, with a clean local tree
$ agent-memory pull

# elsewhere · then bind and set up again
$ agent-memory clone <remote-url> --home <local-home>

# where things stand
$ agent-memory status --home memory
home: memory
source: flag
exists: yes
marker: absent
gitignore: canonical
org-memory: present
projects: 1 with a memory dir
sync: not configured

Bind each machine separately; push explicitly. status output is the README's scratch run, verbatim. Needs git 2.25+.

Lineage

Split from OACP. Same layout, its own command.

The memory verbs that lived in oacp memory now ship as agent-memory. OACP keeps the layout spec; the next OACP release removes its memory commands and points here. The loop's step 07, and the debrief in step 05, run on this tool.

OACP
Defines the memory layout. Its own memory verbs move here; the next release references agent-memory instead.
cortex
Retired. Consolidated into agent-memory; its debrief inbox is now debrief write.
memory-lint
Lints what agent-memory writes. doctor points at it when installed; neither one repairs anything.
oacp-skills
The OACP runtime skills. agent-memory installs its own workflow skill per runtime via setup.

Install it. Read what your agent wrote yesterday.

Bind a repository, work a session, open decision_log.md the next day.

uv tool install agent-memory-clipython -m pip install agent-memory-cli
Source on GitHub agent-memory-cli on PyPI

Apache-2.0 · Python 3.10+ · sync needs git 2.25+
the distribution is agent-memory-cli; the command is agent-memory