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.
So I built agent-soul: a Git-native memory framework. Free. Private. Works with any LLM.
The Architecture in One Paragraph
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/<agent-id>/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 │
└─────────────────────────────────────────────────────────┘
No database. No API key. No monthly bill.
Adding a Memory Event
python scripts/add_event.py \
--source windows-claude \
--kind preference \
--scope stable \
--summary "User prefers explicit TypeScript types over inferred generics."
Push, and GitHub Actions compiles automatically.
Why Git Instead of a Vector DB
| agent-soul | Paid memory APIs | Custom RAG | |
|---|---|---|---|
| Cost | Free | Monthly fee | Dev time + infra |
| Data ownership | Your private repo | Their servers | Yours (complex) |
| Cross-agent sync | Native | No | No |
| Offline support | Yes | No | Partial |
| Audit log | git log | No | No |
Key Design Decisions
Append-only event sourcing — every memory change is a git commit. Full audit log. You can revert, diff, grep everything.
supersedes field — when facts change, write a new event referencing the old one. The compiler excludes superseded events. History is never destroyed.
Conflict detection — the compiler uses Jaccard similarity to flag when two events about the same topic contradict each other. Results go 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
- Fork the repo → https://github.com/kingcharleslzy-ai/agent-soul
- Fill in the four persona files (SOUL.md, IDENTITY.md, USER.md, VOICE.md)
- Enable GitHub Actions in your fork
- Paste the session protocol from JOIN.md into your agent's config file
Setup takes ~10 minutes. On next push, Actions compiles. On next session, your agent remembers.
Issues and PRs 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 it a try.
Top comments (0)