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.
- package/README.md +99 -2
- package/bin/pg +19 -0
- package/install.js +56 -0
- package/package.json +42 -4
package/README.md
CHANGED
|
@@ -1,3 +1,100 @@
|
|
|
1
|
-
|
|
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
|
-
|
|
5
|
+
<p align="center">
|
|
6
|
+
<a href="#install">Install</a> ·
|
|
7
|
+
<a href="#connect-your-agent">Connect your agent</a> ·
|
|
8
|
+
<a href="#results">Results</a> ·
|
|
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.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
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
|
+
}
|