@sol-merrai/cli 0.2.0 → 0.10.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 CHANGED
@@ -62,10 +62,17 @@ Installed-package `.env` files are not loaded.
62
62
  merrai health
63
63
  merrai session
64
64
  merrai account usage
65
- merrai memory add|search|list|profile|by-date|status|clear
65
+ merrai memory add|search|list|profile|by-date|open-items|judgments|style|status|clear|clear-status
66
+ merrai memory backfill start|status
67
+ merrai memory synthesis start|status
68
+ merrai lobe create|list|update
69
+ merrai topic list|set|retire
66
70
  merrai entity find|memories
67
- merrai document list|get
71
+ merrai document list|get|retry-rebuild|retry-backfill
68
72
  merrai ingest memories|chat|chats
73
+ merrai sources list|show|retry|reprocess|delete
74
+ merrai ingestion status|retry
75
+ merrai apps list|show|call|open|create|pull|push|publish
69
76
  merrai auth set-key|status|logout
70
77
  merrai debug rpc
71
78
  ```
@@ -74,37 +81,295 @@ Examples:
74
81
 
75
82
  ```bash
76
83
  merrai memory add "Met Sarah at lunch"
84
+ merrai memory add "The Atlas budget is $4,000" --lobe project-alpha
77
85
  merrai memory search "What did Sarah suggest?" --limit 10
78
86
  merrai memory by-date --start "2026-07-01T00:00:00Z"
87
+ merrai memory search --topic work --stance view --stance decision
88
+ merrai memory search "Acme revenue" --lobe deal-acme --about other
89
+ merrai memory open-items --until 2026-12-31
90
+ merrai memory judgments --evidence-changed
91
+ merrai memory style
92
+ merrai memory profile --lobe deal-acme
93
+ merrai memory list --lobe work --limit 20
79
94
  merrai entity find "Sarah" --type person
80
- merrai entity memories ent_123
81
- merrai document list
82
- merrai document get lvd_123
95
+ merrai entity memories ent_01J00000000000000000000000
96
+ merrai document list --limit 20 --offset 0
97
+ merrai document get lvd_01J00000000000000000000000 --max-characters 12000
83
98
  merrai memory clear people --yes
