Skip to main content

Punk Records

CI PyPI Python License: MIT

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.

punk init, track, save, remember and context in a terminal

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-records is 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.

How it compares

  • Committing CLAUDE.md to 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 CLAUDE.md, CLAUDE.local.md, AGENTS.md, AGENT.md, GEMINI.md, napkin.md, CONVENTIONS.md, .cursorrules, .windsurfrules, .clinerules, .goosehints (anywhere in the tree)
.claude/*.md (napkins, commands, agents), .claude/skills/*, .cursor/rules/*, .windsurf/rules/*, .clinerules/*, .roo/rules/*, .kiro/steering/*, .github/copilot-instructions.md, .github/instructions/*.md
Global ($HOME) ~/.claude/CLAUDE.md, ~/.claude/napkin.md, ~/.claude/{commands,agents,skills}/*, ~/.codex/AGENTS.md, ~/.gemini/GEMINI.md, ~/.config/goose/.goosehints

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-records

Quickstart

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 document

Online 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 -> restore

On 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 sync

Projects 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 only

Any 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.

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 -p shows 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 with save --force (local wins) or restore --force (store wins, and your local copy is kept as .punk-bak).
  • Concurrent appends merge. Memory files use git's union merge driver, so when two machines add lines to the same CLAUDE.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 -p shows which machine wrote which.
  • 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 in satellites/<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 scan and punk save warn about them instead.
  • Dotfiles work. For global memories, a link such as ~/.claude/CLAUDE.md -> ~/dotfiles/claude/CLAUDE.md is 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 $HOME are followed, never anything under .git, .ssh, .gnupg, .aws and 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 --redact to store it with secrets replaced, or put punk:allow on a line to mark a false positive.
  • Restricted writes. restore only 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
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

Roadmap

  • Built-in encryption (age) for untrusted remotes
  • punk watch: save automatically when memory files change
  • Semantic 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 -v

See 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.

Metadata

Release files for punk-records 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for punk-records 0.1.0
File Size Uploaded Provenance Actions
punk_records-0.1.0.tar.gz 37.2 kB With provenance Details for punk_records-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for punk-records 0.1.0
File Interpreter ABI Platform Actions
punk_records-0.1.0-py3-none-any.whl Python 3 none any Details for punk_records-0.1.0-py3-none-any.whl

Total release size: 64.5 kB

Release files / punk_records-0.1.0.tar.gz

Download URL punk_records-0.1.0.tar.gz
Size 37.2 kB
Tags Source
SHA-256 checksum
How to use checksums
5c462cd8795866302e2bf20ed337951d967dcdc0967e371e19d7c4776c292026
BLAKE2b-256 checksum
How to use checksums
d8ac3d843d1a463e9d964189cae1534614af32af690f41b887a189fde02a7786
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / punk_records-0.1.0-py3-none-any.whl

Download URL punk_records-0.1.0-py3-none-any.whl
Size 27.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
097f1392e1e8d56e45374fc68c898208cb155476754b00c0c2351456f8f2ef83
BLAKE2b-256 checksum
How to use checksums
990b91521f4260246eb87d36cdd1ff5ca12fdc3b0172b24f164c91874e1932d0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for punk-records 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for punk_records-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page