qriton 0.3.1 → 0.4.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 (17) hide show
  1. package/README.md +136 -271
  2. package/SECURITY.md +31 -0
  3. package/THIRD_PARTY_NOTICES.md +6 -0
  4. package/deploy/nats/README.md +68 -0
  5. package/deploy/nats/nats-server.conf +31 -0
  6. package/deploy/nats/nats-server.service +31 -0
  7. package/dist/qriton.js +578 -513
  8. package/package.json +6 -9
  9. package/release/contract.json +1 -1
  10. package/docs/energy.md +0 -102
  11. package/docs/hlm.md +0 -148
  12. package/docs/network-policy.md +0 -76
  13. package/docs/production-operations.md +0 -107
  14. package/docs/session-recovery.md +0 -35
  15. package/docs/shield.md +0 -62
  16. package/docs/terminal-interaction.md +0 -38
  17. package/docs/workspace-trust.md +0 -68
package/README.md CHANGED
@@ -1,372 +1,237 @@
1
1
  # Qriton CLI
2
2
 
3
- Qriton CLI is the terminal coding agent. It runs on infrastructure you control. Local models, hosted APIs, and the session record stay in one place: the conversation, the tools, and the memory move with the work, not with the provider.
3
+ A coding agent for your terminal that runs on infrastructure you control. Use a local model on your own machine, or any major model API, in the same session: your conversation, approvals and project memory stay with the work when you switch models.
4
4
 
5
- ```
6
- qriton
5
+ It is also home to **[Qriton HLM](https://hlm.qriton.com/)**, our own open models: run them on your machine and teach them, correct them or make them forget, with every change checked and reversible.
6
+
7
+ ```bash
8
+ npm install -g qriton
7
9
  ```
8
10
 
9
- ## First session
11
+ ## What's new in 0.4
10
12
 
11
- Install [Node](https://nodejs.org) 22.16 or later on the 22.x line, or Node 24. Install [Ollama](https://ollama.com) and leave it running.
13
+ - **Windows.** Runs natively on Windows, using PowerShell 7 or `cmd.exe`.
14
+ - **A backup plan for your model.** A dropped connection or overloaded service is retried by itself, and you can list backup models to switch to, with or without asking first. [More](#choose-a-model)
15
+ - **Checked changes.** After editing, the model is asked to test its change before it says it is done.
16
+ - **Several qritons, one team.** Qriton instances on different machines can see each other and pass messages, end-to-end encrypted, over your local network or an internet relay. [More](#several-qritons-on-one-network)
17
+ - **Safer by default.** Stricter rules for which commands run without asking, and a clearer approval for each one.
18
+
19
+ ## Get started
20
+
21
+ Qriton runs on macOS, Linux and Windows. On Windows, install [PowerShell 7](https://learn.microsoft.com/powershell/scripting/install/installing-powershell-on-windows) for the best results; without it, commands run in `cmd.exe`. You need [Node](https://nodejs.org) 22.16 or later (22.x) or Node 24, and [Ollama](https://ollama.com) running for local models.
12
22
 
13
23
  ```bash
14
- npm install -g qriton
15
- qriton pull qwen3.5:4b
24
+ qriton pull qwen3.5:4b # download the default local model
25
+ cd ~/code/your-project
16
26
  qriton
17
27
  ```
18
28
 
19
- `qriton` starts on `qwen3.5:4b`. `qriton --light` uses that model for one bounded session: an 8K context, thinking disabled, and keyword memory. If the pull or the model does not start, run `qriton doctor`.
20
-
21
- Open a terminal in the project directory, not your home folder, and ask for a change. Qriton CLI shows the edit and waits. `qriton -C /path/to/your/project` selects that directory from anywhere.
29
+ Ask for a change in plain language. Qriton reads your code, proposes the edit and waits for you:
22
30
 
23
31
  ```text
24
32
  Approval · File change
25
33
  - # qriton
26
34
  + # Qriton
27
35
 
