How OACP remembers.
Memory in OACP is plain markdown on the filesystem — durable, append-only where it counts, human-readable, git-syncable. Three dimensions cover the shape of multi-agent work: between agents, between projects, between machines.
Between agents, projects, and machines.
Multi-agent work spans three axes. OACP memory is shaped to all three — one file layout, one set of conventions, three places it travels.
Cross-agent
Inside one project, every runtime reads the same four memory files at session start. Claude knows what Codex decided yesterday because they read the same decision_log.md.
Cross-project
Some things belong above any one project — org-wide standing rules, recent events, decisions that span repos. org-memory sits beside the projects directory and is loaded for every session.
Cross-machine
Optional. If you want memory across machines, point $OACP_HOME at a git remote — same conflict semantics, same tools you already know. Skip it and memory stays local.
Project memory · plain markdown.
Inside every project at projects/<name>/memory/. Each file has one job;
together they cover the whole "what does this project know about itself" surface.
Org-memory · above any one project.
Sits at $OACP_HOME/org-memory/, next to projects/. Auto-loaded
at session start for every project — the org-wide context that doesn't belong to any
single repo.
When to put something here
Rule of thumb: if it applies to more than one project, it belongs in org-memory. If it applies to exactly one project, it goes in that project's memory.
Optional. Plain git. One remote.
Cross-machine sync is opt-in. Memory works fine local-only —
$OACP_HOME is just a directory. Turn on sync by pointing it at a git remote,
and the same memory travels with you across laptop, desktop, and CI. No daemon, no sync server, no proprietary protocol.
01 # initialize the remote (laptop · first time)02 $ oacp memory init --remote git@github.com:org/oacp-memory.git0304 # on every other machine05 $ oacp memory clone git@github.com:org/oacp-memory.git0607 # thereafter — automatic on session start & end08 $ oacp memory status # peek at sync state09 $ oacp memory pull # manual fetch10 $ oacp memory push # manual push
Session start · auto-pull
The oacp skill runs git pull --ff-only against the memory remote before reading any files. Your agents always start from the latest state.
Writes go into commits
Memory writes are batched at end-of-session. wrap-up commits them with a structured message, agent name, and session id — so the git log doubles as an audit trail.
Session end · auto-push
oacp memory push is fast-forward only. If the remote moved (another machine, another agent), you get a clean conflict marker in the file and a chance to merge before retry.
No central server
It's git. Use GitHub, GitLab, Gitea, a bare repo over SSH — whatever you already trust. Memory is private by default because the remote is.
When memory is read & written.
Three moments per session. Reads at the front, writes at the back, with one skill that handles each.
Read everything
The oacp skill loads the four project files + all of org-memory before the agent does anything. By the time you prompt, it already knows the project.
▸ skill: oacp reads · 4 project files + org-memory/Append as you go
Decisions are recorded the moment they're made — not at the end. Open threads tick forward with status updates. decision-log is the canonical skill, but agents can edit files directly.
▸ skill: decision-log appends · decision_log · open_threadsWrap-up writes & pushes
wrap-up tidies open_threads,
promotes anything actionable from known_debt, commits the diff, and
pushes to the memory remote. Tomorrow's session picks up where this one stopped.
Not a vector DB. Not RAG. Not your chat history.
OACP memory is deliberately small, deliberately durable, deliberately legible. Here's what it consciously isn't — and what to use instead when you need those things.
✗ Not a vector DB
memoryNo embeddings, no similarity search. Memory is small enough to load whole, every time. If you need similarity over a large corpus, use a vector DB alongside — feed its results into the prompt as context, not as memory.
✗ Not RAG
retrievalNo retrieval step. Every memory file is loaded at session start; nothing is fetched on demand. If you need retrieval over docs, code, or wikis, run a real RAG pipeline — memory is for what the agent decided, not what it has access to.
✗ Not unbounded context
history
Memory isn't a chat log. Session transcripts go in logs/ if you want
them; memory captures only what the agent decided was worth carrying forward.
Keep it short. If a file passes a few hundred lines, it's drifting.
Small rules that keep memory honest.
The protocol won't enforce these — but everything stays useful only if you do.
Decisions are append-only
Never edit a past decision_log entry. If you changed your mind, write a new entry that supersedes it. The history is the value.
Date everything
Every decision and event gets an ISO date. Six months from now, an agent rereading decision_log has to know which choice came first.
Close threads
An open thread that's been silent for two weeks is a lie. Move it to paused with a reason, or resolve it.
Markdown is for humans too
You'll read this file at 11pm trying to remember why retries are at 3 attempts. Write it for that you, not for the agent.
Don't dump session transcripts
If you find yourself pasting a long chat into decision_log, distill it first. Three sentences usually do.
Org-memory is rarer than you think
Most things belong to a project. If it's only true for one repo, write it there — even if you'll need it from another agent.
Init a project. Read what your agent wrote yesterday.
The fastest way to see why this matters: turn it on in a repo, work for a session,
read decision_log.md the next day. It's the difference between starting
from zero every time and resuming where you stopped.