Unix-for-AI: Why Your AI's Memory Shouldn't Live in Git
This post was drafted with assistance from Gemini, drawing on development logs from January and February sessions.
If you look at my dotfiles, you’ll find a strict separation between code and AI state. This isn’t accidental — it’s a deliberate choice I call “Unix-for-AI.”
The Problem: Context Fragmentation
In most AI-assisted setups, the agent’s memory — task lists, session logs, specs — lives alongside the code in the same Git repository. This creates a problem: AI memory is ephemeral, high-volume, and temporal. It doesn’t belong under the same version control rules as your source code.
When your task tracker is just another markdown file in the Git tree, you end up with noise in your commit history and confusion about what’s “code” versus what’s “agent state.”
The Three Layers
I formalized this separation into three strata:
- Logic (
~/dotfiles/): Where the scripts, kernels, and agent instructions live. Managed by Git. The source of truth for how the system works. - State (
~/soul_registry/): Where tasks, specifications, and session traces live. Project-keyed, outside the Git repository. - The Sync Layer: A synchronization script (
pulse.py) that keeps the local workspace in sync with the global registry.
How It Works
When an agent starts a session in a project folder (e.g., ~/Code/my-project), it checks for a project anchor. Then it looks at the global registry in ~/soul_registry/tasks/my-project/.
The registry-aware kernel performs a “pulse”:
- Harvests any new JSON tasks from the local workspace.
- Pushes them to the global registry.
- Pulls the current state of all other tasks, specs, and session history.
If you switch machines or refresh your environment, your state remains intact because it’s decoupled from the transient project files.
Why This Matters
Because the registry stores every session as a JSON file — capturing reasoning, tool calls, and decisions — I can look back at a session from three months ago without digging through Git commits. I can check the intent delta: what did I plan to do, and what did I actually build?
The filesystem is the interface. The state is transparent, greppable, and mine.