punk-records
Supports using a Gitea repository as a git remote for syncing memories across machines.
Supports syncing the versioned memory store through a private GitHub repository used as a git remote, including history and merge/conflict handling.
Supports using a GitLab repository as a git remote for syncing memories across machines.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Punk Records
One brain for all your AI agents. Persist every CLAUDE.md, AGENTS.md, napkin, and rules file
from every project and machine in a single versioned store. Sync it over any git remote, or carry it
across an air gap on a USB stick. Agents can read and write it live over MCP.

On Egghead, Dr. Vegapunk keeps one shared brain, the Punk Records. His satellites each go off and learn things, and whatever they learn flows back into that shared brain. This project does the same for your agents: each project and machine is a satellite, and
~/.punk-recordsis the brain.The name is a nod to One Piece (the linked wiki pages contain spoilers). This is a fan-named project, not affiliated with Eiichiro Oda, Shueisha or Toei Animation.
Why
Agent memories are scattered across dozens of repos and dotfiles. Many of them are deliberately
uncommitted (CLAUDE.local.md, napkins, ~/.claude/CLAUDE.md). They get lost when you wipe a
laptop, they diverge between your work and home machines, and they can't follow you into an
offline network.
Related MCP server: Session Memory
How it compares
Committing
CLAUDE.mdto each repo. Keep doing it for conventions your team shares. It does not cover the memories you keep out of git on purpose (CLAUDE.local.md, napkins,~/.claude), notes you would rather not push to a team repo, or a machine that cannot reach the repo host. Punk Records stores those too, alongside the committed ones.Dotfiles managers (chezmoi, yadm, GNU Stow). They are built for files at fixed paths in your home directory. Most agent memories live inside project checkouts, at different paths on each machine. Punk Records finds them by itself, matches checkouts by their git remote, merges edits made on two machines, scans for secrets before storing, and serves everything to agents over MCP. The two work together: a global memory that is a symlink into your dotfiles repo is followed (see below).
What it picks up
Scope | Files |
Any project |
|
| |
Global ( |
|
Run punk scan to see what would be captured. To add your own patterns, put globs in punk.json
inside the store ({"include": ["docs/ai/*.md"], "exclude": []}).
Install
Requires Python 3.9+ and git. No other dependencies.
pipx install punk-records # or: pip install punk-recordsQuickstart
punk init # creates ~/.punk-records and tracks your global memories
punk track ~/code/app ~/code/api
punk save # snapshot every memory file into the store
punk context ~/code/app # everything an agent should know there, as one documentOnline sync (any git host)
Create a private repo (GitHub, GitLab, Gitea, a bare repo on your NAS, anything git can reach):
punk git remote add origin git@github.com:you/my-punk-records.git
punk sync # save -> pull -> push -> restoreOn another machine:
punk init git@github.com:you/my-punk-records.git
punk track ~/src/app # matched to the same records through the project's git remote
punk syncProjects get their identity from their git remote (github.com/you/app), so the same repo checked out
at different paths on different machines shares one set of memories. Projects without a remote get
local/<dirname>; you can override it with punk track --id.
Air-gapped sync
punk export /media/usb/records.bundle # on the connected side
punk import /media/usb/records.bundle # on the air-gapped side (and back again)A bundle is a standard git bundle file. It carries full history and can be verified on arrival, and
imports merge the same way online pulls do.
Let agents use it live (MCP)
There is no server to keep running. Your agent starts punk mcp when a session begins and talks to
it over stdin/stdout. Run punk init once first, then register it:
claude mcp add --scope user punk-records -- punk mcp # all projects; without --scope: this project onlyAny MCP client works the same way ("command": "punk", "args": ["mcp"]). If the client cannot find
punk, give it the full path from which punk. Tools offered:
get_context, search_memories, read_memory, list_memories, list_satellites,
append_memory (writes to the store, commits, and updates the local file), and sync.
Sync automatically with Claude Code
punk install-hooks # all projects (~/.claude/settings.json)
punk install-hooks --project # only this project (.claude/settings.local.json)This adds two Claude Code hooks: when a session starts, punk
restores your global memories and the current project's (pulling first when a remote is set); when
it ends, punk saves them and syncs. Nothing is printed into the conversation unless something needs
your attention, such as a conflict or a blocked secret. Your other settings and hooks are left alone,
the previous file is kept as .punk-bak, and punk install-hooks --uninstall removes only punk's
entries. Only tracked projects are synced.
From the shell: punk remember "- integration tests need docker running" appends to the current
project's CLAUDE.md (use -f .claude/napkin.md to target another file).
How sync works
The store is a git repo. Every save is a commit, so
punk git log -pshows how your agents' knowledge changed over time, and nothing is ever truly lost.Three-way per file. Punk records the local and store hash of each file at its last sync, which lets it tell "edited here" apart from "edited on another machine". When both sides changed, it reports a conflict and leaves both copies alone.
punk diff <satellite> <path>shows what differs (-store,+local). You resolve it withsave --force(local wins) orrestore --force(store wins, and your local copy is kept as.punk-bak).Concurrent appends merge. Memory files use git's
unionmerge driver, so when two machines add lines to the sameCLAUDE.md, the result contains both sets of lines. The catch: if both machines change the same line, the merged file keeps both versions, one after the other. Nothing is lost, but read the file after such a sync and delete the line you no longer want;punk git log -pshows which machine wrote which. When two machines add the same line in different places, both copies stay;punk dedupelists them andpunk dedupe --applykeeps only the first (blank lines, code blocks, indented lines and headings are never touched).Deletes propagate on save. Locally removing a file that was synced removes it from the store. Deletions coming from the store are only reported, unless you pass
restore --prune.Symlinked memories are kept as links. If
AGENTS.md -> CLAUDE.md, the content is stored once and the link is recorded insatellites/<id>.json, then recreated on other machines. Only links that resolve to a memory file inside the same project are recorded. Links that point outside the project are never followed.punk scanandpunk savewarn about them instead.Dotfiles work. For global memories, a link such as
~/.claude/CLAUDE.md -> ~/dotfiles/claude/CLAUDE.mdis followed: the content is stored, and restores write through the link into your dotfiles repo. Only non-executable Markdown/text files (or files with the same name as the link) inside$HOMEare followed, never anything under.git,.ssh,.gnupg,.awsand similar.
Safety
Secret scanning. Before a file enters the store it is checked for API keys (Anthropic, OpenAI, AWS, GitHub, Slack, Google, Stripe), private keys, and
password=...-style assignments. A matching file is blocked by default. You can pass--redactto store it with secrets replaced, or putpunk:allowon a line to mark a false positive.Restricted writes.
restoreonly writes paths that match the memory patterns. It never writes into.git/, outside the project, through.., or through an existing symlink. Recreated symlinks must point from one memory path to another inside the project, so a tampered store or bundle can't plant hooks or scripts in your repos.Keep the remote private. Memories describe your code and habits. If you need encryption at rest on a third-party host, git-crypt works transparently on the store repo.
Commands
init [URL] create a store, or clone an existing one
track [DIR...] start persisting a project untrack ID [--purge]
list | scan what is tracked / what would be captured
save | restore store <-> local projects (--dry-run, --force)
status what save/restore would do
diff [ID] [PATH] unified diff of local memories vs the store
dedupe [ID] [PATH] duplicate lines left by merges (--apply removes them)
sync save, pull/push remote, restore
export | import air-gapped bundle files
search | show | context | remember
git ... run git inside the store
mcp MCP server on stdio
install-hooks sync automatically when Claude Code sessions start and endRoadmap
Built-in encryption (age) for untrusted remotes
punk watch: save automatically when memory files changeSemantic search and deduplication across projects
Shared "team brain" satellites that you can subscribe to read-only
Small web UI for browsing memory history
Development
python -m unittest discover -s tests -vSee CONTRIBUTING.md for the rules (no runtime dependencies, Python 3.9 syntax, tests for every change). Report security problems privately as described in SECURITY.md.
MIT licensed.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Project memory, documentation and controlled secret access for AI coding agents.
Persistent docs and memory for AI agents — read, write, organize & search a shared workspace.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides persistent memory and semantic file discovery for AI coding agents, enabling them to remember changes and find relevant files across sessions.5MIT
- AlicenseBqualityDmaintenanceProvides persistent local memory for AI coding sessions, enabling agents to save and retrieve project context across different tools and sessions.16MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP-speaking agents to read and write a local, portable, JSONL-based long-term memory, so context and durable facts persist across sessions through search, context injection, and memory lifecycle tools.2MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI coding agents to share persistent project memory across sessions and worktrees through content-hash file summaries, symbol lookup, bounded reads, notes, handoffs, claims, and agent messaging.451 PyPIMIT