I Built a Free, Git-Native Memory Layer for AI Agents — Here's Why and How

Source: Dev.to

The Problem I Couldn’t Stop Thinking About

I use AI agents constantly — Claude on Windows, Claude on macOS via Codex, GPT‑4o for a second opinion. Every session, the agent is a stranger. It doesn’t know my preferences, my projects, nothing.

The existing “memory” solutions all had the same issues: paid APIs, data on their servers, single‑model lock‑in. None of it felt right.

Solution: agent‑soul

agent‑soul is a Git‑native memory framework that is:

• Free – no paid APIs or monthly bills
• Private – all data lives in your own GitHub repository
• Model‑agnostic – works with any LLM

Every memory is an append‑only JSON event stored in a private GitHub repository. A Python compiler runs via GitHub Actions on every push, processes those events, and outputs clean Markdown files. At the start of each agent session, the agent reads those files via its system prompt. That’s the entire system.

┌─────────────────────────────────────────────────────────┐
│                    agent-soul repo                      │
│                                                         │
│  sources//YYYY-MM-DD.ndjson   ← append‑only   │
│      event stream (what happened)                       │
│                                                         │
│  canonical/                            ← compiled by CI│
│    profile.md          ← who the user is               │
│    stable-memory.md   ← durable facts                  │
└─────────────────────────────────────────────────────────┘

Adding an Event

python scripts/add_event.py \
  --source windows-claude \
  --kind preference \
  --scope stable \
  --summary "User prefers explicit TypeScript types over inferred generics."

Push the change, and GitHub Actions compiles automatically.

Comparison with Paid Memory APIs

Core Concepts

• Append‑only event sourcing – every memory change is a Git commit, giving a full audit log. You can revert, diff, or grep anything.
• Supersedes field – when facts change, write a new event referencing the old one. The compiler excludes superseded events, preserving history.
• Conflict detection – the compiler uses Jaccard similarity to flag contradictory events. Results are written to canonical/conflicts.md.
• Multi‑agent sync – Claude on Windows and Claude on macOS share the same compiled memory. Any agent that can git pull stays in sync.

Getting Started

1. Fork the repository.
2. Fill in the four persona files (SOUL.md, IDENTITY.md, USER.md, VOICE.md).
3. Enable GitHub Actions in your fork.
4. Paste the session protocol from JOIN.md into your agent’s config file.
5. Push once – Actions will compile the memory. On the next session, your agent will remember you.

Setup takes ~10 minutes.

Contributing

Issues and pull requests are welcome. If you’ve ever wanted your AI agents to actually remember who you are—without paying for it or trusting someone else’s server—give agent‑soul a try.