paragma 0.2.7 → 0.3.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 (3) hide show
  1. package/README.md +19 -2
  2. package/SHA256SUMS +6 -6
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -26,6 +26,8 @@ pg setup
26
26
 
27
27
  That is all. `npm` fetches the build of `pg` for your computer (Windows, macOS or Linux, on x64 or arm64) and checks it against the release's SHA-256 sums. It needs Node 18 or later. `pg setup` then opens a small screen where you pick your coding agents and where Paragma should be read: in every conversation, or only in one project's folder.
28
28
 
29
+ A newer npm may warn that `paragma` has install scripts not covered by `allowScripts`. That is fine: the first `pg` call fetches the binary instead.
30
+
29
31
  <details>
30
32
  <summary>Without npm</summary>
31
33
 
@@ -33,7 +35,7 @@ Download `pg` for your platform from the [releases](https://github.com/Utku4836/
33
35
 
34
36
  </details>
35
37
 
36
- Your memory lives in `~/.paragma`, outside your repositories. Paragma never opens a network connection; the search model is built into `pg`.
38
+ Your memory lives in `~/.paragma`, outside your repositories. Paragma works offline; the search model is built into `pg`. Only `pg git`, once you connect it, talks to GitHub.
37
39
 
38
40
  ## Why
39
41
 
@@ -140,6 +142,7 @@ pg write --decision "..." --why "..." --alternatives "..."
140
142
  pg write --error "<error line>" --cause "..." --fix "..."
141
143
  pg write payments/provider --file notes.md # a note; long text from a file or stdin (-)
142
144
  pg finish --done 1 "what changed, what is next" # tick off steps, leave the handoff
145
+ pg ripple # what a change reaches: callers left as they were, tests to run
143
146
  pg tree # the code: files and symbols, with the notes about them marked
144
147
  pg ls # projects, or the notes of one; also pg mv, pg rm, pg doctor
145
148
  ```
@@ -157,13 +160,27 @@ pg run -- npm publish --token '$NPM_PUBLISH_TOKEN'
157
160
 
158
161
  `pg run` puts the value in place itself, on every platform, and prints `$NPM_PUBLISH_TOKEN` again wherever the value would appear in the output. Keys pasted into notes are masked and not kept. In a test with 50 keys and ten requests in plain words, the right key came first every time and was used through `pg run` without its value appearing in any output.
159
162
 
163
+ ### Backup and sync
164
+
165
+ ```bash
166
+ pg git
167
+ ```
168
+
169
+ Opens a small screen: sign in to GitHub (with the GitHub CLI or the sign-in git already has, else in the browser with a code), then choose where the memory goes: a new private repository (`paragma-memory`), or one you have, in a `Paragma/` folder on its own branch or on its main branch. Choosing a public repository asks first. The `.env` files go only if you say so, and never to a public repository.
170
+
171
+ From then on every change goes there by itself, a few seconds after it is made, in the background: the agent never waits for it. What other computers sent comes in the same way. On a new computer, `pg git` finds the memory in your repositories (your own and your organizations') and restores it, joined with whatever is already there. The indexes and the short-lived state in `.pg/` never go; they are rebuilt.
172
+
173
+ Run `pg git` again to see the account, the repository and the last sync, to change the `.env` setting, to move the memory to another repository (other computers follow by themselves) or to disconnect. Without a terminal: `pg git connect --new`, `pg git status`, `pg git sync`, `pg git env on|off`, `pg git move --repo owner/name`, `pg git disconnect`.
174
+
160
175
  ## How it works
161
176
 
162
177
  - **Plain Markdown.** Each project is a folder in `~/.paragma/projects/`: `project.md` (goal, steps, handoffs), `rules.md`, `decisions/`, `errors/` and any notes you like. Open it in any editor; edits are picked up on the next call.
163
178
  - **Hybrid search.** Full-text search (SQLite FTS5) and meaning search with a multilingual embedding model built into the binary ([potion-multilingual-128M](https://huggingface.co/minishlab/potion-multilingual-128M), reduced to Latin scripts and 4-bit), merged by rank. A question in Turkish finds a note written in English.
164
179
  - **Code awareness.** Paragma reads 20 programming languages, the shading languages (WGSL, GLSL, HLSL), SQL, GraphQL, Protobuf, Dockerfiles, CI and compose files, Vue and Svelte: files, functions, types, what each function calls. Shaders and queries kept in strings (``/* wgsl */ `...` ``, ``sql`...` ``) are read as their language, and Markdown documents by their sections, so the brief and `pg find` name the section to read. Notes are linked to code by path and symbol, and record the state of the code when they were written, so a note says when it may be out of date.
180
+ - **What a change reaches.** `pg ripple` compares the code with the last commit: a function whose signature changed, renamed or removed, with the callers the change left as they were and the tests that reach it; a shader struct, GraphQL or Protobuf type or SQL table whose fields changed, with the other code that names them. `pg run`, the hooks and `pg finish` say it by themselves; `pg ripple Refund` tells what reaches a function before changing it.
181
+ - **Libraries at their versions.** The libraries a project locks (Cargo.lock, node_modules, go.mod, a virtual environment) are read from the source already on the computer, when an agent asks: `pg find "serde_json Value get"` gives the real signature, doc, example, the feature it needs and deprecation at that version; a failed build that looked for a name a library does not have gets the right one from `pg run`; an upgrade is pointed out in the brief with what changed in what the code calls.
165
182
  - **Records that merge.** Writing a rule, decision or error that is already known updates the existing one instead of adding a copy; a decision that contradicts an earlier one is pointed out.
166
- - **One binary.** `pg` is written in Rust: no runtime, no server, no network. The indexes next to the notes can be deleted at any time and are rebuilt.
183
+ - **One binary.** `pg` is written in Rust: no runtime, no server, and no network unless you connect `pg git` (it uses git and curl). The indexes next to the notes can be deleted at any time and are rebuilt.
167
184
 
168
185
  ## How it is tested
169
186
 
package/SHA256SUMS CHANGED
@@ -1,6 +1,6 @@
1
- 3925ee7b9390989cb702528ca99a89f3dbb0ba74f9b203de885c6e03d81fefd9 pg-darwin-arm64
2
- 99836619bfbaa7314f7b4d7b13f4756c5e2456c007d7cfb022d96efc5340098f pg-darwin-x64
3
- abce83da17188c8789aebefda7e4f32de5940967d6399bb19eae026b5cd18b3f pg-linux-arm64
4
- 968d0da083075cf223f0fbdb04e5134d680af99c3724bc4e6aad13e6c6eff24e pg-linux-x64
5
- 5c5a13308acdddafaaeafd4ea1d3009f51b4478af6381b79883177e81edd0b33 pg-windows-arm64.exe
6
- 32f85609f703f83a3ab6aa0686e73fc2339d6204d7cf89907c2302730fb0bb30 pg-windows-x64.exe
1
+ 5fb0e7851a5b463d64c949ae9e940927eb86dd35c5466bbb4a73af20d471a140 pg-darwin-arm64
2
+ d20bf0257481faa4385235bc53fc5669a1945de8342adf0b34ce1fc0c1c06a6f pg-darwin-x64
3
+ a73eb5cca079271642fdbaa4c90594ed5857cc0a05a650b7b1b568007b451042 pg-linux-arm64
4
+ 950eecf79c46163635bec0436efa551c242380b8ae23939c7f09362ced4c431f pg-linux-x64
5
+ 2a523e3622166699e657e0f0597265569325a634e65ca28ccb00cc427300bd5e pg-windows-arm64.exe
6
+ 8682f8501c0d8d9098daa6574d979c7392201028ccc0c48293c15a52a0dc8bfd pg-windows-x64.exe
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "paragma",
3
- "version": "0.2.7",
3
+ "version": "0.3.0",
4
4
  "description": "Project memory for AI coding agents: rules, decisions, past errors with their fixes, and handoffs between conversations, found by hybrid search.",
5
5
  "keywords": [
6
6
  "ai",