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.
@@ -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
+ [![CI](https://github.com/gablooge/punk-records/actions/workflows/ci.yml/badge.svg)](https://github.com/gablooge/punk-records/actions/workflows/ci.yml)
30
+ [![PyPI](https://img.shields.io/pypi/v/punk-records)](https://pypi.org/project/punk-records/)
31
+ [![Python](https://img.shields.io/pypi/pyversions/punk-records)](https://pypi.org/project/punk-records/)
32
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](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
+ ![punk init, track, save, remember and context in a terminal](https://raw.githubusercontent.com/gablooge/punk-records/main/docs/demo.gif)
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
+ [![CI](https://github.com/gablooge/punk-records/actions/workflows/ci.yml/badge.svg)](https://github.com/gablooge/punk-records/actions/workflows/ci.yml)
4
+ [![PyPI](https://img.shields.io/pypi/v/punk-records)](https://pypi.org/project/punk-records/)
5
+ [![Python](https://img.shields.io/pypi/pyversions/punk-records)](https://pypi.org/project/punk-records/)
6
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](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
+ ![punk init, track, save, remember and context in a terminal](https://raw.githubusercontent.com/gablooge/punk-records/main/docs/demo.gif)
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"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,3 @@
1
+ """Punk Records: one brain for all your AI agents' memories."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,3 @@
1
+ from .cli import main
2
+
3
+ raise SystemExit(main())