Git Agent Memory: Version Context Without Losing the Work

Versioning agent memory in Git means writing context to committed files so that every change is reviewed, attributed, and reversible. Each commit records what the agent knew at a point in time, and a bad update can be reverted without losing the surrounding history.

The discipline required is the same as for any committed file: deliberate writes, meaningful commit messages, and a review step before changes land in the main branch. Tools like fenbs keep live tasks, standing decisions, and where the work was left outside the repository, because those things change faster than code and belong in a place where every connected assistant can read them without a Git checkout.

Choosing a file format for agent memory in Git

Markdown files are readable in a code review and produce clean diffs when a single fact changes. They suit memory that people also read: project rules, glossary entries, decision records. The downside is that structured data in Markdown (nested lists, tables) is harder to parse programmatically than JSON or YAML.

YAML and JSON files are easier for an agent to read and write programmatically. They produce noisier diffs when a tool rewrites the file, because a schema change can alter every line. Keep each memory file small and focused on one topic so that a single update does not rewrite most of the file. See what is agent memory for a broader look at storage format tradeoffs.

Structuring memory files for reliable diffs

One file per concern is easier to review than one large file. Separate project rules from session notes, and session notes from extracted facts. When an agent updates only the session notes file, the diff is small and reviewable. When everything is in one file, every update touches the same file and conflicts are harder to resolve.

Name files clearly so a reviewer knows what changed without opening the file: decisions.md, glossary.yaml, session-2026-10-21.md. Timestamp-named session files make it easy to find the most recent session and to archive old ones. Use a consistent key structure within YAML or JSON so the agent can read back a value by a stable key name.

Reviewing and merging memory file changes

Treat memory file updates like any other pull request. The reviewer checks that the new fact is accurate, that the key is named consistently, and that the update does not contradict an existing rule. An agent that updates memory files directly to the main branch bypasses this check. Have the agent write to a branch and open a pull request, or write to a staging area that a person approves before merging.

This review step is especially important for decisions and rules. A fact recorded without review might be wrong; a rule recorded without review might contradict a decision a person already made. The review is the guard that keeps the memory accurate. History in Git records who merged the change and when, which helps trace a bad fact back to its source.

Handling stale facts in a Git memory store

A fact becomes stale when the world changes but the file does not. The file still says the API returns a list; the API now returns a paginated object. The agent reads the old file, acts on the wrong assumption, and produces an incorrect result.

Add a reviewed date to each entry in your memory files. Write a rule that any entry older than a threshold must be verified before being used. When an agent detects a stale entry, it should flag it in a comment or a task rather than quietly discarding or overwriting it, so the discrepancy is visible to a person. For a wider treatment of memory reliability, see agent memory security.

Conflicting updates from parallel sessions

Two agents working in parallel on different branches may each update the same memory file with different values for the same key. When the branches are merged, Git marks this as a conflict. The resolver must read both versions and decide which is correct, or write a merged version that combines both.

Design to reduce conflicts rather than to resolve them well. Keep memory files small and single-purpose. Use append-only files (session logs, event lists) where each agent writes new entries rather than updating shared keys. For shared keys that both agents might update, decide in advance which agent has write authority and make the other one read-only for that key. See agent memory vs context for more on how context scope affects conflicts.

How to do this with fenbs

Use Git for versioned context that belongs with the codebase. Use fenbs for the live work record that needs to be readable by any connected assistant, any person on the team, and any session regardless of which branch is checked out.

1. Create a free account and add your project to fenbs. Record the standing rules in Decisions and rules so every assistant reads them first.
2. Connect your assistant from /integrations. At the start of each session, ask it to read fenbs context before reading any Git memory files.
3. Create a memory/ directory in your repository for versioned context: decisions, glossary, and session summaries.
4. Have the agent write memory updates to a branch and open a pull request for a person to review before merging.
5. Add a reviewed date to each memory entry and flag entries older than your chosen threshold as needing verification.