@sol-merrai/cli 0.1.4 → 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 +438 -87
- package/dist/bin.mjs +1910 -0
- package/dist/bin.mjs.map +1 -0
- package/dist/index.d.mts +1475 -37
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +287 -2
- package/dist/index.mjs.map +1 -0
- package/package.json +12 -9
- package/.env.example +0 -3
- package/.env.prod.example +0 -3
- package/dist/cli.d.mts +0 -1
- package/dist/cli.mjs +0 -256
- package/dist/cli.mjs.map +0 -1
- package/dist/client-BirYnOM4.mjs +0 -27
- package/dist/client-BirYnOM4.mjs.map +0 -1
package/README.md
CHANGED
|
@@ -1,132 +1,483 @@
|
|
|
1
1
|
# Merrai CLI
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
The Merrai CLI stores, recalls, and imports memories from a terminal. The npm
|
|
4
|
+
package is `@sol-merrai/cli`; the installed command is `merrai`.
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
`merrai`.
|
|
6
|
+
## Requirements and installation
|
|
8
7
|
|
|
9
|
-
|
|
8
|
+
- Node.js 20 or newer
|
|
10
9
|
|
|
11
10
|
```bash
|
|
12
11
|
npm install -g @sol-merrai/cli
|
|
12
|
+
merrai --help
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
-
##
|
|
15
|
+
## Authentication
|
|
16
|
+
|
|
17
|
+
Validate and save an API key:
|
|
16
18
|
|
|
17
19
|
```bash
|
|
18
|
-
merrai
|
|
19
|
-
merrai
|
|
20
|
-
merrai
|
|
21
|
-
merrai usage-summary --api-key "merrai_..."
|
|
22
|
-
merrai add-memory --memory "Met Sarah at lunch" --source cli --lobe people
|
|
23
|
-
merrai rpc healthCheck
|
|
20
|
+
merrai auth set-key
|
|
21
|
+
merrai auth status --format text
|
|
22
|
+
merrai auth logout
|
|
24
23
|
```
|
|
25
24
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
Check API connectivity.
|
|
31
|
-
|
|
32
|
-
### `session`
|
|
25
|
+
`auth set-key` prompts without echoing the key when stdin is a TTY. For CI,
|
|
26
|
+
provide `MERRAI_API_KEY`; `--api-key` and a positional key remain available but
|
|
27
|
+
may expose the key in shell history.
|
|
33
28
|
|
|
34
|
-
|
|
29
|
+
Configuration precedence is:
|
|
35
30
|
|
|
36
|
-
|
|
31
|
+
1. Command flags
|
|
32
|
+
2. `MERRAI_*` environment variables
|
|
33
|
+
3. Saved credentials
|
|
34
|
+
4. `https://api.merrai.app`
|
|
37
35
|
|
|
38
|
-
|
|
36
|
+
Credentials are stored at `$XDG_CONFIG_HOME/merrai/credentials.json`, or
|
|
37
|
+
`~/.config/merrai/credentials.json` when `XDG_CONFIG_HOME` is unset. The CLI and
|
|
38
|
+
Claude Code plugin share this versioned file. Existing
|
|
39
|
+
`~/.merrai-claude-code/credentials.json` files remain readable as a migration
|
|
40
|
+
fallback and are not deleted automatically.
|
|
39
41
|
|
|
40
|
-
|
|
42
|
+
`merrai auth logout` is an explicit removal action and deletes both shared and
|
|
43
|
+
legacy fallback credentials after confirmation.
|
|
41
44
|
|
|
42
|
-
|
|
45
|
+
There is intentionally no separate persistent `config.json` yet: the only
|
|
46
|
+
persistent non-secret value is the base URL associated with a credential.
|
|
47
|
+
Flags and environment variables cover temporary overrides without creating an
|
|
48
|
+
empty configuration abstraction.
|
|
43
49
|
|
|
44
|
-
|
|
50
|
+
Supported environment variables:
|
|
45
51
|
|
|
46
|
-
|
|
52
|
+
- `MERRAI_API_KEY`
|
|
53
|
+
- `MERRAI_BASE_URL`
|
|
54
|
+
- `MERRAI_COOKIE`
|
|
55
|
+
- `XDG_CONFIG_HOME`
|
|
47
56
|
|
|
48
|
-
|
|
49
|
-
| ------------------- | -------- | -------------------------------------------------------- |
|
|
50
|
-
| `--memory <text>` | Yes | The memory text (also accepted as a positional argument) |
|
|
51
|
-
| `--source <text>` | No | Source identifier (defaults to `"testing-ui"`) |
|
|
52
|
-
| `--lobe <name>` | No | Lobe to store the memory in (defaults to `"main"`) |
|
|
53
|
-
| `--lobe-key <name>` | No | Deprecated alias for `--lobe` |
|
|
57
|
+
Installed-package `.env` files are not loaded.
|
|
54
58
|
|
|
55
|
-
|
|
59
|
+
## Command structure
|
|
56
60
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
61
|
+
```text
|
|
62
|
+
merrai health
|
|
63
|
+
merrai session
|
|
64
|
+
merrai account usage
|
|
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
|
|
70
|
+
merrai entity find|memories
|
|
71
|
+
merrai document list|get|retry-rebuild|retry-backfill
|
|
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
|
|
76
|
+
merrai auth set-key|status|logout
|
|
77
|
+
merrai debug rpc
|
|
78
|
+
```
|
|
74
79
|
|
|
75
|
-
|
|
80
|
+
Examples:
|
|
76
81
|
|
|
77
82
|
```bash
|
|
78
|
-
merrai
|
|
83
|
+
merrai memory add "Met Sarah at lunch"
|
|
84
|
+
merrai memory add "The Atlas budget is $4,000" --lobe project-alpha
|
|
85
|
+
merrai memory search "What did Sarah suggest?" --limit 10
|
|
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
|
|
94
|
+
merrai entity find "Sarah" --type person
|
|
95
|
+
merrai entity memories ent_01J00000000000000000000000
|
|
96
|
+
merrai document list --limit 20 --offset 0
|
|
97
|
+
merrai document get lvd_01J00000000000000000000000 --max-characters 12000
|
|
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
|
|
79
114
|
```
|
|
80
115
|
|
|
81
|
-
|
|
116
|
+
`memory clear` confirms interactively and requires `--yes` in noninteractive
|
|
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:
|
|
82
170
|
|
|
83
171
|
```bash
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
merrai
|
|
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"
|
|
88
182
|
```
|
|
89
183
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
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`.
|
|
215
|
+
|
|
216
|
+
## MCP parity
|
|
217
|
+
|
|
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:
|
|
293
|
+
|
|
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
|
|
109
299
|
```
|
|
110
300
|
|
|
111
|
-
|
|
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.
|
|
373
|
+
|
|
374
|
+
## Files and stdin
|
|
375
|
+
|
|
376
|
+
Bulk commands accept inline JSON, a file, or stdin:
|
|
112
377
|
|
|
113
378
|
```bash
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
379
|
+
merrai ingest memories --input '[{"memory":"Remember this"}]'
|
|
380
|
+
merrai ingest memories --file ./memories.json
|
|
381
|
+
cat memories.json | merrai ingest memories --file -
|
|
382
|
+
cat chats.json | merrai ingest chats --file -
|
|
383
|
+
printf 'A multiline memory\nwith context\n' | merrai memory add --file -
|
|
117
384
|
```
|
|
118
385
|
|
|
119
|
-
|
|
386
|
+
Supplying more than one input source is a usage error.
|
|
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
|
+
|
|
427
|
+
## Output contract
|
|
428
|
+
|
|
429
|
+
JSON is always the default machine contract, including scalar string results.
|
|
430
|
+
Use `--format text` for concise human output. `--json` is an alias for
|
|
431
|
+
`--format json`.
|
|
432
|
+
|
|
433
|
+
- Result data is written to stdout.
|
|
434
|
+
- Diagnostics and errors are written to stderr.
|
|
435
|
+
- JSON output is never mixed with progress or error text.
|
|
436
|
+
- Successful canonical commands emit their typed API response DTO
|
|
437
|
+
directly, without an additional envelope.
|
|
438
|
+
- `NO_COLOR` is naturally honored because the CLI emits no color in machine
|
|
439
|
+
output.
|
|
440
|
+
|
|
441
|
+
Exit codes:
|
|
442
|
+
|
|
443
|
+
| Code | Meaning |
|
|
444
|
+
| ---- | --------------------------------------- |
|
|
445
|
+
| `0` | Success |
|
|
446
|
+
| `2` | Usage or validation error |
|
|
447
|
+
| `3` | Authentication or authorization failure |
|
|
448
|
+
| `4` | Not found or conflict |
|
|
449
|
+
| `5` | Rate limit or resource exhaustion |
|
|
450
|
+
| `6` | An App Artifact handler failed |
|
|
451
|
+
| `10` | Network or server failure |
|
|
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
|
+
|
|
458
|
+
## Raw oRPC access
|
|
459
|
+
|
|
460
|
+
`debug rpc` is an unstable escape hatch for top-level procedures:
|
|
120
461
|
|
|
121
462
|
```bash
|
|
122
|
-
|
|
463
|
+
merrai debug rpc healthCheck
|
|
464
|
+
merrai debug rpc memoryStatus --input '{"lobeKey":"main"}'
|
|
465
|
+
merrai debug rpc addMemories --file ./payload.json
|
|
123
466
|
```
|
|
124
467
|
|
|
125
|
-
##
|
|
468
|
+
## Reusable client
|
|
126
469
|
|
|
127
|
-
|
|
470
|
+
The package exposes both client contracts from `@sol-merrai/cli`:
|
|
471
|
+
|
|
472
|
+
```ts
|
|
473
|
+
import {
|
|
474
|
+
createMerraiClient,
|
|
475
|
+
createMerraiThrowingClient,
|
|
476
|
+
} from "@sol-merrai/cli";
|
|
477
|
+
```
|
|
128
478
|
|
|
129
|
-
-
|
|
130
|
-
|
|
479
|
+
- `createMerraiThrowingClient()` returns typed data and throws oRPC/network
|
|
480
|
+
errors. New integrations should use it.
|
|
481
|
+
- `createMerraiClient()` retains the legacy `[error, data]` safe-tuple contract.
|
|
131
482
|
|
|
132
|
-
|
|
483
|
+
There is no separate SDK package or method-by-method SDK facade.
|