Persistent Agent Memory

Giving Claude Cross-Machine Context with Symlinks and Git

Introduction

A coding agent like Claude starts every session blank. It doesn’t remember what you told it yesterday, what you decided three sessions ago, or which conventions you’ve already corrected it on twice. This guide is about fixing that: giving the agent a persistent memory that survives across sessions, repos, and stays in sync across every machine you work on, so the agent you talk to on the laptop already knows what the agent on the Pi learned.

The mechanism is simpler than it sounds. It’s a folder of plain Markdown files, a symlink so the agent finds that folder where it expects to, and the same git spine the rest of my vault already rides.

This is the in-depth companion to the cross-device vault how-to, which is the one-vault, one-git-spine model this builds on. To get the most out of this, you should be familiar with git and Linux. If you aren’t, you can start with my Raspberry Pi Ubuntu Server guide for a full walkthrough of my server configuration including networking and security.

Guide Outline

1. Introduction — Agent memory and why it needs to be both persistent and synced.

2. Key Terms — Crucial concepts to get the most out of this guide.

3. Symlinks — The enabling idea, taught from scratch.

4. The Memory Store — Where the agent reads and writes memories.

5. Wiring a Store to a Machine — Symlinks plus the per-machine keys.

6. Keeping Machines in Sync — Using two basic git hooks.

7. Where the Pieces Connect — what governs writing memory (and what comes next).

Key Terms

• Symlink (symbolic link): A filesystem entry that points at another path, so opening the link transparently opens the target.

• Agent memory: A folder of Markdown files the agent reads at the start of a session and appends to as it learns. Persistent, human-readable, and version-controlled.

• Memory store: The single, git-tracked home for those files inside the vault (claude/memory/), with one subfolder per project.

• Project key: The per-machine identifier the agent derives from the working directory to decide where on disk to look for a project’s memory.

• Hook: A command the agent runs automatically on an event — here, at session start and session end — to pull and push memory over git.

Symlinks

Everything here hinges on the symlink, so it’s worth understanding before we use it.

A symlink is a tiny file whose entire contents are “I am really pointing at that path over there.” When a program opens the symlink, the operating system quietly redirects to the target — the program never has to know it was redirected. You can think of it as a forwarding address: mail sent to the old address still reaches you, because the post office rewrites the destination on the way.

You create one with ln -s <target> <link> — read it as “make <link> point at <target>“:

# Make ~/notes point at a folder that actually lives elsewhere
ln -s ~/vault/notes ~/notes

# Now these open the same files:
ls ~/notes
ls ~/vault/notes

A few properties that matter for what follows:

• The target and the link can live in completely different places. The link is just a pointer; the real files sit wherever the target says. This is the whole trick — the agent can look in one place while the files live somewhere git-controlled.

• It’s a soft link, not a copy. Edit the file through either path and you’re editing the one real file. There’s no second copy to drift out of sync.

• A dangling link is possible. If the target moves or doesn’t exist, the link points at nothing and opening it fails. So a symlink-based setup has one rebuild step per machine: re-create the link if it’s missing.

Note

A symlink differs from a hard link: a hard link is a second name for the same underlying file data, can’t cross filesystems, and can’t point at a directory. We want a soft link precisely because we’re pointing at a directory on a path that varies per machine — the soft link’s flexibility is the feature.

The Memory Store

The memory itself is deliberately boring: a folder of Markdown files. Inside the vault it lives at claude/memory/, with one subfolder per project:

~/vault/claude/memory/
├── MEMORY.md              # index — one line per memory, loaded every session
├── <project-a>/
│   └── ...memory files
└── <project-b>/
    └── ...memory files

Each file holds one fact — a preference, a piece of feedback, a project constraint — with a little frontmatter so the agent can judge relevance. Because they’re plain Markdown inside the vault, they ride the same git spine as everything else (see the cross-device vault guide): tracked, versioned, and synced for free. The vault root is itself a project the agent works in, so it gets its own store at claude/memory/vault/ alongside the per-project ones.

The catch is that the agent doesn’t look here for memory. It looks under its own config directory, at a per-machine path it derives itself. Bridging that gap is the symlink’s job.

Wiring a Store to a Machine

The agent expects a project’s memory at:

~/.claude/projects/<key>/memory

…where <key> is derived from the project’s working-directory path, with /, _, and . all replaced by -. So the same project resolves to a different key on each machine, because the absolute path differs:

# Same project, two machines, two keys:
/Users/myUserName/vault/projects/foo   →   -Users-myUserName-vault-projects-foo
/home/myUserName/vault/projects/foo    →   -home-myUserName-vault-projects-foo

If we stored memory at that path directly, each machine would have its own separate pile and they’d never sync. Instead, we symlink that per-machine path at the one git-tracked store, keyed by the project’s directory name (foo), which is identical everywhere:

repo=foo                                   # the project's directory name
mkdir -p ~/vault/claude/memory/"$repo"     # the real, git-tracked store

cd ~/vault/projects/"$repo"
key=$(printf '%s' "$PWD" | sed 's#[/_.]#-#g')   # derive this machine's key

mkdir -p ~/.claude/projects/"$key"
ln -s ~/vault/claude/memory/"$repo" ~/.claude/projects/"$key"/memory

Now the agent, looking up its per-machine <key> path, is transparently redirected to ~/vault/claude/memory/foo — the same git-tracked folder on every machine. Two different keys, one real store. The directory name is the anchor; the path-derived key is just how each machine finds its way back to it.

Tip

That . in the substitution matters. A project directory like myUserName.github.io has to become -myUserName-github-io for the key to resolve — miss the dot and the link points at the wrong place.

The vault’s own store wires up the same way, keyed off the vault root instead of a project subfolder. The one rebuild reminder from section 3 applies here: the symlink is an untracked, per-machine artifact, so a fresh clone on a new machine needs this wiring step re-run — the files arrive with the clone, but the link that points the agent at them does not.

Keeping Machines in Sync

Symlinking the store into the vault means memory now travels on the git spine — but only if something actually commits and pushes it. Two hooks handle that automatically, so memory syncs without you ever thinking about it:

• SessionStart — pull. At the start of every session, the hook runs a git pull on the vault, so you begin with the latest memory from whatever machine you last used.

• Stop — push. When a session ends, the hook stages claude/, commits, does a rebase-pull to absorb anything the other machine pushed in the meantime, then pushes. It’s conflict-safe and a no-op when nothing changed.

The Stop push carries its own rebase-pull, so it’s safe even on its own; the SessionStart pull is just the freshen-on-open convenience layered on top. Together they mean every session that teaches the agent something publishes it, and every session starts current.

The reason both machines run both hooks comes down to one more symlink. The live agent config (~/.claude/settings.json) where these hooks are declared is itself a symlink pointing at a single shared file in version control. Edit that one shared file and the change is instantly live on every machine — no copying, no drift. (Same forwarding-address trick as section 3, applied to the config instead of the memory.)

This is also why memory is the one thing in the vault you don’t hand-commit: the Stop hook owns those commits, so letting it do its job is what keeps the machines from fighting over claude/.

Where the Pieces Connect

What we’ve built is the plumbing: where memory lives, how each machine finds it, and how it syncs. What I haven’t gone into yet, and I’ll include in future guides:

• What decides when and what to write to memory — the conventions for triaging a session into durable facts.

• Why the live config is symlinked rather than copied.

To recap, think of agent context as including a folder of Markdown, a symlink so the agent finds it, and the git spine to move it around.