28
- [y approve] · n reject · a allow kind
36
+ [y approve] · n reject · a always
37
+ a allows all file edits this session without asking again
29
38
  ```
30
39
 
31
- `y` writes the file. `n` leaves it unchanged. Nothing is written before you answer.
40
+ `y` applies it, `n` leaves the file alone. Nothing is written before you answer. Run qriton from the project folder, or point it there from anywhere with `qriton -C ~/code/your-project`. If something doesn't start, run `qriton doctor`.
32
41
 
33
- With this local model, the prompt and the files Qriton CLI reads stay on this machine. Selecting Grok, Claude, or OpenAI sends that context to the provider. The commands are below, after the description of the product.
42
+ On a smaller machine, `qriton --light` runs a lighter session: a smaller context, no thinking, keyword-only memory.
34
43
 
35
- ## What it is for
44
+ ## Qriton HLM
36
45
 
37
- Qriton CLI keeps the evidence of a coding session attached to the session. You can change the model, resume the work, and inspect what was remembered.
46
+ HLM is Qriton's own family of open language models, and qriton is where you work with them. Run an HLM model locally, then change what it knows: teach it a fact, correct one, or make it forget. The model's weights never change. Each edit is a small, separate memory that you preview before it applies: qriton shows the model's real answer before and after, checks that other facts and unrelated prompts are unaffected, and refuses edits that fail. Any edit can be undone exactly.
38
47
 
39
- **Local execution.** Models run through [Ollama](https://ollama.com) on your machine. A bare model name selects a local model. `qriton pull` downloads it. `qriton --light` runs a bounded session: 8K context, thinking disabled, keyword memory.
40
-
41
- **Any model API, in the same session.** A prefix selects xAI, Anthropic, or OpenAI. `OPENAI_BASE_URL` selects an OpenAI-compatible endpoint, including OpenRouter, Groq, vLLM, and LM Studio. `/model` changes the model during a task. The transcript, approvals, and memory remain.
42
-
43
- **Memory with a history.** Facts are stored as a graph: nodes, edges, revisions, and full-text search. A repeated fact reinforces the current one. A corrected fact keeps the previous wording. A fact that no longer applies can be removed. A pinned fact is retained. The next session recalls from that record.
44
-
45
- **Hopfield recall.** `qriton pull bge-m3` installs the embedding model. With embeddings enabled, recall also reads the query against an energy landscape. A low-energy query matches a known basin. A high-energy query is new. A query between two basins — eureka — returns both. `/memory probe` compares ordinary recall with that reading. Keyword and graph recall remain available without embeddings.
46
-
47
- **HLM.** The [HLM workbench](docs/hlm.md) keeps a base model's weights frozen and applies a reversible memory overlay: preview, compare the next token, apply, evaluate, restore. The operation is on the local model. It does not replace the model conducting the coding session.
48
+ ```bash
49
+ qriton hlm catalog # the HLM models available
50
+ qriton hlm fetch hlm5-1b # download and verify (about 4.2 GB)
51
+ qriton hlm predict hlm5-1b "The capital of France is"
52
+ ```
48
53
 
49
- **Energy Language.** The [Energy Language workbench](docs/energy.md) is programmable memory for a supported Hopfield checkpoint. Edits are staged, evaluated, and restored from bounded scripts. The source checkpoint is preserved.
54
+ An edit is one line in a small file:
50
55
 
51
- **Research with sources.** `research` queries several angles, reads the selected pages, and returns the passages that address the question, with numbered sources.
56
+ ```text
57
+ memorize "The capital of Veldoria is" " Paris"
58
+ ```
52
59
 
53
- **A session you can resume.** `qriton --continue` restores the latest session in this directory. `/sessions` lists them. See [session recovery](docs/session-recovery.md). `qriton capabilities` reports what is installed, without loading a model.
60
+ ```bash
61
+ qriton hlm preview hlm5-1b edit.hlm controls.json # check it before anything changes
62
+ qriton hlm apply <proposal-id> # use it
63
+ qriton hlm compare hlm5-1b "The capital of Veldoria is" # original model versus your edits
64
+ qriton hlm restore <proposal-id> # go back exactly
65
+ ```
54
66
 
55
- The runtime adds the terminal interface, provider SDKs, Hopfield analysis, and controlled HTTP.
67
+ | Model | Size | |
68
+ |---|---|---|
69
+ | `hlm5-1b` | 4.2 GB | run and edit |
70
+ | `hlm5-1b-hybrid` | 4.2 GB | run and edit, with a trained memory component |
71
+ | `hlm5-3b` | 10.8 GB | run |
56
72
 
57
- ## Where it fits
73
+ Learn more at [hlm.qriton.com](https://hlm.qriton.com/); the models are on [Hugging Face](https://huggingface.co/qriton). HLM runs in Python, separately from the coding assistant: run `qriton hlm` for setup and `qriton hlm doctor` to check it. The same commands work inside a session after `/hlm`. For HLM3 checkpoints, `qriton energy` offers the same preview, apply and restore workflow in Energy Language.
58
74
 
59
- Qriton CLI is for work that should stay on infrastructure you control, with the model treated as something you can switch and, for HLM and Energy Language, inspect.
75
+ ## What stays on your machine
60
76
 
61
- | | Qriton CLI | Claude Code | Codex CLI | Aider | Cursor |
62
- |---|---|---|---|---|---|
63
- | Form | Terminal | Terminal | Terminal | Terminal | IDE |
64
- | Model | On your machine through Ollama, or xAI, Anthropic, OpenAI, and any OpenAI-compatible API | Claude | OpenAI | On your machine, or an API you select | Selected hosted models in the editor |
65
- | One session across models | Yes. `/model` keeps the transcript, approvals, and memory | Within Claude | Within OpenAI | Yes | Yes |
66
- | What is retained | A graph of facts, with revisions, plus the session | Instructions and session notes | Project instructions | The repository, through git | The codebase in the editor |
67
- | The model itself | HLM can apply a reversible memory overlay. Energy Language can edit a Hopfield checkpoint | The coding model is the product | The coding model is the product | The coding model is the product | The coding model is the product |
68
- | Choose it for | A local session, a record of what was decided, and direct operations on a local model | Claude as the coding system | Codex in the terminal | Git-centred pairing with a model you choose | An editor built around the agent |
77
+ With a local model, your prompts and the files Qriton reads never leave your computer. When you pick a hosted model (Claude, OpenAI, Grok), the conversation and the files it reads are sent to that provider. API keys are stored in the macOS Keychain, libsecret on Linux, or a private file, never in your project or configuration.
69
78
 
70
- The table describes the shape of each product. It is not a quality ranking.
79
+ Qriton's file tools only work inside the project folder you started it in. Commands run only as your approval mode allows, and a command you approve runs with your own permissions, so read it before you say yes. Simple reads inside the project run without asking.
71
80
 
72
- ## Another model
81
+ ## Choose a model
73
82
 
74
- The first session stays on this machine. To use another provider in that same session:
83
+ A plain name means a local Ollama model; a prefix selects a provider:
75
84
 
76
85
  ```bash