99
+ merrai lobe create project-alpha
100
+ merrai lobe list
101
+ merrai lobe update deal-acme --purpose "Evaluate Acme for a seed investment"
102
+ merrai topic list --lobe deal-acme
103
+ merrai topic set risks "Risks to the investment and open concerns" --lobe deal-acme
104
+ merrai topic retire food_and_drink --lobe deal-acme
105
+ merrai memory backfill start
106
+ merrai memory backfill status --lobe deal-acme
107
+ merrai sources list --status partial failed --limit 20
108
+ merrai sources show ent_01J00000000000000000000000
109
+ merrai sources retry ent_01J00000000000000000000000
110
+ merrai sources reprocess ent_01J00000000000000000000000
111
+ merrai sources delete ent_01J00000000000000000000000 --yes
112
+ merrai ingestion status miw_01J00000000000000000000000_01J00000000000000000000000
113
+ merrai ingestion retry miw_01J00000000000000000000000_01J00000000000000000000000
84
114
  ```
85
115
 
86
116
  `memory clear` confirms interactively and requires `--yes` in noninteractive
87
- use.
117
+ use. A custom lobe must be created explicitly before any memory write uses it.
118
+ Clearing runs as durable server work: the command follows it, printing
119
+ progress on stderr, and prints the final status (`deleted` memories,
120
+ `deletedSources`, `remainingSources`) once it completes. `--no-wait` returns as
121
+ soon as the clear has started; `memory clear-status <clearId>` follows it
122
+ later. Repeating the clear joins or resumes the one already running. A clear
123
+ that stopped exits with code `10`; running it again finishes it.
124
+
125
+ `memory backfill start` labels memories stored before Merrai labelled them
126
+ with topics, who they are about and their stance, for every lobe or one
127
+ (`--lobe`), then refreshes each lobe's profile. It runs as durable server
128
+ work; a start while one runs joins it, and labels already chosen for a lobe's
129
+ current topics and purpose are never chosen again. Changing a lobe's topics
130
+ or purpose (`topic set`, `topic retire`, `lobe update --purpose`) relabels
131
+ that lobe on its own. `memory backfill status` prints each lobe's state
132
+ (`queued`, `running`, `complete` or `failed`) and how many memories' evidence
133
+ it has labelled of those that needed it; a failed lobe is retried by the next
134
+ start. Backfill has no MCP tool: it changes stored labels.
135
+
136
+ While deleted sources are being removed from a living document, `document get`
137
+ returns no content and a summary saying the document is unavailable.
138
+ `document retry-rebuild <documentId>` retries that update when it failed.
139
+ When a document could not add the memories already saved in lobes added to
140
+ it, `document retry-backfill <documentId>` retries that.
141
+
142
+ `sources list` reports each source's processing status (`pending`,
143
+ `processing`, `partial`, `failed`, `complete`, or `deleted` when asked for with
144
+ `--status deleted`), memory count, available actions and `origin`: where it
145
+ came from. A Merrai agent chat is `app` (web, desktop or mobile), `voice`,
146
+ `telegram`, `whatsapp`, `slack`, `discord` or `linear`; a synced chat, or a
147
+ chat the Claude Code plugin imported, is its provider (`chatgpt`,
148
+ `claude-code`, `codex`…); `granola` and `upload` are themselves; a saved entry
149
+ is `app`, `mcp`, `api` (an API key: this CLI, the Claude Code plugin or a
150
+ script) or `onboarding`. `origin` is `null` when Merrai did not record it (some
151
+ older sources) and once a source is deleted. Text output adds `from <origin>`
152
+ when it says more than the kind or provider, and `sources show` prints a
153
+ `From:` line. It filters with
154
+ `--kind`, `--provider` and `--status`; pass the printed `nextCursor` JSON to
155
+ `--cursor` for the next page. A status-filtered page can hold fewer sources
156
+ than `--limit` while more remain. `sources delete` removes the source and the
157
+ memories that came only from it, and like `memory clear` requires `--yes` in
158
+ noninteractive use. `sources retry` re-extracts the parts a `partial` source
159
+ could not extract, as the Sources view's Retry does (`sourceArtifactRetry`);
160
+ repeating it before the retry starts returns the same ingestion, and once
161
+ nothing is retryable it exits `4` with `CONFLICT`. `sources reprocess`
162
+ processes a `failed` source again from the start, as the Sources view's
163
+ Reprocess does (`sourceArtifactReprocess`); any other source exits `4` with
164
+ `CONFLICT`. `ingestion status` follows the `ingestionId` a save or retry
165
+ returns; `ingestion retry` does the same retry for a finished partial
166
+ ingestion by its ID.
167
+
168
+ `apps` uses and builds App Artifacts, the small apps Merrai builds over your
169
+ connected accounts:
170
+
171
+ ```bash
172
+ merrai apps guide
173
+ merrai apps guide design
174
+ merrai apps list
175
+ merrai apps show aar_01J00000000000000000000000
176
+ merrai apps call aar_01J00000000000000000000000 query messages --input '{"limit":5}'
177
+ merrai apps open aar_01J00000000000000000000000
178
+ merrai apps create "Inbox pulse" --from ./inbox-pulse --publish -m "First Version"
179
+ merrai apps pull aar_01J00000000000000000000000 ./inbox-pulse
180
+ merrai apps push aar_01J00000000000000000000000 ./inbox-pulse -m "Add replies"
181
+ merrai apps publish aar_01J00000000000000000000000 --push ./inbox-pulse -m "Add replies"
182
+ ```
183
+
184
+ `apps guide` prints how to build an app from a folder (`authoring`, the
185
+ default) and how to design its UI (`design`); it is the same guide MCP's
186
+ `get_app_building_guide` and the public agent skill at
187
+ `/.well-known/agent-skills/merrai-build-apps/` serve, so a coding agent
188
+ should read it before writing an app. `apps show` lists the queries,
189
+ mutations and actions `apps call` can run, and the running app's recent
190
+ errors;
191
+ handlers an app marks `internal` are only for its own UI and are refused. A
192
+ handler that fails exits `6` with `CALL_FAILED`, and one Merrai refuses (a
193
+ tool the owner has not allowed, an archived app) exits `3` with
194
+ `CALL_REFUSED`. `apps open` prints a link that signs the browser in for about
195
+ a minute. `apps create --from` and `apps publish --push` upload every text
196
+ file in the folder except dotfiles, `.git`, `node_modules` and `.merrai`; the
197
+ folder needs an `app-artifact.json`. `apps pull` refuses a folder that is not
198
+ empty unless given `--force`. `apps push` saves the folder without publishing.
199
+ Pull, create and push record the source revision in `.merrai/revision`; a
200
+ later push from that folder is refused if someone changed the app meanwhile,
201
+ so pull again and redo the change. Version 1 may call every tool
202
+ `app-artifact.json` declares; later Versions keep the tools allowed then, and
203
+ a newly declared tool waits for you. Allowing or turning off tools, accounts
204
+ and archiving stay in the Merrai app.
205
+
206
+ `memory add`, `ingest`, `sources retry`, `sources reprocess` and `ingestion
207
+ retry` queue work rather than finish it. Their text output names the
208
+ ingestion and the `merrai ingestion status <id>` command that follows it; the
209
+ JSON output carries the same `ingestionId`.
210
+
211
+ `memory add --lobe <key>` saves into an existing lobe of the account (the
212
+ `main` lobe when omitted), as MCP `add_memory`'s `lobeKey` does. An unknown
213
+ lobe, including another account's, exits `4` with `NOT_FOUND` and saves
214
+ nothing; create the lobe first with `lobe create`.
88
215
 
89
216
  ## MCP parity
90
217
 
91
- Every Merrai MCP tool has a canonical CLI command and a compatibility spelling:
218
+ Merrai's memory and document tools have canonical CLI commands and compatibility spellings:
219
+
220
+ | MCP tool | Canonical command | Compatibility spelling |
221
+ | ----------------------- | ------------------- | --------------------------- |
222
+ | `add_memory` | `memory add` | `add-memory` |
223
+ | `search_memories` | `memory search` | |
224
+ | `get_memory_profile` | `memory profile` | `who-am-i`, `whoami` |
225
+ | `list_living_documents` | `document list` | `list-living-documents` |
226
+ | `read_living_document` | `document get` | `read-living-document` |
227
+ | `search_memories` | `entity find` | `find-entity` |
228
+ | `search_memories` | `entity memories` | `search-memories-by-entity` |
229
+ | `search_memories` | `memory by-date` | `search-memories-by-date` |
230
+ | `list_lobes` | `lobe list` | |
231
+ | `list_topics` | `topic list` | |
232
+ | `list_open_items` | `memory open-items` | |
233
+ | `list_judgments` | `memory judgments` | |
234
+ | `get_style_profile` | `memory style` | |
235
+
236
+ The source tools map to `ingestion_status` → `ingestion status` and
237
+ `list_sources` → `sources list`. The App Artifact tools map to
238
+ `search_app_artifacts` → `apps list`, `open_app_artifact` → `apps open`,
239
+ `call_app_artifact` → `apps call`, `get_app_building_guide` → `apps guide`,
240
+ `create_app_artifact` → `apps create`,
241
+ `read_app_artifact_source` → `apps pull`, `write_app_artifact_source` →
242
+ `apps push` and `publish_app_artifact` → `apps publish`.
243
+ `get_usage_guide` has no CLI command; it documents MCP use. `sources retry`, `sources reprocess` and
244
+ `sources delete` have no MCP tool: MCP is read-only for sources, and MCP tools never delete existing
245
+ memories. `search_sources` and `search_memories_and_sources` have no CLI
246
+ command yet; `debug rpc sourceSearch` and `debug rpc search` call the same
247
+ procedures. The CLI tests hold this mapping to every tool the MCP server
248
+ advertises.
249
+
250
+ The OAuth-only `get_setup_state` and `progress_setup` tools intentionally have no
251
+ CLI equivalent: a CLI API key has no MCP connection or connection-scoped saving
252
+ preference. MCP opt-out does not disable separately authorized CLI writes.
253
+
254
+ `get_usage_guide` is also MCP-only: it returns documentation for the MCP
255
+ interaction. CLI usage is documented here and through command `--help`.
256
+
257
+ The canonical commands share recall limits and defaults with MCP. `memory
258
+ search`, `memory by-date` and `entity memories` call `recall.searchMemories`,
259
+ the oRPC form of MCP `search_memories`: no model call, the same reply, and
260
+ each memory's update marks. `memory by-date` and `entity memories` keep their
261
+ default of 20 results; their `--limit` is 1-25, the shared maximum. MCP
262
+ `add_memory` additionally requires a policy-checked `saveReason`, while the CLI
263
+ submits the user's command directly. The CLI profile retains first-party refresh
264
+ diagnostics; the MCP profile only reads existing context and omits those fields.
265
+ `memory search` filters with `--topic` (repeat for any of several),
266
+ `--about owner|other|none` and `--stance reported|view|decision|inferred` (repeatable),
267
+ alone or with a query; `--lobe` searches one of your lobes instead of the
268
+ lobes your agent reads, as MCP's `lobeKey` does, and `memory profile --lobe`
269
+ reads that lobe's profile. `memory open-items` lists current memories with a
270
+ planned or due time not yet passed, and decisions still ahead, earliest first,
271
+ counted from today where the CLI runs (`--as-of` to choose the day, `--until`
272
+ to bound it). `memory judgments` lists current views and decisions, newest
273
+ first, with the facts each rests on or weighs against; `--evidence-changed`
274
+ keeps those whose facts changed. `memory style` shows how you write in one
275
+ lobe (`--lobe`, default `main`): up to 12 passages in your own words and a
276
+ summary citing them, never built from assistant text. `memory synthesis
277
+ start|status` rebuilds and reports each lobe's patterns and style; ingestion
278
+ asks for the same work on its own, debounced. `lobe list` lists your lobes oldest first,
279
+ as `{ lobes, nextCursor }` in JSON. All three page with `--limit` (1-50,
280
+ default 20) and the printed `--cursor`; an open-items cursor keeps its first
281
+ page's day.
282
+ `add-memory` preserves the older CLI-only `--source` option; the
283
+ other compatibility spellings are aliases for the canonical contract. They do
284
+ not emit deprecation warnings. Retrieval tuning (similarity threshold, query
285
+ rewriting, relations, source content) belongs to unified search: `debug rpc
286
+ search` with its `retrieval`, `include` and `budget` options.
287
+
288
+ ## Update marks
289
+
290
+ A later value never retires an earlier one: both stay current, and the newer
291
+ one carries an update mark. Text output shows each memory as Merrai's Search
292
+ does, with what it replaced and its marks under it:
92
293
 
93
- | MCP tool | Canonical command | Compatibility spelling |
94
- | --------------------------- | ----------------- | --------------------------- |
95
- | `add_memory` | `memory add` | `add-memory` |
96
- | `search_memory` | `memory search` | `search` |
97
- | `whoAmI` | `memory profile` | `who-am-i`, `whoami` |
98
- | `list_living_documents` | `document list` | `list-living-documents` |
99
- | `read_living_document` | `document get` | `read-living-document` |
100
- | `find_entity` | `entity find` | `find-entity` |
101
- | `search_memories_by_entity` | `entity memories` | `search-memories-by-entity` |
102
- | `search_memories_by_date` | `memory by-date` | `search-memories-by-date` |
294
+ ```text
295
+ - [fact] 2024-03-15: The patent filing budget is $3,500. [mem_01J0000000000000000000000A]
296
+ ↳ updated by: mem_01J0000000000000000000000B
297
+ - [fact] 2024-03-16: The patent filing budget is now $4,000. [mem_01J0000000000000000000000B]
298
+ replaces: mem_01J0000000000000000000000A
299
+ ```
103
300
 
104
- The canonical commands use the same input limits, defaults, and structured
105
- response DTOs as their MCP tools. `add-memory` and `search` preserve the older
106
- CLI-only options and response shapes; the other compatibility spellings are
107
- aliases for the canonical contract. They do not emit deprecation warnings.
301
+ `↳ updated by: …` names a newer value of something the memory states;
302
+ `replaces: …` names an earlier value it updates. A linked memory that is also
303
+ in the results is named by its id, which its own line carries; any other by
304
+ its text, when it happened or is due, and the day it was said:
305
+ `↳ updated by: The patent filing budget is now $4,000. (said 2024-03-16)`.
306
+
307
+ In JSON, each memory's `linked` lists the same marks: `relation`
308
+ (`updated_by` or `updates`), `id`, `content`, `eventTime` and `said`
309
+ (`YYYY-MM-DD` or `null`).
310
+
311
+ ### Changes in 0.10.0
312
+
313
+ - `sources list` and `sources show` carry each source's `origin` (where it
314
+ came from) in JSON, and the client's `SourceArtifact` adds
315
+ `origin: SourceOrigin | null`. Text output adds `from <origin>` to a listed
316
+ source when it says more than the kind or provider, for example
317
+ `agent_conversation from telegram`, and `sources show` prints
318
+ `From: <origin>`.
319
+
320
+ ### Changes in 0.9.0
321
+
322
+ - `memory add` accepts `--lobe` (and `--lobe-key`) and sends it as
323
+ `recall.addMemory`'s `lobeKey`; the server refuses a lobe the account does
324
+ not own.
325
+ - New `sources reprocess <id>` for a failed source.
326
+ - `ingest chats` no longer reads `extractionProfile` from its input, and the
327
+ client's `AddChatSessionsInput` drops it: extraction does not vary by
328
+ profile, so the server ignored it.
329
+ - `memory list` (and `memories`) reads one bounded page of current memories,
330
+ newest first: `{ items, nextCursor }` instead of every stored row.
331
+ Superseded, retracted and expired memories are no longer listed, and
332
+ `isCurrent`, `supersededByMemoryId` and `metadata` are gone; each memory
333
+ adds `recordedAt`, `replaces` and `linked`, and text output shows them as
334
+ `memory search` does. `--lobe`, `--limit` (1-100, default 50) and
335
+ `--cursor` (the printed `nextCursor` JSON) select the page. The client's
336
+ `memories` takes `MemoriesInput` and returns `MemoriesOutput`. CLI versions
337
+ before 0.9.0 cannot run `memory list` against a current server.
338
+ - Text output of `memory add`, `add-memory` and `ingest` names the queued
339
+ ingestion and `merrai ingestion status <id>` instead of "Memory queued." or
340
+ "Ingest queued.".
341
+
342
+ ### Changes in 0.8.0
343
+
344
+ - `entity memories` (and `search-memories-by-entity`) calls
345
+ `recall.searchMemories` with the entity id and returns MCP
346
+ `search_memories`' reply: `entity` becomes `matchedEntities[0]`, each memory
347
+ adds `replaces` and `linked`, and text output shows them under each memory.
348
+ An undated memory reads `undated`. `--limit` is 1-25 (default still 20);
349
+ above 25 is a usage error (exit `2`).
350
+ - The client drops `memoriesByEntity` and its types
351
+ (`MemoriesByEntityInput`/`Output`), which the server no longer serves. CLI
352
+ versions before 0.8.0 cannot run `entity memories` against a current server.
353
+
354
+ ### Changes in 0.7.0
355
+
356
+ - `memory search` returns MCP `search_memories`' reply. `memories` keeps its
357
+ fields and adds `linked`; the reply adds `appliedFilters`, `matchedEntities`,
358
+ `status` and `undatedExcludedCount`.
359
+ - `memory by-date` (and `search-memories-by-date`) returns the same reply.
360
+ Its `range` is gone: the applied bounds are `appliedFilters.start` and
361
+ `appliedFilters.end`, as supplied. Each memory adds `replaces` and `linked`.
362
+ `--limit` above 25 is now a usage error (exit `2`).
363
+ - The hidden top-level `search` command is removed with the `searchMemories`
364
+ RPC it called, so every memory search returns the reply above. Use `memory
365
+ search`; `search` is now an unknown command (exit `2`). Its `--mode`,
366
+ `--threshold`, `--lobe`, graph and `--include-source-content` options have
367
+ no `memory search` equivalent: use `debug rpc search`.
368
+ - The client drops `searchMemories`, `memoriesByDate` and `recall.searchMemory`
369
+ and their types (`SearchMemoriesInput`, `SearchMemoryHit`,
370
+ `MemoriesByDateInput`/`Output`, `SearchMemoryRecallInput`/`Output`), which
371
+ the server no longer serves; use `recall.searchMemories`. CLI versions
372
+ before 0.7.0 cannot search against a current server.
108
373
 
109
374
  ## Files and stdin
110
375
 
@@ -120,6 +385,45 @@ printf 'A multiline memory\nwith context\n' | merrai memory add --file -
120
385
 
121
386
  Supplying more than one input source is a usage error.
122
387
 
388
+ ## Retries and idempotency
389
+
390
+ Every write sends an `idempotencyKey` derived from what it writes, never a
391
+ random one, so re-running a command that timed out joins the first ingestion
392
+ instead of storing the content twice:
393
+
394
+ - `memory add` / `add-memory`: the text, lobe, source and observation date.
395
+ Without `--observation-date`, the UTC day is part of the key: the same
396
+ sentence saved on a later day is a new occurrence, not a retry.
397
+ - `ingest memories|chat|chats`: the parsed payload (content, sources, lobes,
398
+ supplied times, session metadata). Field order in the file does not matter.
399
+ A caller-supplied `idempotencyKey` in `chat`/`chats` input takes precedence.
400
+
401
+ The server treats a key as naming one payload: the same key with the same
402
+ content returns the first ingestion, while the same key with different content
403
+ is refused with `CONFLICT` (`IDEMPOTENCY_KEY_REUSED`) instead of silently
404
+ keeping the first content. A request larger than one ingestion accepts is
405
+ refused with `PAYLOAD_TOO_LARGE`; split it.
406
+
407
+ `deriveIdempotencyKey` and `deriveMemorySaveIdempotencyKey` are exported for
408
+ integrations (the Claude Code plugin uses the latter for `/merrai:save`).
409
+
410
+ ## Dates
411
+
412
+ Chat turns in `ingest chats` input may carry `sourceTime`: an ISO 8601
413
+ instant with an offset (`2026-03-04T09:30:00Z`) or a local calendar date
414
+ (`2026-03-04`). A session's `metadata.date`, in the same format, dates every
415
+ turn without its own time. A turn's time is part of its identity, and a stored
416
+ session's date cannot change. Without either, the time stays unknown; the
417
+ import time is never used instead.
418
+
419
+ A memory's recorded date is `null` when no cited source carries a time
420
+ (for example, every upload). A local date records that day without a time. Text output shows these as `undated`. Date-range
421
+ recall (`memory by-date`) can only match dated memories; its
422
+ `undatedExcludedCount` reports how many memories the range could not include,
423
+ and text output prints that count. Unified search (`debug rpc search` with
424
+ `filters.startDate`/`endDate`) returns the same top-level
425
+ `undatedExcludedCount` for the memories in its scope and filters.
426
+
123
427
  ## Output contract
124
428
 
125
429
  JSON is always the default machine contract, including scalar string results.
@@ -129,7 +433,7 @@ Use `--format text` for concise human output. `--json` is an alias for
129
433
  - Result data is written to stdout.
130
434
  - Diagnostics and errors are written to stderr.
131
435
  - JSON output is never mixed with progress or error text.
132
- - Successful canonical MCP-parity commands emit the MCP tool's structured DTO
436
+ - Successful canonical commands emit their typed API response DTO
133
437
  directly, without an additional envelope.
134
438
  - `NO_COLOR` is naturally honored because the CLI emits no color in machine
135
439
  output.
@@ -143,8 +447,14 @@ Exit codes:
143
447
  | `3` | Authentication or authorization failure |
144
448
  | `4` | Not found or conflict |
145
449
  | `5` | Rate limit or resource exhaustion |
450
+ | `6` | An App Artifact handler failed |
146
451
  | `10` | Network or server failure |
147
452
 
453
+ An unknown, malformed, revoked or expired API key exits `3` with code
454
+ `UNAUTHORIZED`, `data.reason: "INVALID_API_KEY"` and a message saying to save
455
+ a new key with `merrai auth set-key` or `MERRAI_API_KEY`. Library callers can
456
+ test a caught error with `isInvalidApiKeyError`.
457
+
148
458
  ## Raw oRPC access
149
459
 
150
460
  `debug rpc` is an unstable escape hatch for top-level procedures: