Giving a coding agent a memory

Every Claude Code session starts blank. You open a project and the agent has no idea what you decided last week, which branch is live, or why a file looks the way it does. So you re-explain. Ariadne is the tool I built to stop re-explaining.

It has two moving parts. On the hot path, two hooks: one captures a session when it ends, one recalls the right context when the next one starts. Between sessions, a librarian I run by hand distils the raw logs into something durable.

Capture and recall

The end-of-session hook writes down what happened: repo, branch, which machine I was on, the subject lines of recent commits, how many files were dirty. It never reads file contents or the transcript, only the shape of the work. That record goes into a plain-markdown vault, plus a one-line entry in a monthly log.

The start-of-session hook does the reverse. It finds the current project’s page, reads its status, next steps, and recent activity, and drops that into the new session before I type anything. The thread is already in my hand when I sit down.

The librarian

Capture is fast and a little dumb on purpose. It runs on every session and can’t afford to stop and think. The distilling happens later, in a separate pass I trigger with /ariadne consolidate. That pass reads the episodic log and turns it into durable memory: refreshed project pages, a next-step list that reflects reality, notes that survive past the session that produced them. Write fast during the work, reflect once it’s done.

That split is borrowed from how agent-memory systems tend to work, scaled down to a pile of files. The monthly log is the episodic layer: machine-written and append-only. The project pages and notes are the semantic layer, the knowledge worth keeping. The conventions file the agent reads first is the procedural layer, the house rules of the vault.

Two decisions I’d defend

The first was deciding what the vault is even allowed to hold. Metadata only, and a firm line between work and personal. Any repo whose remote matches a work pattern gets written to a gitignored folder that never syncs, so the shared vault carries my own projects and nothing from a client. The good part is that the line is auditable: I can open that directory and see exactly what has crossed it.

Splitting the engine from the vault was the other one. The engine is a small set of Node scripts with no dependencies and no user data anywhere in it. The memory itself lives in a separate private git repo, plain markdown, readable in any editor. So if Ariadne breaks tomorrow, the notes are still sitting there in a form I can read without it. A second brain I own rather than a feature I rent.

Why markdown, why git

The zero-dependency rule was a deliberate constraint. Node standard library only, nothing to npm install, no lockfile, nothing to update or audit. It installs the same on any machine with a recent Node, and I can read the whole engine in an afternoon.

Git does the syncing. The same vault lives on every machine I work on, and the log files use a union merge so captures from two machines never fight over the same line. Each entry is tagged with the hostname that wrote it, so I can see which machine I was on when a decision got made. No cloud account, no API key, no monthly bill for the privilege of remembering my own work.