77
- qriton auth xai # https://console.x.ai
78
- qriton --model grok-4.6
79
- qriton --model grok-build-0.1
86
+ qriton --model qwen2.5-coder:7b # local, through Ollama
80
87
 
81
- qriton auth anthropic
88
+ qriton auth anthropic # save a key once
82
89
  qriton --model anthropic/claude-opus-5
83
90
 
84
91
  qriton auth openai
85
92
  qriton --model openai/gpt-5-mini
93
+
94
+ qriton auth xai
95
+ qriton --model grok-4.6
86
96
  ```
87
97
 
88
- `qriton auth` stores a key in the macOS Keychain, libsecret, or a private file on this machine. The same names work as `XAI_API_KEY`, `ANTHROPIC_API_KEY`, and `OPENAI_API_KEY`. An OpenAI-compatible server needs no extra adapter:
98
+ Any OpenAI-compatible server works too (OpenRouter, Groq, vLLM, LM Studio):
89
99
 
90
100
  ```bash
91
- export OPENAI_BASE_URL=https://openrouter.ai/api/v1 # also Groq, vLLM, LM Studio
101
+ export OPENAI_BASE_URL=https://openrouter.ai/api/v1
92
102
  ```
93
103
 
94
- Set `network.allowHostedFallback` in user configuration when a hosted model should be available alongside Ollama. A managed machine can run shell, Git, and Python through the container profile in the [deployment guide](docs/production-operations.md).
104
+ Switch at any time with `/model <name>`, or browse with `/models`; the conversation carries over. A practical pattern is to explore with a local model, switch to a hosted one for a hard change, and switch back.
95
105
 
96
- Check everything is wired up:
106
+ **Ollama on another computer.** `/servers` finds Ollama servers on your local network, and `/server <url>` selects one. Qriton checks it and remembers it.
97
107
 
98
- ```bash
99
- qriton doctor
100
- ```
108
+ **If a model stops responding.** Qriton retries a dropped connection, timeout or overloaded service by itself. You can also list backup models; Qriton then asks before switching, or switches on its own and tells you (see [Configuration](#configuration)).
101
109
 
102
- ## Use
110
+ ## Everyday use
103
111
 
104
112
  ```bash
