Keeping coding-agent context in a Git repository

Switching coding agents is easy until the new one asks a question you answered yesterday. The source code is still there. The explanation for a decision, the convention you corrected, and the lesson from an earlier failure may be somewhere else entirely.

I work across machines and tools, so that repeated explanation became a workflow problem. I built agent-memory-nest to keep reusable context in a private Git repository that I control. It is an MIT-licensed template and protocol, built around Markdown rather than a running memory service.

Start with what should survive a session

I don't want every conversation loaded into every future task. A transcript mixes useful decisions with abandoned ideas and temporary observations. What I want to preserve is the part another agent can act on: a rule, a reason, a project decision, or a lesson with enough context to apply it correctly.

That distinction also matters when migrating existing tool memory. Connecting a tool to the nest does not automatically import its native memory. Useful entries need to be selected and reviewed. The carryover format records the source, original project directory, migration date, and the explanation of why and how to use the note.

Why Git fits this particular job

The thing being synchronized is text with a history. Git gives me a familiar way to inspect changes and find out when a conclusion entered the repository. A private remote provides a meeting point for machines that do not need to connect directly to each other.

There is no daemon, extra port, or memory server to keep online. An offline machine can work from its local copy and synchronize when it reconnects. That also makes the trade-off explicit: another machine cannot read a change that has not reached it yet. Git synchronization is asynchronous.

This isn't an argument that every memory system should use Git. A memory server may offer richer search or automatic capture. I wanted deliberate, readable notes and a transport I already use.

Separate rules from observations

The nest has several kinds of context:

queen/ human-maintained rules and strategy shared/ distilled cross-agent knowledge agents/<host>/<id>/ notes owned by one agent instance projects/ project context workflow/ methods reusable across projects 

There is an explicit priority chain: rules, strategy, shared memory, agent memory, project notes, then workflow notes. When sources conflict, the protocol chooses the higher-priority source rather than asking the model to combine incompatible instructions.

Each agent writes only to its own directory. Shared memory is updated through reviewed distillation. This reduces the need for concurrent edits to the same files, but it does not make conflicts impossible. A conflicting write can still stop synchronization and require a manual merge. These are protocol rules, not operating-system permissions.

Keep startup small

A growing archive should not become a growing startup prompt. Sessions load a small resident layer first, then search headings or keywords and read the history relevant to the task.

In my own measurements, default startup loaded about 1/50 of what full loading would. That is a measurement of context loading in my nest, not a general benchmark for model speed, coding quality, or token savings on every task. A task that needs more history will read more.

The practical benefit is keeping old information available without treating all of it as current instruction. Notes still need dates, sources, and review. Searching a repository does not establish that an old project status remains true today.

Integrate each tool explicitly

Claude Code and Codex need their own entry points. The repository's installers configure those integrations; placing files in a common directory alone is not enough.

Where supported, hooks handle synchronization around work. Claude Code has session-start, write, and end-of-turn hooks. Codex has write and end-of-turn hooks. Other tools may follow startup instructions and synchronize at session end instead. The common protocol does not imply that every tool has the same lifecycle capabilities.

A typical handoff is modest: an agent records a reviewed decision, another machine pulls it, and a different tool reads it when relevant. The second tool gains written context. It does not inherit hidden reasoning, a live terminal, or an exact copy of the previous session.

Ownership needs boundaries

The public repository is a template. Actual memory belongs in a separate private repository. Secrets do not belong there, even if the remote is private. Keep credentials in environment variables or a secret store.

For content that must remain unreadable to the Git host, the project documents optional git-crypt encryption. Encryption protects committed content from the host; agents still work with plaintext locally. It does not protect memory from someone who controls the machine running the agent.

Existing native memories also require care when restoring onto a new machine. Some tools derive memory locations from absolute project paths. Recalculate the destination rather than copying an old path blindly. Restoring into a native memory location is a deliberate manual step.

What this leaves unsolved

There is no GUI, semantic-search server, real-time collaboration service, or additional access-control layer. Git-host permissions determine repository visibility. The setup cannot recover cloud information that was never saved, and it cannot guarantee that an agent follows every instruction perfectly.

I've used it daily since April 2026 across 10 machines, 10 tools, and more than 30 agent instances. That describes my own use, not external adoption. The protocol grew out of that workflow, including the need to keep shared knowledge reviewed and startup context bounded.

If those trade-offs fit how you work, the source and setup instructions are at https://github.com/songth1ef/agent-memory-nest. I'm @songth1ef, the author. I'd especially appreciate feedback on stale-context handling, migration boundaries, and when a simple Git-backed protocol stops being enough.