punk-records 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- punk_records-0.1.0/LICENSE +21 -0
- punk_records-0.1.0/PKG-INFO +218 -0
- punk_records-0.1.0/README.md +192 -0
- punk_records-0.1.0/pyproject.toml +50 -0
- punk_records-0.1.0/setup.cfg +4 -0
- punk_records-0.1.0/src/punk_records/__init__.py +3 -0
- punk_records-0.1.0/src/punk_records/__main__.py +3 -0
- punk_records-0.1.0/src/punk_records/cli.py +302 -0
- punk_records-0.1.0/src/punk_records/discover.py +221 -0
- punk_records-0.1.0/src/punk_records/mcp.py +145 -0
- punk_records-0.1.0/src/punk_records/secrets.py +57 -0
- punk_records-0.1.0/src/punk_records/store.py +819 -0
- punk_records-0.1.0/src/punk_records.egg-info/PKG-INFO +218 -0
- punk_records-0.1.0/src/punk_records.egg-info/SOURCES.txt +16 -0
- punk_records-0.1.0/src/punk_records.egg-info/dependency_links.txt +1 -0
- punk_records-0.1.0/src/punk_records.egg-info/entry_points.txt +2 -0
- punk_records-0.1.0/src/punk_records.egg-info/top_level.txt +1 -0
- punk_records-0.1.0/tests/test_punk.py +813 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Punk Records contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: punk-records
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: One brain for all your AI agents' memories (CLAUDE.md, AGENTS.md, napkins, rules), synced online or air-gapped.
|
|
5
|
+
Author: gablooge
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/gablooge/punk-records
|
|
8
|
+
Project-URL: Issues, https://github.com/gablooge/punk-records/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/gablooge/punk-records/blob/main/CHANGELOG.md
|
|
10
|
+
Keywords: ai,memory,claude,agents,mcp,cursor,codex,sync,air-gapped
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Development Status :: 3 - Alpha
|
|
18
|
+
Classifier: Intended Audience :: Developers
|
|
19
|
+
Classifier: Operating System :: OS Independent
|
|
20
|
+
Classifier: Environment :: Console
|
|
21
|
+
Classifier: Topic :: Software Development
|
|
22
|
+
Requires-Python: >=3.9
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
License-File: LICENSE
|
|
25
|
+
Dynamic: license-file
|
|
26
|
+
|
|
27
|
+
# Punk Records
|
|
28
|
+
|
|
29
|
+
[](https://github.com/gablooge/punk-records/actions/workflows/ci.yml)
|
|
30
|
+
[](https://pypi.org/project/punk-records/)
|
|
31
|
+
[](https://pypi.org/project/punk-records/)
|
|
32
|
+
[](https://github.com/gablooge/punk-records/blob/main/LICENSE)
|
|
33
|
+
|
|
34
|
+
**One brain for all your AI agents.** Persist every `CLAUDE.md`, `AGENTS.md`, napkin, and rules file
|
|
35
|
+
from every project and machine in a single versioned store. Sync it over any git remote, or carry it
|
|
36
|
+
across an air gap on a USB stick. Agents can read and write it live over MCP.
|
|
37
|
+
|
|
38
|
+

|
|
39
|
+
|
|
40
|
+
> On [Egghead](https://onepiece.fandom.com/wiki/Egghead), Dr.
|
|
41
|
+
> [Vegapunk](https://onepiece.fandom.com/wiki/Vegapunk) keeps one shared brain, the
|
|
42
|
+
> [Punk Records](https://onepiece.fandom.com/wiki/Punk_Records). His satellites each go off
|
|
43
|
+
> and learn things, and whatever they learn flows back into that shared brain. This project does the
|
|
44
|
+
> same for your agents: each project and machine is a satellite, and `~/.punk-records` is the brain.
|
|
45
|
+
>
|
|
46
|
+
> <sub>The name is a nod to *One Piece* (the linked wiki pages contain spoilers). This is a fan-named
|
|
47
|
+
> project, not affiliated with Eiichiro Oda, Shueisha or Toei Animation.</sub>
|
|
48
|
+
|
|
49
|
+
## Why
|
|
50
|
+
|
|
51
|
+
Agent memories are scattered across dozens of repos and dotfiles. Many of them are deliberately
|
|
52
|
+
uncommitted (`CLAUDE.local.md`, napkins, `~/.claude/CLAUDE.md`). They get lost when you wipe a
|
|
53
|
+
laptop, they diverge between your work and home machines, and they can't follow you into an
|
|
54
|
+
offline network.
|
|
55
|
+
|
|
56
|
+
## How it compares
|
|
57
|
+
|
|
58
|
+
- **Committing `CLAUDE.md` to each repo.** Keep doing it for conventions your team shares. It does not
|
|
59
|
+
cover the memories you keep out of git on purpose (`CLAUDE.local.md`, napkins, `~/.claude`), notes
|
|
60
|
+
you would rather not push to a team repo, or a machine that cannot reach the repo host. Punk
|
|
61
|
+
Records stores those too, alongside the committed ones.
|
|
62
|
+
- **Dotfiles managers** (chezmoi, yadm, GNU Stow). They are built for files at fixed paths in your home
|
|
63
|
+
directory. Most agent memories live inside project checkouts, at different paths on each machine.
|
|
64
|
+
Punk Records finds them by itself, matches checkouts by their git remote, merges edits made on two
|
|
65
|
+
machines, scans for secrets before storing, and serves everything to agents over MCP. The two work
|
|
66
|
+
together: a global memory that is a symlink into your dotfiles repo is followed (see below).
|
|
67
|
+
|
|
68
|
+
## What it picks up
|
|
69
|
+
|
|
70
|
+
| Scope | Files |
|
|
71
|
+
|---|---|
|
|
72
|
+
| 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) |
|
|
73
|
+
| | `.claude/*.md` (napkins, commands, agents), `.claude/skills/*`, `.cursor/rules/*`, `.windsurf/rules/*`, `.clinerules/*`, `.roo/rules/*`, `.kiro/steering/*`, `.github/copilot-instructions.md`, `.github/instructions/*.md` |
|
|
74
|
+
| Global (`$HOME`) | `~/.claude/CLAUDE.md`, `~/.claude/napkin.md`, `~/.claude/{commands,agents,skills}/*`, `~/.codex/AGENTS.md`, `~/.gemini/GEMINI.md`, `~/.config/goose/.goosehints` |
|
|
75
|
+
|
|
76
|
+
Run `punk scan` to see what would be captured. To add your own patterns, put globs in `punk.json`
|
|
77
|
+
inside the store (`{"include": ["docs/ai/*.md"], "exclude": []}`).
|
|
78
|
+
|
|
79
|
+
## Install
|
|
80
|
+
|
|
81
|
+
Requires Python 3.9+ and git. No other dependencies.
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
pipx install punk-records # or: pip install punk-records
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## Quickstart
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
punk init # creates ~/.punk-records and tracks your global memories
|
|
91
|
+
punk track ~/code/app ~/code/api
|
|
92
|
+
punk save # snapshot every memory file into the store
|
|
93
|
+
punk context ~/code/app # everything an agent should know there, as one document
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### Online sync (any git host)
|
|
97
|
+
|
|
98
|
+
Create a **private** repo (GitHub, GitLab, Gitea, a bare repo on your NAS, anything git can reach):
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
punk git remote add origin git@github.com:you/my-punk-records.git
|
|
102
|
+
punk sync # save -> pull -> push -> restore
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
On another machine:
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
punk init git@github.com:you/my-punk-records.git
|
|
109
|
+
punk track ~/src/app # matched to the same records through the project's git remote
|
|
110
|
+
punk sync
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Projects get their identity from their git remote (`github.com/you/app`), so the same repo checked out
|
|
114
|
+
at different paths on different machines shares one set of memories. Projects without a remote get
|
|
115
|
+
`local/<dirname>`; you can override it with `punk track --id`.
|
|
116
|
+
|
|
117
|
+
### Air-gapped sync
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
punk export /media/usb/records.bundle # on the connected side
|
|
121
|
+
punk import /media/usb/records.bundle # on the air-gapped side (and back again)
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
A bundle is a standard `git bundle` file. It carries full history and can be verified on arrival, and
|
|
125
|
+
imports merge the same way online pulls do.
|
|
126
|
+
|
|
127
|
+
### Let agents use it live (MCP)
|
|
128
|
+
|
|
129
|
+
There is no server to keep running. Your agent starts `punk mcp` when a session begins and talks to
|
|
130
|
+
it over stdin/stdout. Run `punk init` once first, then register it:
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
claude mcp add --scope user punk-records -- punk mcp # all projects; without --scope: this project only
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Any MCP client works the same way (`"command": "punk", "args": ["mcp"]`). If the client cannot find
|
|
137
|
+
`punk`, give it the full path from `which punk`. Tools offered:
|
|
138
|
+
`get_context`, `search_memories`, `read_memory`, `list_memories`, `list_satellites`,
|
|
139
|
+
`append_memory` (writes to the store, commits, and updates the local file), and `sync`.
|
|
140
|
+
|
|
141
|
+
From the shell: `punk remember "- integration tests need docker running"` appends to the current
|
|
142
|
+
project's `CLAUDE.md` (use `-f .claude/napkin.md` to target another file).
|
|
143
|
+
|
|
144
|
+
## How sync works
|
|
145
|
+
|
|
146
|
+
- **The store is a git repo.** Every save is a commit, so `punk git log -p` shows how your agents'
|
|
147
|
+
knowledge changed over time, and nothing is ever truly lost.
|
|
148
|
+
- **Three-way per file.** Punk records the local and store hash of each file at its last sync, which
|
|
149
|
+
lets it tell "edited here" apart from "edited on another machine". When both sides changed, it
|
|
150
|
+
reports a **conflict** and leaves both copies alone. `punk diff <satellite> <path>` shows what
|
|
151
|
+
differs (`-` store, `+` local). You resolve it with `save --force` (local wins) or
|
|
152
|
+
`restore --force` (store wins, and your local copy is kept as `.punk-bak`).
|
|
153
|
+
- **Concurrent appends merge.** Memory files use git's `union` merge driver, so when two machines
|
|
154
|
+
add lines to the same `CLAUDE.md`, the result contains both sets of lines. The catch: if both
|
|
155
|
+
machines change the *same* line, the merged file keeps both versions, one after the other. Nothing
|
|
156
|
+
is lost, but read the file after such a sync and delete the line you no longer want;
|
|
157
|
+
`punk git log -p` shows which machine wrote which.
|
|
158
|
+
- **Deletes propagate on save.** Locally removing a file that was synced removes it from the store.
|
|
159
|
+
Deletions coming *from* the store are only reported, unless you pass `restore --prune`.
|
|
160
|
+
- **Symlinked memories are kept as links.** If `AGENTS.md -> CLAUDE.md`, the content is stored once
|
|
161
|
+
and the link is recorded in `satellites/<id>.json`, then recreated on other machines. Only links
|
|
162
|
+
that resolve to a memory file inside the same project are recorded. Links that point outside the
|
|
163
|
+
project are never followed. `punk scan` and `punk save` warn about them instead.
|
|
164
|
+
- **Dotfiles work.** For global memories, a link such as `~/.claude/CLAUDE.md ->
|
|
165
|
+
~/dotfiles/claude/CLAUDE.md` is followed: the content is stored, and restores write through the
|
|
166
|
+
link into your dotfiles repo. Only non-executable Markdown/text files (or files with the same name
|
|
167
|
+
as the link) inside `$HOME` are followed, never anything under `.git`, `.ssh`, `.gnupg`, `.aws`
|
|
168
|
+
and similar.
|
|
169
|
+
|
|
170
|
+
## Safety
|
|
171
|
+
|
|
172
|
+
- **Secret scanning.** Before a file enters the store it is checked for API keys (Anthropic, OpenAI,
|
|
173
|
+
AWS, GitHub, Slack, Google, Stripe), private keys, and `password=...`-style assignments. A matching
|
|
174
|
+
file is blocked by default. You can pass `--redact` to store it with secrets replaced, or put
|
|
175
|
+
`punk:allow` on a line to mark a false positive.
|
|
176
|
+
- **Restricted writes.** `restore` only writes paths that match the memory patterns. It never writes
|
|
177
|
+
into `.git/`, outside the project, through `..`, or through an existing symlink. Recreated symlinks
|
|
178
|
+
must point from one memory path to another inside the project, so a tampered store or bundle can't
|
|
179
|
+
plant hooks or scripts in your repos.
|
|
180
|
+
- **Keep the remote private.** Memories describe your code and habits. If you need encryption at
|
|
181
|
+
rest on a third-party host, [git-crypt](https://github.com/AGWA/git-crypt) works transparently
|
|
182
|
+
on the store repo.
|
|
183
|
+
|
|
184
|
+
## Commands
|
|
185
|
+
|
|
186
|
+
```
|
|
187
|
+
init [URL] create a store, or clone an existing one
|
|
188
|
+
track [DIR...] start persisting a project untrack ID [--purge]
|
|
189
|
+
list | scan what is tracked / what would be captured
|
|
190
|
+
save | restore store <-> local projects (--dry-run, --force)
|
|
191
|
+
status what save/restore would do
|
|
192
|
+
diff [ID] [PATH] unified diff of local memories vs the store
|
|
193
|
+
sync save, pull/push remote, restore
|
|
194
|
+
export | import air-gapped bundle files
|
|
195
|
+
search | show | context | remember
|
|
196
|
+
git ... run git inside the store
|
|
197
|
+
mcp MCP server on stdio
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
## Roadmap
|
|
201
|
+
|
|
202
|
+
- Built-in encryption (age) for untrusted remotes
|
|
203
|
+
- `punk watch`: save automatically when memory files change
|
|
204
|
+
- Semantic search and deduplication across projects
|
|
205
|
+
- Shared "team brain" satellites that you can subscribe to read-only
|
|
206
|
+
- Small web UI for browsing memory history
|
|
207
|
+
|
|
208
|
+
## Development
|
|
209
|
+
|
|
210
|
+
```bash
|
|
211
|
+
python -m unittest discover -s tests -v
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
See [CONTRIBUTING.md](https://github.com/gablooge/punk-records/blob/main/CONTRIBUTING.md) for the rules (no runtime dependencies, Python 3.9 syntax,
|
|
215
|
+
tests for every change). Report security problems privately as described in
|
|
216
|
+
[SECURITY.md](https://github.com/gablooge/punk-records/blob/main/SECURITY.md).
|
|
217
|
+
|
|
218
|
+
MIT licensed.
|
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
# Punk Records
|
|
2
|
+
|
|
3
|
+
[](https://github.com/gablooge/punk-records/actions/workflows/ci.yml)
|
|
4
|
+
[](https://pypi.org/project/punk-records/)
|
|
5
|
+
[](https://pypi.org/project/punk-records/)
|
|
6
|
+
[](https://github.com/gablooge/punk-records/blob/main/LICENSE)
|
|
7
|
+
|
|
8
|
+
**One brain for all your AI agents.** Persist every `CLAUDE.md`, `AGENTS.md`, napkin, and rules file
|
|
9
|
+
from every project and machine in a single versioned store. Sync it over any git remote, or carry it
|
|
10
|
+
across an air gap on a USB stick. Agents can read and write it live over MCP.
|
|
11
|
+
|
|
12
|
+

|
|
13
|
+
|
|
14
|
+
> On [Egghead](https://onepiece.fandom.com/wiki/Egghead), Dr.
|
|
15
|
+
> [Vegapunk](https://onepiece.fandom.com/wiki/Vegapunk) keeps one shared brain, the
|
|
16
|
+
> [Punk Records](https://onepiece.fandom.com/wiki/Punk_Records). His satellites each go off
|
|
17
|
+
> and learn things, and whatever they learn flows back into that shared brain. This project does the
|
|
18
|
+
> same for your agents: each project and machine is a satellite, and `~/.punk-records` is the brain.
|
|
19
|
+
>
|
|
20
|
+
> <sub>The name is a nod to *One Piece* (the linked wiki pages contain spoilers). This is a fan-named
|
|
21
|
+
> project, not affiliated with Eiichiro Oda, Shueisha or Toei Animation.</sub>
|
|
22
|
+
|
|
23
|
+
## Why
|
|
24
|
+
|
|
25
|
+
Agent memories are scattered across dozens of repos and dotfiles. Many of them are deliberately
|
|
26
|
+
uncommitted (`CLAUDE.local.md`, napkins, `~/.claude/CLAUDE.md`). They get lost when you wipe a
|
|
27
|
+
laptop, they diverge between your work and home machines, and they can't follow you into an
|
|
28
|
+
offline network.
|
|
29
|
+
|
|
30
|
+
## How it compares
|
|
31
|
+
|
|
32
|
+
- **Committing `CLAUDE.md` to each repo.** Keep doing it for conventions your team shares. It does not
|
|
33
|
+
cover the memories you keep out of git on purpose (`CLAUDE.local.md`, napkins, `~/.claude`), notes
|
|
34
|
+
you would rather not push to a team repo, or a machine that cannot reach the repo host. Punk
|
|
35
|
+
Records stores those too, alongside the committed ones.
|
|
36
|
+
- **Dotfiles managers** (chezmoi, yadm, GNU Stow). They are built for files at fixed paths in your home
|
|
37
|
+
directory. Most agent memories live inside project checkouts, at different paths on each machine.
|
|
38
|
+
Punk Records finds them by itself, matches checkouts by their git remote, merges edits made on two
|
|
39
|
+
machines, scans for secrets before storing, and serves everything to agents over MCP. The two work
|
|
40
|
+
together: a global memory that is a symlink into your dotfiles repo is followed (see below).
|
|
41
|
+
|
|
42
|
+
## What it picks up
|
|
43
|
+
|
|
44
|
+
| Scope | Files |
|
|
45
|
+
|---|---|
|
|
46
|
+
| 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) |
|
|
47
|
+
| | `.claude/*.md` (napkins, commands, agents), `.claude/skills/*`, `.cursor/rules/*`, `.windsurf/rules/*`, `.clinerules/*`, `.roo/rules/*`, `.kiro/steering/*`, `.github/copilot-instructions.md`, `.github/instructions/*.md` |
|
|
48
|
+
| Global (`$HOME`) | `~/.claude/CLAUDE.md`, `~/.claude/napkin.md`, `~/.claude/{commands,agents,skills}/*`, `~/.codex/AGENTS.md`, `~/.gemini/GEMINI.md`, `~/.config/goose/.goosehints` |
|
|
49
|
+
|
|
50
|
+
Run `punk scan` to see what would be captured. To add your own patterns, put globs in `punk.json`
|
|
51
|
+
inside the store (`{"include": ["docs/ai/*.md"], "exclude": []}`).
|
|
52
|
+
|
|
53
|
+
## Install
|
|
54
|
+
|
|
55
|
+
Requires Python 3.9+ and git. No other dependencies.
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
pipx install punk-records # or: pip install punk-records
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Quickstart
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
punk init # creates ~/.punk-records and tracks your global memories
|
|
65
|
+
punk track ~/code/app ~/code/api
|
|
66
|
+
punk save # snapshot every memory file into the store
|
|
67
|
+
punk context ~/code/app # everything an agent should know there, as one document
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
### Online sync (any git host)
|
|
71
|
+
|
|
72
|
+
Create a **private** repo (GitHub, GitLab, Gitea, a bare repo on your NAS, anything git can reach):
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
punk git remote add origin git@github.com:you/my-punk-records.git
|
|
76
|
+
punk sync # save -> pull -> push -> restore
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
On another machine:
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
punk init git@github.com:you/my-punk-records.git
|
|
83
|
+
punk track ~/src/app # matched to the same records through the project's git remote
|
|
84
|
+
punk sync
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Projects get their identity from their git remote (`github.com/you/app`), so the same repo checked out
|
|
88
|
+
at different paths on different machines shares one set of memories. Projects without a remote get
|
|
89
|
+
`local/<dirname>`; you can override it with `punk track --id`.
|
|
90
|
+
|
|
91
|
+
### Air-gapped sync
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
punk export /media/usb/records.bundle # on the connected side
|
|
95
|
+
punk import /media/usb/records.bundle # on the air-gapped side (and back again)
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
A bundle is a standard `git bundle` file. It carries full history and can be verified on arrival, and
|
|
99
|
+
imports merge the same way online pulls do.
|
|
100
|
+
|
|
101
|
+
### Let agents use it live (MCP)
|
|
102
|
+
|
|
103
|
+
There is no server to keep running. Your agent starts `punk mcp` when a session begins and talks to
|
|
104
|
+
it over stdin/stdout. Run `punk init` once first, then register it:
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
claude mcp add --scope user punk-records -- punk mcp # all projects; without --scope: this project only
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Any MCP client works the same way (`"command": "punk", "args": ["mcp"]`). If the client cannot find
|
|
111
|
+
`punk`, give it the full path from `which punk`. Tools offered:
|
|
112
|
+
`get_context`, `search_memories`, `read_memory`, `list_memories`, `list_satellites`,
|
|
113
|
+
`append_memory` (writes to the store, commits, and updates the local file), and `sync`.
|
|
114
|
+
|
|
115
|
+
From the shell: `punk remember "- integration tests need docker running"` appends to the current
|
|
116
|
+
project's `CLAUDE.md` (use `-f .claude/napkin.md` to target another file).
|
|
117
|
+
|
|
118
|
+
## How sync works
|
|
119
|
+
|
|
120
|
+
- **The store is a git repo.** Every save is a commit, so `punk git log -p` shows how your agents'
|
|
121
|
+
knowledge changed over time, and nothing is ever truly lost.
|
|
122
|
+
- **Three-way per file.** Punk records the local and store hash of each file at its last sync, which
|
|
123
|
+
lets it tell "edited here" apart from "edited on another machine". When both sides changed, it
|
|
124
|
+
reports a **conflict** and leaves both copies alone. `punk diff <satellite> <path>` shows what
|
|
125
|
+
differs (`-` store, `+` local). You resolve it with `save --force` (local wins) or
|
|
126
|
+
`restore --force` (store wins, and your local copy is kept as `.punk-bak`).
|
|
127
|
+
- **Concurrent appends merge.** Memory files use git's `union` merge driver, so when two machines
|
|
128
|
+
add lines to the same `CLAUDE.md`, the result contains both sets of lines. The catch: if both
|
|
129
|
+
machines change the *same* line, the merged file keeps both versions, one after the other. Nothing
|
|
130
|
+
is lost, but read the file after such a sync and delete the line you no longer want;
|
|
131
|
+
`punk git log -p` shows which machine wrote which.
|
|
132
|
+
- **Deletes propagate on save.** Locally removing a file that was synced removes it from the store.
|
|
133
|
+
Deletions coming *from* the store are only reported, unless you pass `restore --prune`.
|
|
134
|
+
- **Symlinked memories are kept as links.** If `AGENTS.md -> CLAUDE.md`, the content is stored once
|
|
135
|
+
and the link is recorded in `satellites/<id>.json`, then recreated on other machines. Only links
|
|
136
|
+
that resolve to a memory file inside the same project are recorded. Links that point outside the
|
|
137
|
+
project are never followed. `punk scan` and `punk save` warn about them instead.
|
|
138
|
+
- **Dotfiles work.** For global memories, a link such as `~/.claude/CLAUDE.md ->
|
|
139
|
+
~/dotfiles/claude/CLAUDE.md` is followed: the content is stored, and restores write through the
|
|
140
|
+
link into your dotfiles repo. Only non-executable Markdown/text files (or files with the same name
|
|
141
|
+
as the link) inside `$HOME` are followed, never anything under `.git`, `.ssh`, `.gnupg`, `.aws`
|
|
142
|
+
and similar.
|
|
143
|
+
|
|
144
|
+
## Safety
|
|
145
|
+
|
|
146
|
+
- **Secret scanning.** Before a file enters the store it is checked for API keys (Anthropic, OpenAI,
|
|
147
|
+
AWS, GitHub, Slack, Google, Stripe), private keys, and `password=...`-style assignments. A matching
|
|
148
|
+
file is blocked by default. You can pass `--redact` to store it with secrets replaced, or put
|
|
149
|
+
`punk:allow` on a line to mark a false positive.
|
|
150
|
+
- **Restricted writes.** `restore` only writes paths that match the memory patterns. It never writes
|
|
151
|
+
into `.git/`, outside the project, through `..`, or through an existing symlink. Recreated symlinks
|
|
152
|
+
must point from one memory path to another inside the project, so a tampered store or bundle can't
|
|
153
|
+
plant hooks or scripts in your repos.
|
|
154
|
+
- **Keep the remote private.** Memories describe your code and habits. If you need encryption at
|
|
155
|
+
rest on a third-party host, [git-crypt](https://github.com/AGWA/git-crypt) works transparently
|
|
156
|
+
on the store repo.
|
|
157
|
+
|
|
158
|
+
## Commands
|
|
159
|
+
|
|
160
|
+
```
|
|
161
|
+
init [URL] create a store, or clone an existing one
|
|
162
|
+
track [DIR...] start persisting a project untrack ID [--purge]
|
|
163
|
+
list | scan what is tracked / what would be captured
|
|
164
|
+
save | restore store <-> local projects (--dry-run, --force)
|
|
165
|
+
status what save/restore would do
|
|
166
|
+
diff [ID] [PATH] unified diff of local memories vs the store
|
|
167
|
+
sync save, pull/push remote, restore
|
|
168
|
+
export | import air-gapped bundle files
|
|
169
|
+
search | show | context | remember
|
|
170
|
+
git ... run git inside the store
|
|
171
|
+
mcp MCP server on stdio
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
## Roadmap
|
|
175
|
+
|
|
176
|
+
- Built-in encryption (age) for untrusted remotes
|
|
177
|
+
- `punk watch`: save automatically when memory files change
|
|
178
|
+
- Semantic search and deduplication across projects
|
|
179
|
+
- Shared "team brain" satellites that you can subscribe to read-only
|
|
180
|
+
- Small web UI for browsing memory history
|
|
181
|
+
|
|
182
|
+
## Development
|
|
183
|
+
|
|
184
|
+
```bash
|
|
185
|
+
python -m unittest discover -s tests -v
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
See [CONTRIBUTING.md](https://github.com/gablooge/punk-records/blob/main/CONTRIBUTING.md) for the rules (no runtime dependencies, Python 3.9 syntax,
|
|
189
|
+
tests for every change). Report security problems privately as described in
|
|
190
|
+
[SECURITY.md](https://github.com/gablooge/punk-records/blob/main/SECURITY.md).
|
|
191
|
+
|
|
192
|
+
MIT licensed.
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "punk-records"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "One brain for all your AI agents' memories (CLAUDE.md, AGENTS.md, napkins, rules), synced online or air-gapped."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
authors = [{ name = "gablooge" }]
|
|
13
|
+
requires-python = ">=3.9"
|
|
14
|
+
dependencies = []
|
|
15
|
+
keywords = ["ai", "memory", "claude", "agents", "mcp", "cursor", "codex", "sync", "air-gapped"]
|
|
16
|
+
classifiers = [
|
|
17
|
+
"Programming Language :: Python :: 3",
|
|
18
|
+
"Programming Language :: Python :: 3.9",
|
|
19
|
+
"Programming Language :: Python :: 3.10",
|
|
20
|
+
"Programming Language :: Python :: 3.11",
|
|
21
|
+
"Programming Language :: Python :: 3.12",
|
|
22
|
+
"Programming Language :: Python :: 3.13",
|
|
23
|
+
"Development Status :: 3 - Alpha",
|
|
24
|
+
"Intended Audience :: Developers",
|
|
25
|
+
"Operating System :: OS Independent",
|
|
26
|
+
"Environment :: Console",
|
|
27
|
+
"Topic :: Software Development",
|
|
28
|
+
]
|
|
29
|
+
|
|
30
|
+
[project.urls]
|
|
31
|
+
Homepage = "https://github.com/gablooge/punk-records"
|
|
32
|
+
Issues = "https://github.com/gablooge/punk-records/issues"
|
|
33
|
+
Changelog = "https://github.com/gablooge/punk-records/blob/main/CHANGELOG.md"
|
|
34
|
+
|
|
35
|
+
[project.scripts]
|
|
36
|
+
punk = "punk_records.cli:main"
|
|
37
|
+
|
|
38
|
+
[tool.setuptools.dynamic]
|
|
39
|
+
version = { attr = "punk_records.__version__" }
|
|
40
|
+
|
|
41
|
+
[tool.setuptools.packages.find]
|
|
42
|
+
where = ["src"]
|
|
43
|
+
|
|
44
|
+
[tool.ruff]
|
|
45
|
+
target-version = "py39"
|
|
46
|
+
line-length = 120
|
|
47
|
+
|
|
48
|
+
[tool.ruff.lint]
|
|
49
|
+
# pyflakes, pycodestyle, import order, bugbear, pyupgrade (3.9 syntax only)
|
|
50
|
+
select = ["F", "E", "W", "I", "B", "UP"]
|