105
- qriton # interactive
106
- qriton "why does the build fail" # interactive, with a first prompt
107
- qriton -p "list the exported types" # answer once, print, exit
108
- qriton -p --mode auto-edit "fix the typo" # allow file edits without a prompt
109
- qriton --plan "how would I add auth" # read-only investigation
110
- qriton -C ~/code/other-project # work somewhere else
111
- qriton --continue # resume the latest session here
112
- qriton resume # same
113
- qriton --image shot.png "what is wrong here"
113
+ qriton # interactive session
114
+ qriton "why does the build fail" # start with a question
115
+ qriton -p "list the exported types" # answer once, print, exit
116
+ qriton -p --mode auto-edit "fix the typo in README"
117
+ qriton --plan "how would I add login" # investigate without changing anything
118
+ qriton --continue # resume the last session here
119
+ qriton --image screenshot.png "what is wrong here"
114
120
  ```
115
121
 
116
- ### Approval modes
122
+ While Qriton works you can type an addition or correction and press Enter; it joins the task at the next safe step. `Esc` interrupts. `Ctrl+C` twice or `/exit` quits.
117
123
 
118
- Writes and shell commands are confirmed before they run. Use `/auto on` to run them without approval prompts for this session, and `/auto off` to restore confirmations. `/auto` toggles, and `Shift+Tab` cycles modes only when the composer is empty and idle. In an open list it moves to the previous choice. The footer always shows the current mode and auto-run status.
119
-
120
- [Network policy](docs/network-policy.md) can limit destinations to this machine or to an exact list of origins. A restricted profile runs shell, Git, and Python through the [container profile](docs/production-operations.md).
121
-
122
- You can also use `/mode` or a startup flag:
124
+ ### Approval modes
123
125
 
124
- | Mode | Files | Shell |
126
+ | Mode | File changes | Commands |
125
127
  |---|---|---|
126
- | `suggest` (default) | confirm | confirm |
127
- | `auto-edit` | apply | confirm |
128
+ | `suggest` (default) | ask | ask |
129
+ | `auto-edit` | apply | ask |
128
130
  | `full-auto` (`--yolo`) | apply | run |
129
131
  | `plan` (`--plan`) | blocked | blocked |
130
132
 
131
- At an approval prompt: `y` approve, `a` always allow that kind, `n` reject, `v` expand the preview. Or use `Tab`/`Shift+Tab` or `←`/`→` to select a bracketed choice and `Enter` to confirm it. The initial selection is approve once; `Esc` always rejects. Use `↑`/`↓` or `Page Up`/`Page Down` to inspect long previews. The input draft is preserved while the approval owns the keyboard.
132
-
133
- ### Models
134
-
135
- `/models` opens a searchable list across the available backends. OpenAI coding models appear by newest family first; the current model is marked without being moved above newer choices. Audio, image, embedding and other specialized endpoints are excluded, and dated snapshots are hidden when a rolling alias is available. Type to filter, use arrows or `Tab`/`Shift+Tab` to move, then `Enter` to switch. Browsing does not warm or load a model; selection uses the normal model-switch flow. `Esc` returns to the draft. `/model <name>` also switches directly, keeping the transcript and memory:
136
-
137
- ```
138
- /model grok-4.6
139
- /model grok-build-0.1
140
- /model anthropic/claude-opus-5
141
- /model openai/gpt-5.6-sol
142
- /model qwen2.5-coder:7b bare names mean Ollama
143
- ```
133
+ Change mode with `/mode`, or cycle with `Shift+Tab` when the input is empty. `/auto on` runs everything without prompts for the current session, and `/auto off` turns prompts back on. The footer always shows the current mode.
144
134
 
145
- A bare `claude-*`, `gpt-*`, or `grok-*` routes correctly without the prefix. Ollama names containing slashes, like `hf.co/user/repo`, are left alone.
135
+ At an approval: `y` approves once, `n` rejects, `a` always allows what the prompt describes (for a command, only that exact command) for the rest of the session, `v` expands a long preview.
146
136
 
147
- A practical division of work is to inspect with a local model, switch to a hosted model for the edit, and switch back. The session is unchanged.
137
+ For `-p` runs nobody is there to approve, so actions that would need approval are rejected. Use `--mode auto-edit` to allow file edits, or `--mode full-auto` for unattended commands.
148
138
 
149
- OpenAI reasoning models use the Responses API, including Codex and GPT-5.6 tool calls. Requests use `store: false`; encrypted reasoning continuity stays in the local session and is replayed only to the same endpoint and model. Custom OpenAI-compatible endpoints retain Chat Completions. `/models` lists what the configured account offers. See [OpenAI's migration guide](https://developers.openai.com/api/docs/guides/migrate-to-responses).
139
+ ## Memory
150
140
 
151
- ### Ollama servers and local feedback
141
+ Qriton keeps a memory of your project across sessions: conventions, decisions, facts that were hard to find. Ask it to remember something, or use `/remember`. Corrections keep the earlier wording, and forgotten facts can be restored.
152
142
 
153
- `/servers` opens a choice between checking this computer and scanning the local network. `/servers local` checks `127.0.0.1:11434`; `/servers scan` checks up to 255 addresses on attached private IPv4 subnets, on port 11434, with eight probes at a time and short timeouts. Large subnets are limited to the surrounding /24. A scan can miss servers on other ports, other subnets, IPv6, or behind a firewall. Discovery checks version and model metadata only; it does not load models or send prompts. Use Escape to cancel.
154
-
155
- Choose a discovered server with Enter, or use `/server <url>`. Qriton verifies it and saves the Ollama address; `/models` shows models from that server with its address. The coding model stays as it is until you select one. A private IPv4 server you choose may use HTTP. Other remote services use HTTPS. To expose an Ollama server to your LAN, configure its bind address as described in the [Ollama FAQ](https://docs.ollama.com/faq#how-can-i-expose-ollama-on-my-network).
156
-
157
- `/feedback` opens a multiline feedback composer. Enter saves, Ctrl+J adds a line, and Escape cancels. `/feedback <text>` saves directly. Reports are private files under `~/.qriton/feedback/` (or `$QRITON_HOME/feedback/`), containing only what you type, the Qriton version, timestamp and report ID. Conversation history, credentials and workspace files are not attached. Feedback is separate from project memory and is never uploaded; no feedback API is configured.
158
-
159
- ### Commands
160
-
161
- Type `/` to discover commands. `↑`/`↓` moves the highlighted suggestion, `Tab` fills it, and `Esc` closes suggestions without clearing the draft. `Enter` fills a partial command first; press it again to run the completed command. Common options are suggested too: try `/theme `, `/mode `, `/auto `, `/queue ` or `/auth `.
162
-
163
- `/sessions` opens a searchable list of conversations in the current workspace. Filter by title, model or ID; use arrows or `Tab`/`Shift+Tab` to navigate, `Enter` to resume, and `Esc` to return. The footer shows shortcuts for the active control. See [terminal interaction principles](docs/terminal-interaction.md) for the keyboard contract and current scope.
164
-
165
- | | |
166
- |---|---|
167
- | `/help` | commands and shortcuts |
168
- | `/theme light\|dark` | switch and save colors for a white or dark terminal background |
169
- | `/queue [pause\|resume\|clear]` | inspect, pause, resume, or cancel pending instructions |
170
- | `/model <name>` | switch chat model, any backend |
171
- | `/fast <name>` | switch the fast model (memory, compact) |
172
- | `/models` | browse, filter and select a chat model |
173
- | `/auth` | which API keys are stored |
174
- | `/usage` | token and cost log |
175
- | `/sessions` | browse, filter and resume saved conversations here |
176
- | `/save` | save the current conversation or retry a failed save |
177
- | `/resume [id]` | continue a saved session |
178
- | `/image <path>` | attach a screenshot to the next message |
179
- | `/pull <name>` | download a local model |
180
- | `/mode <mode>` | change approval mode |
181
- | `/auto [on\|off]` | toggle automatic writes and commands for this session |
182
- | `/policy` | inspect effective configuration, trust and managed limits |
183
- | `/memory` | graph stats and recent entries |
184
- | `/capabilities` | configured features, optional HLM installations and commands to try; no model load |
185
- | `/energy [command]` | inspect, preview, apply, evaluate and restore HLM checkpoint edits |
186
- | `/hlm [command]` | Qriton HF models, local completion, frozen/active comparison and reviewed factual-memory edits |
187
- | `/memory probe <query>` | compare plain and Hopfield recall without reinforcing memories |
188
- | `/recall <query>` | search memory |
189
- | `/remember <text>` | save a pinned memory yourself |
190
- | `/forget <id>` | drop a memory |
191
- | `/sweep` | forget everything that has faded |
192
- | `/unload` | free the memory local models are holding |
193
- | `/stats` | context use, tokens per second, active backends |
194
- | `/clear` | reset the conversation |
195
-
196
- The composer stays at the bottom of the terminal and grows up to six lines. Longer drafts scroll around the cursor. `Ctrl+J` inserts a newline, and a trailing `\` continues a line. `↑`/`↓` move within multiline drafts or walk prompt history on a single line. `Page Up`/`Page Down` scroll the conversation; reaching the bottom resumes following new output. `Esc` interrupts a running turn, and `Ctrl+C` twice exits. The interactive UI uses the alternate screen and restores your terminal on exit; saved sessions retain the conversation.
197
-
198
- Use `/theme light` on a white terminal background for dark body text and readable secondary text. The input uses a native blinking caret on supported terminals, with no application animation timer. The terminal controls its blink timing and any fade effect.
199
-
200
- You can type an addition or correction while Qriton works and press **Enter**. The pending instruction appears above the composer and joins the current task at the next safe step. Actions that have not started are deferred until the model has considered the update; a running tool finishes first. **Esc** interrupts immediately and pauses pending input. `/queue` shows pending instructions, `/queue pause` holds them, `/queue resume` continues, and `/queue clear` cancels them. Failed or interrupted turns pause remaining requests. If the current operation cannot receive updates, pending requests run afterward, one at a time. `/exit` also works during a running turn. Approval dialogs retain their decision keys, and settings commands wait until the agent is idle with no pending requests.
201
-
202
- The pending queue holds up to ten requests for the current session; it is not restored after exit. Once an update is added to the task, it becomes part of the normal saved conversation. A full queue leaves your draft intact.
203
-
204
- When a model ends an execution request with a routine chat question such as “approve these edits to continue,” Qriton makes one recovery attempt directing it to concrete tool calls. The UI shows this handoff. The reminder grants no permission and leaves the selected approval mode unchanged. Missing choices, credentials, plan-only requests and consequential actions still need the appropriate user input; rejected tools are never unblocked by this recovery. A repeated stall reports unfinished work instead of looping or claiming completion.
205
-
206
- Unattended runs reject actions that need approval in `suggest` mode. Choose `--mode auto-edit` for file edits or `--mode full-auto` for explicitly unattended shell work. `--plan` blocks writes even if a model emits an unadvertised tool call. Exit codes are 0 for completion, 3 for rejected actions, 130 for interruption, and 1 for provider errors, truncation, a repeated approval stall, or an exhausted step limit.
207
-
208
- Resuming a session restores its model unless `--model` overrides it. The current invocation's approval mode remains in force. `-C` selects both the workspace and its project configuration.
209
-
210
- ## HLM and Energy Language
211
-
212
- Both are optional and run locally. Python and PyTorch are installed separately. The model conducting the coding session is unchanged.
213
-
214
- HLM keeps a published base model frozen and stages a memory overlay. `qriton hlm catalog` lists the releases. The [walkthrough](docs/hlm.md) covers setup.
215
-
216
- ```sh
217
- qriton hlm compare hlm5-1b "The capital of Veldoria is"
218
- qriton hlm preview hlm5-1b examples/hlm/memorize.hlm examples/hlm/controls.json
219
- qriton hlm apply <proposal-id>
220
- qriton hlm evaluate <proposal-id>
221
- qriton hlm restore <proposal-id>
143
+ ```text
144
+ /remember prices are integer euro cents, never floats
145
+ /memory what is stored, recent entries
146
+ /recall <query> search memory
147
+ /forget <id> drop a memory (/restore <id> brings it back)
222
148
  ```
