How to set up shared memory across AI coding agents

Shared memory across AI coding agents means one set of plain markdown files that every agent reads at the start of a session and writes to whenever it learns something worth keeping. Part of that is already solved for free by a shared convention called AGENTS.md. The rest you assemble yourself: keep the canonical copy in a folder you own, generate each remaining tool’s file from it, and give every agent one place to append what it learns.

The work splits into two jobs. The first is standing instructions: the house rules, the stack, the conventions you would tell any new contributor. The second is the accumulated record: the decisions you made, the facts you established, the follow-ups still open.

Instructions belong in each tool’s expected file. The record belongs in many small notes an agent queries on demand, because pasting a year of decisions into every prompt costs money and buries the three lines that mattered.

What AGENTS.md already covers

AGENTS.md is a deliberate cross-tool convention, not one vendor’s private filename. Codex reads it, GitHub Copilot’s coding agent reads it, and editors including Cursor and Zed read it too. Gemini CLI can be pointed at it by setting contextFileName in its settings file. If you want one memory for Claude Code, Codex, and Gemini CLI, that convention gets you most of the instruction half before you write any tooling.

Claude Code reads its own file. Here is what each tool looks for in a repository:

Agent	Instruction file
Claude Code	CLAUDE.md
Codex	AGENTS.md
Gemini CLI	GEMINI.md, or AGENTS.md via contextFileName
GitHub Copilot	.github/copilot-instructions.md

Each also reads a user-level file in its own config directory, for rules that apply to every project.

Where one shared file stops helping

Three gaps remain. A single file carries no accumulated record, so every decision you want remembered gets pasted back in by hand until the file is too long to read. Every tool receives byte-identical content, so tool-specific material has nowhere to live: a Claude Code skill means nothing to Copilot. And agents edit these files themselves, so the copies drift and nothing tells you which one changed.

The five-minute version

On one machine, write the canonical file once and link each tool’s filename at it.

mkdir -p ~/agent-memory
cat > ~/agent-memory/instructions.md <<'EOF'
# House rules
Run `make test` before every commit. Never edit files under `vendor/`.
EOF
ln -s ~/agent-memory/instructions.md ./AGENTS.md
ln -s ~/agent-memory/instructions.md ./CLAUDE.md

On Windows the equivalent is mklink CLAUDE.md %USERPROFILE%\agent-memory\instructions.md. Watch the argument order: mklink takes the link name first and the target second, the reverse of ln -s. Creating a file symlink also needs Developer Mode turned on or an elevated prompt.

Symlinks fail in two ways worth knowing before you rely on them. An agent that saves atomically writes a temporary file and renames it over CLAUDE.md, which replaces your symlink with an ordinary file and quietly ends the sharing. A symlink committed to git also breaks for collaborators who clone on Windows without Developer Mode.

Copy and reconcile instead

The sturdier shape is a canonical folder plus a step that copies content out to each tool. The shortest honest version is a few lines of shell you run yourself:

#!/bin/sh
src=~/agent-memory/instructions.md
for dest in CLAUDE.md AGENTS.md GEMINI.md .github/copilot-instructions.md; do
  cp "$src" "$dest"
done

That costs you something. It is one-way, so anything an agent appends to CLAUDE.md is overwritten on the next run, and it says nothing when both sides changed.

A dotfile manager such as chezmoi adds templating and multi-machine handling. Git on the folder gives you diffs, blame, and review before a new rule reaches your agents.

One canonical folder, synced out to each tool

Adam Richardson built Jotura as a private, fast markdown notes app for his own notes, and the agent commands came later on top of it. It ships a first-party command line tool called jotura that reconciles agent config. Install the app, the CLI, and the agent skills in one step:

curl -fsSL jotura.io/install.sh | bash
# Windows PowerShell: irm jotura.io/install.ps1 | iex

Your notes live in an ordinary folder of .md files, and an Agents/ folder inside it holds the instruction files, skills, and subagent definitions. You edit the vault copy, then apply it outward:

jotura agents status          # read-only drift report, always exits 0
jotura agents sync --dry-run  # print the planned actions, write nothing
jotura agents sync            # pull system changes in, push vault changes out

The sync runs in both directions: it pulls edits an agent made to its own file back into the vault, and applies your vault edits outward. When a file changed on both sides, the sync skips it rather than overwriting silently, and exits with code 16. You resolve it with jotura agents sync --prefer vault or --prefer system.

To wire up a single tool from scratch, jotura skill install accepts claude, codex, gemini, or all. Copilot has no skill format, so jotura agents sync handles its instruction file instead.

A shared record every agent can query

The changing half is what your agents learn while working.

jotura memory log --kind decision \
  --title "Postgres for the job queue, not Redis" \
  --project "billing-api" \
  --body "Redis dropped jobs on restart. SKIP LOCKED is fast enough at our volume."

You get three kinds. A decision records a choice and the reason behind it. A fact records something established about the system that will not change soon. A followup records something still open, so you can close it later rather than rediscovering it.

jotura memory recall "job queue"
jotura context "add retries to the billing worker"

recall ranks results by relevance, freshness, and importance, so last week’s decision outranks last year’s. context takes the task you are about to start and returns the memories that bear on it, which is the call to make at the top of a session. When a decision gets reversed, jotura memory supersede <old> --by <new> links the two so the old one stops surfacing as current advice.

Every note is a plain file, so grep or any editor reads them too.

Keeping the folder on more than one machine

One folder solves one machine. A laptop and a desktop need that folder in the same state on both.

Git is the strongest free answer: real diffs on every memory note, blame, a branch per experiment, and review before a rule reaches your agents. Syncthing wins on invisibility, but it writes conflict-copy files instead of merging, and both machines need to be online in the same window.

Jotura Sync is the paid option at 4 pounds a month or 40 pounds a year, with no free trial. It is end-to-end encrypted, so the server never sees your file contents, your paths, or your keys.

A longer multi-machine walkthrough lives in sync agent config across computers.

What cross-agent memory cannot do

It does not let two agents see each other’s live conversation, and there is no shared runtime context. An agent only knows what somebody wrote down before it started, so the write step is the whole system. If your agents never log anything, you have a synced folder and no memory.

Retrieval is not free either. Every memory you surface costs prompt space, which is why querying by task beats loading the whole store. Cross-agent memory also cannot rescue vague instructions: four agents reading the same unclear rule will misread it four different ways.

Two more limits are worth naming plainly. Jotura is closed source, so if an auditable codebase is a requirement, a git repository of markdown plus the script above is the honest alternative and it costs nothing. There is also no iOS app, so an iPhone is not part of this loop.

Common questions

Can two agents write to the same note at once? Read the note first to get its current hash, then pass --if-hash <hash> on the edit. If the file changed underneath you, the CLI refuses the write with exit code 2. Re-read the note, reapply your change to the new content, and retry with the new hash.

Do I need the paid sync for this? No. Everything above works on one machine with no account and no subscription. Sync matters only once the folder has to exist on more than one computer.

Why markdown rather than a vector database? For a store measured in hundreds of notes, files you can read and correct by hand are usually the better trade. That question gets a full answer in vector database versus markdown for agent memory.

The CLI reference covers every subcommand and exit code.