paragma 0.1.2 → 0.1.3

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 CHANGED
@@ -23,18 +23,18 @@ Paragma answers in one step:
23
23
 
24
24
  ## Results
25
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):
26
+ The same knowledge reached two ways: as plain Markdown notes the agent reads with its own tools, or through Paragma. Real agents, OpenCode with two free models (DeepSeek V4.1 Flash and GLM-5.3 Flash, both at their highest reasoning effort), each run in a fresh copy of a small Go project with a memory of 1,539 notes:
27
27
 
28
- | Memory | Access | Correct facts | Tool calls | Tokens processed | Time |
28
+ | Tasks | Access | Result | Tool calls | Tokens processed | Time |
29
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** |
30
+ | 5 questions from memory, 2 models | plain notes | 33/34 facts | 85 | 0.79M | 684 s |
31
+ | | **Paragma** | 33/34 facts | **24** | **0.27M** | 772 s |
32
+ | 3 coding tasks, 2 models | plain notes | 28/28 hidden tests | 267 | 4.94M | 2,673 s |
33
+ | | **Paragma** | 28/28 hidden tests | **213** | **2.40M** | **2,115 s** |
34
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.
35
+ Both ways were equally correct. With Paragma the agents processed about a third of the tokens on questions and half on coding tasks, with fewer tool calls; Paragma was the cheaper of the two in 15 of 16 paired runs.
36
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).
37
+ The coding tasks are a recurring error whose obvious fix is wrong, a feature finished in a second conversation that only knows what the first one recorded, and a change governed by project rules. Without memory, agents failed parts of each in earlier runs. Each task ran once per model and condition, so read the ratios as a trend. Earlier runs, including Antigravity with Gemini, are in [bench/RESULTS.md](bench/RESULTS.md).
38
38
 
39
39
  ## Install
40
40
 
@@ -65,7 +65,7 @@ pg setup
65
65
  | Antigravity | CLI, IDE | `~/.gemini/AGENTS.md` | `AGENTS.md` in its folder |
66
66
  | OpenCode | CLI | `~/.config/opencode/AGENTS.md` | `AGENTS.md` in its folder |
67
67
 
68
- The benchmarks above were run with Antigravity. In scripts: `pg setup codex --global` or `pg setup claude --dir .`
68
+ The results above were measured with OpenCode, earlier ones with Antigravity. In scripts: `pg setup codex --global` or `pg setup claude --dir .`
69
69
 
70
70
  ## What the agent does with it
71
71
 
@@ -73,18 +73,23 @@ The agent learns these commands from the section `pg setup` writes; `pg help` li
73
73
 
74
74
  ```bash
75
75
  pg prime # start of a conversation: what memory holds
76
+ pg start payments --goal "Card payments" --step "Webhook" --step "Tests" --decision "Discount before VAT"
77
+ pg tree # the code: files, their declarations, the rules and errors about each
78
+ pg related payments/refund.go # before changing a file: its rules, decisions, past fixes, last commits
76
79
  pg context "refund" # rules, decisions and fixes on a topic, in one call
77
80
  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
81
  pg done t2f4 # mark a step done; prints the next one in full
82
+ pg checkpoint "where it stands" # before stopping: a handoff for the next conversation
80
83
  pg resume payments # in a new conversation: goal, decisions, open steps, changed code
81
84
  pg error record --from-last --cause "CRLF checkout" --fix "Normalise line endings before hashing"
82
85
  ```
83
86
 
87
+ `pg start` on a project that exists continues it. `pg related` without a path lists the files you changed with the rules that apply to them. Notes, folders and whole projects are renamed or moved with `pg mv`, and many `pg` calls can run at once.
88
+
84
89
  ## How it works
85
90
 
86
91
  - **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.
92
+ - **One index.** A SQLite full-text index next to the notes is updated on every call and can be deleted at any time. Parallel calls wait for each other's writes instead of failing.
88
93
  - **Addresses.** Every result starts with an address the agent can pass back: `shopkit/rules^r003`, `payments/payments#Decisions`, `shopkit/errors/catalog-checksum-crlf`.
89
94
  - **Local.** Paragma never opens a network connection. Memory stays on your computer and out of git.
90
95
 
Binary file
package/bin/pg-darwin-x64 CHANGED
Binary file
Binary file
package/bin/pg-linux-x64 CHANGED
Binary file
Binary file
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "paragma",
3
- "version": "0.1.2",
3
+ "version": "0.1.3",
4
4
  "description": "Local memory for AI coding agents: rules, decisions, past errors and project notes, one call away.",
5
5
  "keywords": [
6
6
  "ai",