223
149
 
224
- Energy Language does the reversible edit for a supported Hopfield checkpoint, using a bounded script. The [guide](docs/energy.md) covers the runtime and the evaluation suite. Apply and restore ask for approval.
150
+ Memory is kept per project and stays on your machine. With the embedding model installed (`qriton pull bge-m3`), recall also finds related facts that use different words.
225
151
 
226
- ```sh
227
- qriton energy doctor
228
- qriton energy inspect models/model.pt
229
- qriton energy preview models/model.pt examples/energy/edit.hlm
230
- qriton energy apply <proposal-id>
231
- qriton energy evaluate <proposal-id>
232
- qriton energy restore <proposal-id>
233
- ```
152
+ ## Commands
234
153
 
235
- ## Tools
154
+ Type `/` for suggestions. The most used:
236
155
 
237
- | Tool | What it does |
156
+ | | |
238
157
  |---|---|
239
- | `read_file`, `write_file`, `edit_file` | read, create, and patch files |
240
- | `list_dir`, `glob`, `grep` | explore and search the workspace |
241
- | `shell` | run commands, with a denylist and a timeout |
242
- | `git_status`, `git_diff`, `git_commit` | inspect and commit; commits need an explicit file list |
243
- | `web_search`, `fetch_url` | find pages, read one page |
244
- | `research` | search, crawl, rank, and cite |
245
- | `remember`, `recall` | save and retrieve memories |
246
- | `update_memory`, `forget` | correct or drop a memory |
247
- | `link_memory`, `memory_graph` | connect memories, inspect connections |
248
- | `plan` | track a multi-step task |
249
-
250
- Read-only tools run in parallel and never prompt. Everything else is serialised behind approval.
158
+ | `/help` | all commands and shortcuts |
159
+ | `/model <name>`, `/models` | switch or browse models |
160
+ | `/mode <mode>`, `/auto [on\|off]` | change approval mode |
161
+ | `/sessions`, `/resume [id]` | browse and continue past conversations |
162
+ | `/memory`, `/remember`, `/recall`, `/forget` | project memory |
163
+ | `/hlm` | run and edit Qriton HLM models |
164
+ | `/servers`, `/server <url>` | find or select an Ollama server |
165
+ | `/image <path>` | attach a screenshot to your next message |
166
+ | `/compact` | summarise the conversation to free space |
167
+ | `/stats`, `/usage` | speed, context use, token and cost log |
168
+ | `/unload` | free the memory local models are using |
169
+ | `/theme light\|dark` | colours for a light or dark terminal |
170
+ | `/clear` | start over |
171
+
172
+ From the shell: `qriton hlm`, `qriton models`, `qriton sessions`, `qriton usage`, `qriton doctor`, `qriton capabilities`.
251
173
 
