agentmemoryrepo: keeping agent memory in a git repository

A format specification, not a memory server

Agent Memory Repo starts from a simple premise: an agent that forgets everything between sessions has to relearn the same facts every time. The repository's answer is to store what an agent learns as files in a git repository and let each session read and write that repository.

What the repository actually contains is worth stating up front, because the name suggests more than it delivers. The top level holds LICENSE, README.md, SPEC.md, a skills directory and a .devin-plugin directory. There is no server component, no database and no daemon in that list. The project describes itself as the spec for Agent Memory Repo, and it says the spec is also published at cognition.com/agent-memory-repo.

So the deliverable is a format plus a set of instructions for agents to follow. The format specification lives in SPEC.md and covers repository layout, entries, metadata and cross links. The skills directory packages that behaviour for agents that can load a skill, and the .devin-plugin directory packages it for Devin CLI.

The intended user is someone running an agent across many sessions, or several agents in parallel, who wants the accumulated context to be inspectable, greppable and versioned rather than trapped inside a chat interface. The use cases the README lists are personal memory, agent swarms, team memory and multiplayer sessions. In each case the mechanism is the same: a directory of notes, plus git.

The four step memory loop every session follows

The README defines the cycle that makes the system work, and it is the same four steps every time.

1. Clone the latest memory. 2. Grep for what the task needs, or follow links. 3. Update entries as the agent learns, with no human in the loop. 4. Push after every edit.

The interesting steps are the third and the fourth. Updates happen without a human in the loop, meaning the agent is expected to record what it learns during the session without waiting for you to approve each entry. And a push is required after every edit, not at the end of the day. The reason is that the memory is shared state: in the swarm case described in the README, each agent pushes to the same repository and git flags any edits that conflict. If an agent holds unsaved changes, the next session that clones the memory sees stale state.

The second step is where the format pays off. Rather than loading everything into context, the agent greps for what the current task needs, and it follows cross links when the entry it finds points somewhere else. That is the wiki-like behaviour the README describes when it says memories link to each other and the agent treats them like a wiki.

The consequence for a reader evaluating the project is that git is not a packaging detail. It is the concurrency control, the history, and the transport between sessions and between machines.

Installing the skill into Devin CLI, Claude Code or Cursor

Installation happens through the agent's own plugin or skill mechanism, and the README gives a command for each of the two supported routes.

For Devin CLI, run this in your terminal and then start a new Devin session.

devin plugins install AgentMemoryRepo/agentmemoryrepo

For Claude Code, Cursor and other agents that support skills, run this from your project and choose your agent in the installer. This route requires Node.js and Git, and you may need to restart the agent afterwards.

npx skills add AgentMemoryRepo/agentmemoryrepo --skill agent-memory-repo

The Devin path is the more direct one, and the linked installation guide covers the plugin system in detail. The skills path pulls in a Node based installer, which is why the README states the Node.js and Git requirement for that route. Git is not optional for either route in practice, since the memory repo is a git repository and the loop ends with a push.

One detail worth noting: installing the skill does not create a memory repository. The README's next step has the agent create the repo, write the first entry and commit it, which means the memory repository lives wherever the agent decides to put it, and the README tells you to ask for the full path.

The local trial: save a preference, then ask for it again

The README walks through a trial with two sessions. The first session asks the agent to set up a separate local memory repo and save one trial preference.

Use the agent-memory-repo skill to set up a separate local memory repo for this trial. Save this trial preference: I prefer concise bullet-point summaries. Do not configure a remote. Tell me the full path to the memory repo so I can reuse it next session.

The agent creates the repo, saves the entry and commits it. Then you start a new session in the same project on the same machine, paste the path, and ask for the preference back.

Use the agent-memory-repo skill with the memory repo at <paste the full path from the previous session>. What trial preference did I save?

The new session has no chat history with the first one, so the only way it can answer is by reading the repository. That is the point of the exercise, and it is a genuine test of the format rather than a demonstration.

The README is explicit about the constraints of this trial. The memory repo stays local and no remote is configured. For a local trial you need the same machine with persistent storage, and cloud sessions or another machine need a private remote or other persistent storage to carry memory across sessions. The last line of the trial section states what you do not get: automatic startup and scheduled Dreaming are not included, and you invoke the skill when you want to use memory.

