Growth-Kinetics/DiffMem

DiffMem – Git‑based differential memory for AI agents

What it is – DiffMem is a lightweight, production‑ready service that lets an LLM‑powered conversational agent keep a versioned personal knowledge base. Instead of a vector store or a custom graph DB, it stores the current “facts” in plain‑text Markdown files and relies on Git to record every change. A retrieval agent can run ordinary shell tools (git log, git diff, grep, …) to fetch the latest view or dive into the history for temporal reasoning.

Why it matters – Long‑running agents (e.g., a chatbot that talks to the same user for months or years) need a memory that:

stays human‑readable and easy to back up,
lets you ask how something changed over time, and
avoids loading gigabytes of old data into the LLM context window. By separating the surface (the current Markdown files) from the depth (Git history), DiffMem keeps the prompt size small while still offering rich auditability.

Core components

Component	Role
Writer agent (`writer_agent`)	Parses a conversation transcript, extracts or creates entities, writes updates to the Markdown files, and makes an atomic Git commit.
Retrieval agent (`retrieval_agent`)	A single‑tool LLM that runs sandboxed shell commands against the repo to locate relevant sections, diffs, or commit logs, then returns a structured retrieval plan that becomes the LLM context.
FastAPI service (`api.py` / `server.py`)	HTTP endpoints for onboarding users, ingesting sessions, and fetching context. Also importable as a Python library (`DiffMemory`).
Storage backend	Local disk by default; holds a central Git repo and per‑user worktrees (each user lives on an isolated orphan branch).
Backup backend (optional)	Mirrors each user branch to a private GitHub repo (`none` or `github`). Backups run asynchronously and do not block request handling.
Task executor	`inline` (default thread‑pool) or `hatchet` (durable, observable background workers).

How it works (high‑level flow)

Onboard – POST /memory/{user_id}/onboard creates an orphan branch for the user and a fresh worktree.
Ingest – POST /memory/{user_id}/process-and-commit sends a conversation transcript. The writer agent extracts entities, writes/updates Markdown files, and commits them.
Retrieve – POST /memory/{user_id}/context asks a question. The retrieval agent runs git log, git diff, grep, etc., builds a list of file sections and diffs, and feeds that into the LLM as context.
Consolidate (optional) – Periodic /consolidate runs tools that de‑duplicate entities, redistribute oversized files, and add wikilinks, keeping the “current‑state” tidy.

Deployment options

Option	What you need	Key steps
One‑click with Coolify	Docker‑enabled VPS, Coolify instance	Add a Docker‑Compose resource pointing at `https://github.com/Growth-Kinetics/DiffMem`, set `OPENROUTER_API_KEY`, deploy.
Hatchet‑backed production	Hetzner (or similar) VM, Hatchet Cloud account	Use `deploy/docker-compose.hatchet.yml`; runs an API container and a Hatchet worker for durable task execution.
Plain Docker Compose	Any Linux box with Docker	`git clone … && cp .env.example .env && docker compose up -d`. The service listens on `PORT` (default 8000).
Python library	Python 3.11+, `openrouter` API key	`from diffmem import DiffMemory; mem = DiffMemory(path, user, key); mem.process_and_commit_session(...); ctx = mem.get_context(...)`.

All deployments store state in a named Docker volume (diffmem_data) that can be backed up with a simple tar command.

Key features

Git‑native versioning – every memory change is a Git commit; you can query git log or git diff to see how a fact evolved.
Markdown storage – human‑readable, easy to edit manually, works with tools like Obsidian.
Per‑user isolation – each user lives on an orphan branch with its own worktree; no cross‑user data leakage.
No embeddings / vector DB – retrieval is pure text/regex + Git history, dramatically reducing token usage.
Pluggable ontologies – built‑in personal and corporate schemas; custom schemas can be dropped into ontologies/.
Optional GitHub backup – off‑site mirror for disaster recovery, completely asynchronous.
Consolidation tools – dedupe, redistribute, link, and a migration‑only reabsorb tool to keep the current‑state compact and well‑linked.
Configurable executor – run synchronously (inline) for simple setups or use Hatchet for durable, observable background jobs.

Typical use case (example)

A user “Alex” chats with a virtual assistant on WhatsApp.
After each conversation the assistant calls POST /memory/alex/process-and-commit with the transcript.
The writer agent creates/updates memories/people/mom.md, adds a line to timeline/2024-09.md, and commits.
Later Alex asks, “What did Mom say about her new job?” – the retrieval agent runs git grep "Mom" and git log -p to pull the latest fact plus any recent changes, then supplies that as context to the LLM, which answers accurately.
A nightly job calls /memory/alex/consolidate to merge duplicate entries and insert wikilinks, keeping the memory tidy.

Limitations (as documented)

Write operations can be slow (≈1–10 minutes) because they involve LLM calls and Git I/O. Use ?sync=false to get an async job ID.
Retrieval quality depends on the underlying LLM; GPT‑4o‑class models give noticeably better entity linking.
The system is I/O‑bound; a small VPS (1 vCPU, modest SSD) is sufficient for thousands of users, but heavy write traffic may need larger storage throughput.

Who might want this?

Developers of long‑term chatbots who need persistent, auditable user memories without a heavyweight vector store.
Researchers exploring temporal reasoning in LLM agents (e.g., “how did my relationship with X change over the past year?”).
Teams that value data portability – the memory is just a Git repo; you can clone, diff, or archive it with standard tools.
Self‑hosters who prefer an open‑source stack with minimal external services (only an LLM API key is required).

Quick start (Docker)

git clone https://github.com/Growth-Kinetics/DiffMem.git
cd DiffMem
cp .env.example .env   # edit to add your OpenRouter API key
docker compose up -d   # service runs on http://localhost:8000

Then call the API (or use the provided Python wrapper) to create a user, ingest sessions, and retrieve context.

License & status

License: MIT
Current version: 0.5.0 (production‑grade, used in the Annabelle chatbot)
Roadmap: improve indexing, add context caps, support visual retrieval, PDF export, and linked‑entity wikification.

Bottom line: DiffMem demonstrates that a conventional version‑control system can serve as a fast, transparent, and durable memory layer for AI agents, giving developers a simple alternative to vector databases while retaining full auditability and human editability.