252
174
  ## Configuration
253
175
 
254
- `~/.qriton/config.json`, or `.qriton/config.json` in a project to override per workspace. Project configuration requires an explicit grant: run `qriton trust show`, review the file, then `qriton trust grant <fingerprint>`. Changes require a new grant. `qriton doctor policy` inspects effective settings and their origins offline; `/policy` shows the active session. See [workspace configuration trust](docs/workspace-trust.md).
255
-
256
- `qriton` already starts on `qwen3.5:4b`. Save this file to keep an 8K context and embeddings for later sessions. `qriton --light` still applies the bounded session for a single run, with keyword memory for that run. The `model` field also accepts `grok-4.6`, `anthropic/claude-opus-5`, `openai/gpt-5-mini`, or any model served through `OPENAI_BASE_URL`.
176
+ Settings live in `~/.qriton/config.json`. A project can add its own `.qriton/config.json`; for safety, Qriton ignores it until you review and approve it with `qriton trust show` and `qriton trust grant <fingerprint>`, and asks again whenever it changes.
257
177
 
258
178
  ```jsonc
259
179
  {
260
180
  "model": "qwen3.5:4b",
261
- "fastModel": "qwen3.5:4b", // summarising, memory extraction
262
- "embedModel": "bge-m3:latest",
263
- "keepAlive": "30s", // how long Ollama retains the model
264
- "releaseOnExit": true, // release the model when Qriton exits
265
- "contextTokens": 8192,
266
- "reasoning": "off",
267
- "maxOutputTokens": 1024, // ceiling per step
268
- "maxSteps": 8,
269
181
  "approvalMode": "suggest",
270
- "search": { "backend": "auto", "fetchTopN": 4 },
271
- "memory": { "seedK": 8, "hops": 1, "recallLimit": 10, "autoCapture": true, "embeddings": true, "hopfield": true }
182
+ "contextTokens": 16384,
183
+ "verifyEdits": true, // ask the model to test its change before it says it is done
184
+ "fallback": {
185
+ "retries": 3, // retry a failed request on the same model
186
+ "models": ["qwen3.5:4b"], // then try these backups, in order
187
+ "switch": "ask" // "ask" before switching, or "auto"
188
+ }
272
189
  }
273
190
  ```
274
191
 
275
- `qriton pull bge-m3` fills `embedModel`. With embeddings on, `/memory probe` can compare plain recall and the Hopfield reading.
276
-
277
- ### Environment
192
+ A backup that sends your conversation from a local model to a hosted provider also needs `"network": { "allowHostedFallback": true }`. In `-p` runs only `"auto"` can switch.
278
193
 
279
- | | |
194
+ | Environment variable | |
280
195
  |---|---|
281
- | `OLLAMA_HOST` | Ollama server, default `http://127.0.0.1:11434` |
282
- | `QRITON_MODEL` | override the chat model |
283
- | `XAI_API_KEY` | use Grok models |
284
- | `ANTHROPIC_API_KEY` | use Claude models |
285
- | `OPENAI_API_KEY` | use OpenAI models |
286
- | `OPENAI_BASE_URL` | any OpenAI-compatible server |
287
- | `TAVILY_API_KEY` / `BRAVE_API_KEY` | better search ranking |
288
- | `SEARXNG_URL` | use your own SearXNG instance |
289
- | `QRITON_DEBUG=1` | debug log at `~/.qriton/debug.log` |
196
+ | `OLLAMA_HOST` | Ollama server (default `http://127.0.0.1:11434`) |
197
+ | `QRITON_MODEL` | model for this run |
198
+ | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `XAI_API_KEY` | provider keys |
199
+ | `OPENAI_BASE_URL` | an OpenAI-compatible server |
200
+ | `TAVILY_API_KEY`, `BRAVE_API_KEY`, `SEARXNG_URL` | better web search |
290
201
 