MEMORY.md, bullet entries and the [[path]] link syntax

The format is deliberately loose about structure and strict about a few conventions.

Files and folders can be organised however you want. The repository can hold Markdown notes, SQL queries, scripts and other files, and the README gives an example layout with a top level MEMORY.md, notes, a projects folder and a metrics folder.

memory-john/
  MEMORY.md
  team_structure.md
  using_datadog_mcp.md
  projects/
    payments.md
    website.md
  metrics/
    autocomplete_keep_rate.sql

MEMORY.md is the entry point. Agents load it at the start of every session, so the README tells you to keep it short: only what every session needs, plus links to everything else.

# Memory: John

- John leads the product team [source: https://example.com/sessions/100]

## Index
- [[team_structure]]
- [[projects/payments]]
- [[projects/website]]

Inside Markdown notes, an entry is a single bullet line with optional metadata at the end.

- John coordinates the billing launch [source: https://example.com/sessions/101]
- Payments and website share a 2026-10-15 launch deadline [source: https://example.com/sessions/102; added: 2026-09-03]

Metadata uses the form [key: value; key: value] and the keys are open, with source and added recommended. Cross links use [[path]], starting at the memory root, omitting the .md extension for Markdown files but keeping other extensions. The rule behind the links is that information lives in one place and is linked from elsewhere, and links have to be updated when files move.

The end result is a memory store you can read, edit and grep with ordinary tools, which is also what makes the format compatible with a range of agents rather than tied to one runtime.

Dreaming: the periodic agent that consolidates memory

Dreaming is the part of the specification that goes beyond reading and writing during a session. The README describes it as a dedicated agent that runs periodically, with two jobs.

The first is adding new memory: spot patterns across sessions and save them as new entries. The second is cleaning up memory: merge duplicates, remove outdated entries, and check sources to resolve contradictions.

Both jobs are consolidation work, and both are things a session agent is badly placed to do well. A running session sees the current task and the current context, so it can record a fact but has little sense of what has been recorded many times before. The cleanup job in particular needs a wider view, and a source pointer on every entry is what makes contradiction resolution possible at all, since two entries can disagree and only the linked session can settle it.

The catch is in the trial section: automatic startup and scheduled Dreaming are not included. The scheduled Dreaming agent is part of the specification, but a person following the trial steps will not get it running by following them. If periodic consolidation is the reason you want this project, you need to find the scheduling mechanism yourself or run the Dreaming agent yourself on a schedule.

Swarms, teams and the git conflict flag as a feature

The use cases section is where the design earns its keep.

For agent swarms, each agent pushes to the same memory repository, and git flags any edits that conflict. Conflicts are treated as a signal rather than as damage to be papered over, which is a different philosophy from the usual one where a shared agent store is a database with last write wins.

For team memory, the point is sharing knowledge about customers, processes and tools, particularly for teams without a code repository. A lesson from one person's support investigation becomes available to everyone's agents. That is the case where the memory repository stands in for the missing code repository, and where the per entry source metadata becomes an audit trail of where a claim came from.

For multiplayer sessions, memory composes because it is folders. The README's example has Alice start a session with her memory repo cloned onto the machine, then Bob joining and having his repo cloned as well. The agent then reads both MEMORY.md files and follows links as needed. Each repository keeps its own ownership, permissions and history, so a future session can combine them in any mix, and Bob's memory is only cloned if he chooses to share it with the session. When the destination is unclear, the agent asks rather than guessing.

The alternative to this design is a hosted memory service with an API. The difference in approach is the whole article: this spec makes memory files in git, so the memory is readable without any tooling, versioned without a schema, and shared by pushing rather than by calling an endpoint.

Editorial conclusion

Follow the agentmemoryrepo spec if you run several sessions of the same agent and want preferences and project facts to persist in plain Markdown you can read and edit yourself. Do not expect a ready made memory service from it, since the repository holds a spec, a skill and a format rather than a server, and the trial in the README deliberately runs without a remote, without automatic startup and without scheduled Dreaming. Before adopting the format, decide where the memory repo will live, because a session on a cloud machine or a second computer needs a private remote or some other persistent storage, and check that your agent can push on every edit as the loop requires.

Frequently asked questions

Official sources

1. AgentMemoryRepo/agentmemoryrepo on GitHub
2. Issues
3. License: MIT
4. README