paragma 0.0.0-stage → 0.1.0

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.
Files changed (4) hide show
  1. package/README.md +99 -2
  2. package/bin/pg +19 -0
  3. package/install.js +56 -0
  4. package/package.json +42 -4
package/README.md CHANGED
@@ -1,3 +1,100 @@
1
- # Temporary Holding Version
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/Utku4836/Paragma/main/.github/assets/banner.png" width="100%" alt="Paragma">
3
+ </p>
2
4
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
5
+ <p align="center">
6
+ <a href="#install">Install</a> &nbsp;·&nbsp;
7
+ <a href="#connect-your-agent">Connect your agent</a> &nbsp;·&nbsp;
8
+ <a href="#results">Results</a> &nbsp;·&nbsp;
9
+ <a href="#how-it-works">How it works</a>
10
+ </p>
11
+
12
+ Paragma is a local memory for AI coding agents. It keeps a project's rules, decisions, past errors and work notes as Markdown on your computer, and hands the agent what it needs in one command instead of a dozen searches. One binary, `pg`. No server, no network, no model.
13
+
14
+ ## Why
15
+
16
+ An agent starts every conversation from zero. It rediscovers the same project rules, repeats a fix that was already found, and loses the decisions you gave it yesterday. Notes help, but an agent reading files has to search, open and re-open until it trusts it has seen everything, and every extra step re-reads the whole conversation.
17
+
18
+ Paragma answers in one step:
19
+
20
+ - **Known errors come back with their fix.** `pg run -- go test ./...` prints the recorded cause and fix next to a failure it has seen before.
21
+ - **A topic in one call.** `pg context refund` returns the matching rules, decisions and past fixes, grouped by note, and ends by saying that nothing else matches, so the agent stops searching.
22
+ - **Work outlives the conversation.** `pg start` records the goal, the steps and your decisions. In a new conversation `pg resume` brings them back, together with the code that changed since.
23
+
24
+ ## Results
25
+
26
+ The same knowledge reached two ways: as plain Markdown notes the agent reads with its own tools, or through Paragma. Five questions answered from memory by the same agent (Antigravity CLI, Gemini 3.8 Flash High):
27
+
28
+ | Memory | Access | Correct facts | Tool calls | Tokens processed | Time |
29
+ | --- | --- | --- | --- | --- | --- |
30
+ | 149 notes | plain notes | 17/17 | 42 | 1.14M | 281 s |
31
+ | 149 notes | **Paragma** | 17/17 | **19** | **0.40M** | **173 s** |
32
+ | 1,539 notes | plain notes | 17/17 | 60 | 2.17M | 591 s |
33
+ | 1,539 notes | **Paragma** | 17/17 | **12** | **0.32M** | **163 s** |
34
+
35
+ Both always answered correctly. With Paragma the agent made 2 to 5 times fewer tool calls and processed 3 to 7 times fewer tokens, and its cost did not grow with the memory.
36
+
37
+ In full coding tasks, memory decides correctness: without it the agent fixed a recurring error the wrong way and missed a project rule it could not know; with the same knowledge, as notes or through Paragma, every task passed its hidden tests. Setup, scenarios and limits are in [bench/](bench/README.md) and [bench/RESULTS.md](bench/RESULTS.md).
38
+
39
+ ## Install
40
+
41
+ ```bash
42
+ npm install -g paragma
43
+ ```
44
+
45
+ This installs `pg` for Windows, macOS or Linux (x64 and arm64). You can also download `pg` from the [releases](https://github.com/Utku4836/Paragma/releases) and put it on your `PATH`, or build it with Go:
46
+
47
+ ```bash
48
+ go install github.com/Utku4836/Paragma/cmd/pg@latest
49
+ ```
50
+
51
+ Memory lives in `~/.paragma`, outside your repositories. The only file Paragma writes into a project is the instructions section, and only when you set up that project's conversations.
52
+
53
+ ## Connect your agent
54
+
55
+ ```bash
56
+ pg setup
57
+ ```
58
+
59
+ `pg setup` finds the agents on your computer, including their desktop apps, and adds a short "Memory (Paragma)" section where each one reads its instructions. Choose **every conversation**, or pick **one conversation** from the agent's own history to set up only that conversation's folder. Running it again updates the section and leaves the rest of the file alone.
60
+
61
+ | Agent | Apps | Every conversation | One conversation |
62
+ | --- | --- | --- | --- |
63
+ | Claude Code | CLI, desktop | `~/.claude/CLAUDE.md` | `CLAUDE.md` in its folder |
64
+ | Codex | CLI, desktop | `~/.codex/AGENTS.md` | `AGENTS.md` in its folder |
65
+ | Antigravity | CLI, IDE | `~/.gemini/AGENTS.md` | `AGENTS.md` in its folder |
66
+ | OpenCode | CLI | `~/.config/opencode/AGENTS.md` | `AGENTS.md` in its folder |
67
+
68
+ The benchmarks above were run with Antigravity. In scripts: `pg setup codex --global` or `pg setup claude --dir .`
69
+
70
+ ## What the agent does with it
71
+
72
+ The agent learns these commands from the section `pg setup` writes; `pg help` lists the rest.
73
+
74
+ ```bash
75
+ pg prime # start of a conversation: what memory holds
76
+ pg context "refund" # rules, decisions and fixes on a topic, in one call
77
+ pg run -- go test ./... # on failure: the known fix; on success: rules for the files you changed
78
+ pg start payments --goal "Card payments" --step "Webhook" --step "Tests" --decision "Discount before VAT"
79
+ pg done t2f4 # mark a step done; prints the next one in full
80
+ pg resume payments # in a new conversation: goal, decisions, open steps, changed code
81
+ pg error record --from-last --cause "CRLF checkout" --fix "Normalise line endings before hashing"
82
+ ```
83
+
84
+ ## How it works
85
+
86
+ - **Spaces and projects.** Notes are plain Markdown in `~/.paragma/Spaces/<space>/<project>/`. A space works like an Obsidian vault: search and links stay inside it. Open the folder in any editor.
87
+ - **One index.** A SQLite full-text index next to the notes is updated on every call and can be deleted at any time.
88
+ - **Addresses.** Every result starts with an address the agent can pass back: `shopkit/rules^r003`, `payments/payments#Decisions`, `shopkit/errors/catalog-checksum-crlf`.
89
+ - **Local.** Paragma never opens a network connection. Memory stays on your computer and out of git.
90
+
91
+ ## Development
92
+
93
+ ```bash
94
+ go test ./...
95
+ python bench/quick.py # retrieval test without an agent, about a minute
96
+ ```
97
+
98
+ ## License
99
+
100
+ [MIT](LICENSE)
package/bin/pg ADDED
@@ -0,0 +1,19 @@
1
+ #!/usr/bin/env node
2
+ // Runs the native pg binary that install.js downloaded. On Linux and macOS
3
+ // install.js replaces this file with the binary itself, so this wrapper only
4
+ // runs on Windows (or when the download has not happened yet).
5
+ const { spawnSync } = require("child_process");
6
+ const path = require("path");
7
+ const fs = require("fs");
8
+
9
+ const exe = path.join(__dirname, process.platform === "win32" ? "pg.exe" : "pg-native");
10
+ if (!fs.existsSync(exe)) {
11
+ console.error("paragma: the pg binary is missing. Reinstall with: npm install -g paragma");
12
+ process.exit(7);
13
+ }
14
+ const r = spawnSync(exe, process.argv.slice(2), { stdio: "inherit", windowsHide: false });
15
+ if (r.error) {
16
+ console.error("paragma: " + r.error.message);
17
+ process.exit(7);
18
+ }
19
+ process.exit(r.status === null ? 1 : r.status);
package/install.js ADDED
@@ -0,0 +1,56 @@
1
+ // Downloads the pg binary for this platform from the GitHub release that
2
+ // matches this package's version. Release assets are named
3
+ // pg-<os>-<arch>[.exe], for example pg-windows-amd64.exe or pg-darwin-arm64.
4
+ const fs = require("fs");
5
+ const https = require("https");
6
+ const path = require("path");
7
+
8
+ const { version } = require("./package.json");
9
+ const REPO = "Utku4836/Paragma";
10
+
11
+ const os = { win32: "windows", linux: "linux", darwin: "darwin" }[process.platform];
12
+ const arch = { x64: "amd64", arm64: "arm64" }[process.arch];
13
+ if (!os || !arch) {
14
+ console.error(`paragma: no prebuilt pg for ${process.platform}/${process.arch}. Build it with: go install github.com/${REPO}/cmd/pg@latest`);
15
+ process.exit(0);
16
+ }
17
+ const asset = `pg-${os}-${arch}${os === "windows" ? ".exe" : ""}`;
18
+ const url = `https://github.com/${REPO}/releases/download/v${version}/${asset}`;
19
+ const binDir = path.join(__dirname, "bin");
20
+ const target = path.join(binDir, os === "windows" ? "pg.exe" : "pg-native");
21
+
22
+ function get(u, redirects, done) {
23
+ https
24
+ .get(u, { headers: { "User-Agent": "paragma-npm" } }, (res) => {
25
+ if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location && redirects > 0) {
26
+ res.resume();
27
+ return get(res.headers.location, redirects - 1, done);
28
+ }
29
+ if (res.statusCode !== 200) {
30
+ res.resume();
31
+ return done(new Error(`HTTP ${res.statusCode} for ${u}`));
32
+ }
33
+ const tmp = target + ".download";
34
+ const out = fs.createWriteStream(tmp, { mode: 0o755 });
35
+ res.pipe(out);
36
+ out.on("finish", () => out.close(() => done(null, tmp)));
37
+ out.on("error", done);
38
+ })
39
+ .on("error", done);
40
+ }
41
+
42
+ get(url, 5, (err, tmp) => {
43
+ if (err) {
44
+ console.error(`paragma: could not download ${asset}: ${err.message}`);
45
+ console.error(`Download it from https://github.com/${REPO}/releases and put it on your PATH as pg.`);
46
+ process.exit(0); // do not fail the whole npm install
47
+ }
48
+ fs.renameSync(tmp, target);
49
+ if (os !== "windows") {
50
+ // the npm bin link points at bin/pg: make it the binary itself, so pg
51
+ // starts without Node in between
52
+ fs.chmodSync(target, 0o755);
53
+ fs.renameSync(target, path.join(binDir, "pg"));
54
+ }
55
+ console.log(`paragma: installed pg ${version} (${os}/${arch}). Next: pg setup`);
56
+ });
package/package.json CHANGED
@@ -1,6 +1,44 @@
1
1
  {
2
2
  "name": "paragma",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Local memory for AI coding agents: rules, decisions, past errors and project notes, one call away.",
5
+ "keywords": [
6
+ "ai",
7
+ "agents",
8
+ "memory",
9
+ "claude-code",
10
+ "codex",
11
+ "antigravity",
12
+ "opencode",
13
+ "cli"
14
+ ],
15
+ "homepage": "https://github.com/Utku4836/Paragma",
16
+ "repository": {
17
+ "type": "git",
18
+ "url": "git+https://github.com/Utku4836/Paragma.git"
19
+ },
20
+ "license": "MIT",
21
+ "bin": {
22
+ "pg": "bin/pg"
23
+ },
24
+ "scripts": {
25
+ "postinstall": "node install.js"
26
+ },
27
+ "files": [
28
+ "bin/pg",
29
+ "install.js",
30
+ "README.md"
31
+ ],
32
+ "os": [
33
+ "win32",
34
+ "linux",
35
+ "darwin"
36
+ ],
37
+ "cpu": [
38
+ "x64",
39
+ "arm64"
40
+ ],
41
+ "engines": {
42
+ "node": ">=18"
43
+ }
44
+ }