291
- ### Project instructions
202
+ **Project instructions.** Put a `QRITON.md` in your project root and it is read at the start of every session. `AGENTS.md` and `CLAUDE.md` work too.
292
203
 
293
- Drop a `QRITON.md` in the repo root and it is loaded into every session. `AGENTS.md` and `CLAUDE.md` are picked up too.
204
+ ## Several qritons on one network
294
205
 
295
- ## How it fits together
206
+ Qriton instances on different machines can see each other and pass messages, for example asking the one on your Windows box to run the tests there. They meet through a [NATS](https://nats.io) server: any machine on your local network, or a relay on the internet ([Azure setup](https://unpkg.com/qriton/deploy/nats/README.md) is one option).
296
207
 
297
- ```
298
- cli.tsx ──► Agent ──► ProviderRegistry ──► Ollama (local, streaming)
299
- │ ├─► xAI (Grok)
300
- │ ├─► Anthropic (official SDK)
301
- │ └─► OpenAI (official SDK, or any compatible API)
302
- │
303
- ├─► ToolRegistry ──► fs · shell · web · memory · plan
304
- │
305
- ├─► MemoryStore ──► nodes, edges, revisions, full-text search
306
- │ vectors held in memory, cosine ranked
307
- │
308
- ├─► Embedder ──► bge-m3 through the configured Ollama server
309
- │
310
- ├─► HLM ──► frozen base model, reversible memory overlay
311
- │
312
- └─► Energy ──► reversible edits to a Hopfield checkpoint
208
+ ```bash
209
+ qriton mesh init nats://10.0.0.5:4222 # first machine: creates a group, prints an invite code
210
+ qriton mesh join <code> # every other machine
313
211
  ```
314
212
 
315
- Every provider normalises to one event stream, so the agent loop never learns which backend it is talking to. The translation each one needs is real, though: Anthropic takes the system prompt as a top-level parameter and requires all parallel tool results in a single user message, while OpenAI takes one message per result with a `tool_call_id`.
213
+ Then set `"mesh": { "enabled": true, "name": "laptop" }` in `~/.qriton/config.json` on each machine. In a session, `/peers` shows who is online (machine, project, model, busy or idle, and a fingerprint), `/tell <peer> <text>` sends a message, and `/mesh scan` finds NATS servers on your network. The model can also list peers and send messages; sending asks for approval unless you run in `full-auto`.
316
214
 
317
- The system prompt is built once per session and never rewritten. Ollama caches the prompt prefix between requests, and changing the system message would force a full reprocess of several thousand tokens on every step. Per-turn content such as recalled memories goes into the user message instead, so history only ever grows and the cache keeps paying off.
215
+ **Everything is end-to-end encrypted.** Each machine has its own keys, and every message is encrypted and signed before it leaves, so the NATS server, or anyone on the network, sees only random bytes on random-looking channels. Direct messages can be read by their recipient only, not even by other machines in the group. The invite code contains the group secret, so pass it only over a channel you trust. A relay on the internet also needs `tls://`, and per-machine keys (`qriton mesh status` prints the one to add to the server).
318
216
 
319
- When the transcript passes 75% of the context window, the older half is summarised by the fast model and recent turns are kept verbatim.
217
+ A received message is shown to you and waits for `/accept`. With `"accept": "auto"` it joins the task queue on its own, so qritons can coordinate work without you in the loop. Either way it is labelled as coming from another agent, never from you: it grants no permission, and every action still goes through your approvals. The mesh is off unless you configure it, and a project can never turn it on.
320
218
 
321
- Models without native tool support use fenced `tool` blocks.
219
+ ## Teams and managed machines
322
220
 
323
- ## Speed
221
+ Administrators can restrict network destinations, allowed approval modes and which project settings apply, and can run commands in a network-isolated container. For the deployment guide, write to **cli@qriton.com**.
324
222
 
325
- Most of the elapsed time is model inference. The first turn sends roughly a 3,600-token prefix, covering the system prompt and tool schemas. Later turns send only the new tokens. Two measurements describe the result:
223
+ ## Troubleshooting
326
224
 
327
- | | |
328
- |---|---|
329
- | prompt processing | how long before the first token appears |
330
- | token generation | how fast the answer streams |
331
-
332
- `/stats` shows tokens per second after each turn. `--light` shortens local turns, and `maxOutputTokens` caps each step.
333
-
334
- ### Context budget
335
-
336
- Qriton compacts automatically before the next request exceeds its estimated input budget. It keeps complete tool exchanges that fit, preserves the newest user instructions and attachments, and carries a bounded record of the task plan into the summary. Large file reads no longer force the last eight messages to stay in context. Long tool results show an explicit shortening notice; request narrower file ranges or filtered command output to recover omitted detail.
337
-
338
- The summary request uses the fast model's context window. Compaction leaves the system prompt stable and does not change approval mode. `/compact` requests it manually, and `/stats` shows estimated usage.
339
-
340
- ### Memory pressure
341
-
342
- A local model resides in memory alongside the other processes on the machine:
343
-
344
- - The model is **released when qriton exits**, rather than staying pinned for the rest of its keep-alive. Turn this off with `"releaseOnExit": false`.
345
- - `keepAlive` defaults to 10 minutes, so a resumed turn does not reload the model immediately.
346
- - The embedding model gets its own 2-minute keep-alive, because it loads in under a second.
347
- - Switching models with `/model` releases the one you left.
348
- - `/unload` releases resident models without ending the session.
225
+ - **Nothing happens, or the model doesn't load:** `qriton doctor`.
226
+ - **Slow or out of memory:** try `qriton --light`, a smaller model, or `/unload` between tasks. Local models are released when Qriton exits.
227
+ - **A long session runs out of room:** `/compact` summarises it, or raise `contextTokens`.
228
+ - **Answers stop mid-way:** raise `maxOutputTokens`.
229
+ - **Keys:** `/auth` shows which keys are stored; `qriton auth <provider>` saves one.
349
230
 
350
- `--light` uses an 8K context, four CPU inference threads, 1,024 output tokens per step, eight steps per turn and thinking off. Main and fast tasks use the same model. Keyword and graph recall stay available, and chat residency expires after 30 seconds idle.
231
+ ## Security
351
232
 
352
- A hosted model leaves local inference unloaded. With `--model openai/gpt-5-mini` or `--model anthropic/claude-opus-5`, the only local model left is the embedder, and only while it is working.
353
-
354
- The `reasoning` setting chooses whether a model's scratchpad is shown in its own channel or left inline. `"on"` keeps the scratchpad separate from the reply.
355
-
356
- ## Development
357
-
358
- Local [Shield scanning](docs/shield.md) checks retrieved content and withholds recognized credentials. `qriton shield status` and `qriton shield scan SKILL.md` run offline.
359
-
360
- ```bash
361
- npm run dev # esbuild watch
362
- npm test # unit tests
363
- npm run typecheck
364
- ```
365
-
366
- `qriton memory reembed` refreshes stored vectors with the current embedder and keeps each fact's history.
233
+ Please report vulnerabilities privately to **cli@qriton.com**, not in a public issue. The full policy is in `SECURITY.md`, included in the package.
367
234
 
368
235
  ## License
369
236
 
370
237
  MIT
371
-
372
- The [deployment guide](docs/production-operations.md) covers installation, the container profile, memory authorization, backup and restore, and rollback.
package/SECURITY.md ADDED
@@ -0,0 +1,31 @@
1
+ # Security policy
2
+
3
+ ## Reporting a vulnerability
4
+
5
+ Please report security problems privately to **cli@qriton.com**. Do not open a public issue for a suspected vulnerability.
6
+
7
+ Include what you can:
8
+
9
+ - the qriton version (`qriton --version`), operating system and Node version;
10
+ - the approval mode, execution profile (host or container) and network policy in use;
11
+ - steps to reproduce, using synthetic secrets and a disposable workspace, never real credentials or private code;
12
+ - what you expected and what happened.
13
+
14
+ You will receive an acknowledgement, and we will agree on disclosure timing with you. Please give us a reasonable chance to release a fix before disclosing publicly.
15
+
16
+ ## Supported versions
17
+
18
+ Security fixes are released for the latest published version only. Upgrade before reporting if you can.
19
+
20
+ ## Scope
21
+
22
+ In scope: anything that lets repository content, model output, web content or tool output
23
+
24
+ - run commands, write files or read files outside the workspace without the approval the selected mode requires;
25
+ - bypass workspace trust, managed policy, network policy or the container execution profile;
26
+ - read or write memory outside the permitted scopes;
27
+ - send credentials or workspace content to a destination the policy does not allow.
28
+
29
+ Out of scope: actions a user explicitly approved or ran in `full-auto` mode, a compromised host account or administrator, host execution mode used as an isolation boundary (it is a compatibility mode, not a sandbox), and Shield pattern detection missing a phrasing (it is heuristic and not an authorization boundary).
30
+
31
+ Organisations evaluating qriton can request the deployment guide and a description of its security boundaries from **cli@qriton.com**.
package/THIRD_PARTY_NOTICES.md CHANGED
@@ -1,3 +1,9 @@
1
+ # Bundled NATS client
2
+
3
+ The CLI bundles the NATS client for its optional mesh feature: @nats-io/transport-node 3.4.0, @nats-io/nats-core 3.4.0, @nats-io/nkeys 2.0.3 and @nats-io/nuid 3.0.0, all Copyright The NATS Authors and licensed under the Apache License, Version 2.0 (the full text appears below). The packages ship no NOTICE file. They are used unmodified.
4
+
5
+ @nats-io/nkeys depends on tweetnacl 1.0.3, released into the public domain under the Unlicense (https://unlicense.org).
6
+
1
7
  # Bundled Qriton Shield
2
8
 
3
9
  The CLI bundles local scanner code from @qriton/shield 3.3.0 (Apache-2.0). The integration calls its standalone scanners and adapts their output; it does not modify the upstream package.