@north-light/crouter 0.3.353 → 0.3.354

package/docs/concepts/why-a-daemon.md

@@ -26,4 +26,4 @@ The costs are real. A daemon must be running, and canvas state has one home inst
 
 Those costs buy a simpler model: one state owner, one broker launcher, and clients that can reconnect. A CLI command, an SDK application, and a terminal viewer all use the same API for canvas state. They can come and go without creating competing writers or losing the graph that explains what each agent is doing.
 
-For the lower-level runtime model, run `crtr memory read internal/nodes-and-canvas`. For a complete remote application setup, start with the SDK [getting started guide](../sdk/getting-started.md).
+For the lower-level runtime model, run `crtr canvas read internal/nodes-and-canvas`. For a complete remote application setup, start with the SDK [getting started guide](../sdk/getting-started.md).

package/docs/sdk/README.md

@@ -5,7 +5,7 @@ description: Drive a crouter daemon from a Node or browser application with the
 
 # `@north-light/crouter-sdk`
 
-The ESM-only client an application installs to drive a crouter daemon: create agent runs, watch streamed events, wait for typed results, read and write memory, and reach the rest of the daemon's `/v1` API.
+The ESM-only client an application installs to drive a crouter daemon: create agent runs, watch streamed events, wait for typed results, and reach the rest of the daemon's `/v1` API.
 
 One package, one class. `new Crouter()` in Node talks to the owner's unix socket. `new Crouter({ baseURL, token })` in a browser or a remote process talks to the daemon's TCP listener with a bearer token. Resource methods issue `/v1` requests; `createAndWait`, `parse`, and `auth.status` compose more than one request. crtrd stays the sole owner of canvas state.
 
@@ -32,7 +32,6 @@ if (run.kind === 'result') console.log(run.output_parsed.root_cause);
 | [Client construction](./client.md) | Every constructor option and its environment-variable fallback; per-request options |
 | [Nodes](./nodes.md) | `create` parameters, the outcome union, `parse()` with a zod schema, `waitForOutcome`, `message`, `cancel`, nested resources |
 | [Streaming](./streaming.md) | The event table, `stream()` / `events()`, the activity helper, resume with `after`, `stream_gap` and `stream_dropped` |
-| [Memory](./memory.md) | The scope object and every `client.memory` method |
 | [Files](./files.md) | Absolute-path reads, writes, and one-level lists |
 | [Bash](./bash.md) | One bounded command and its output result |
 | [Resource map](./resources.md) | Every namespace with its phase, what is deliberately excluded, and the `client.request()` escape hatch |
@@ -42,21 +41,21 @@ if (run.kind === 'result') console.log(run.output_parsed.root_cause);
 
 ## Phases
 
-The surface ships in three cuts. Phase 3 memory methods are shipped.
+The surface ships in three cuts.
 
 | Phase | What lands | State |
 |---|---|---|
 | **Phase 1** | Client construction and transports; `client.auth.status()`; `client.nodes.create`, `retrieve`, `list`, `outcome`, `waitForOutcome`, `createAndWait`, `parse`, `message`, `cancel`, and `interrupt`; `nodes.reports.list`; `profiles.ensure` and `retrieve`; `system.status` and `health`; the error hierarchy; per-request options; `crtr sys connect`; and `env-docker.connection()` | Shipped |
 | **Phase 2 namespaces** | Node lifecycle, job, worktree, and result; canvas and canvas history; crons; human requests and inbox; models; `client.files.read` through `/v1/files/peek`, `write`, and `list`; and `client.bash.run` | Shipped |
 | **Phase 2 streaming** | `GET /v1/nodes/{id}/events`, `nodes.stream(params, options?)`, `nodes.events(id, options?)`, `NodeStream`, and the activity helper | Shipped |
-| **Phase 3** | Memory routes and `client.memory`, plus the review, comment, and chat-inventory namespaces | Memory shipped; remaining namespaces not shipped |
+| **Phase 3** | The review, comment, and chat-inventory namespaces | Not shipped |
 
 The per-run `scopes` create field ships in phase 1. `nodes.update` scope support remains phase 2 and is not in the shipped client or wire declarations.
 
 ## Verification status
 
-The SDK declarations, streaming examples, and memory examples are verified.
+The SDK declarations and streaming examples are verified.
 
 ## Where the agents read this
 
-The same content routed for agents lives in the builtin memory document `crouter-sdk`, which ships with the `crtr` binary. An agent working in an application's repository reaches it with `crtr memory read crouter-sdk` and does not need this repository checked out.
+The same content routed for agents lives in the builtin memory document `crouter-sdk`, which ships with the `crtr` binary. An agent working in an application's repository reaches it with `crtr canvas read crouter-sdk` and does not need this repository checked out.

package/docs/sdk/errors.md

@@ -64,19 +64,6 @@ The SDK validates path-segment identifiers before it makes a request. Invalid no
 | The bearer token's ceiling lacks the scope a route needs, or `nodes.create` asks for `scopes` outside it (`details.scopes` lists them) | `PermissionDeniedError`, 403 `scope_denied` |
 | A scoped token reaches an owner-only route (daemon restart, attach, broker internals, canvas prune, profile pause/resume/delete, model credential install) | `PermissionDeniedError`, 403 `owner_only` |
 
-## Memory requests
-
-| Condition | Class, status, and code |
-|---|---|
-| `retrieve` or `resolve` names a document that does not exist, including a document deleted earlier | `NotFoundError`, 404 `memory_document_not_found` |
-| `history` names a document with no document or revision history | `NotFoundError`, 404 `not_found` |
-| History is requested for a builtin or plugin document | `BadRequestError`, 400 `usage` |
-| A mutation directly sets protected frontmatter (`kind`, `when-and-why-to-read`, `origin`, or `last-updated`) | `BadRequestError`, 400 `invalid_request` |
-| An update would make no change | `BadRequestError`, 400 `usage` |
-| A node-targeted caller lacks `memory:read` or `memory:write` | `PermissionDeniedError`, 403 `scope_denied` |
-
-Invalid names, invalid scope combinations, invalid limits, builtin mutation selections, and invalid search combinations are also `BadRequestError` responses. Builtin and plugin documents cannot be mutated; no code should treat a 400 refusal as a successful write.
-
 ## The wire body
 
 The daemon answers an error with:

package/docs/sdk/guides/README.md

@@ -13,6 +13,5 @@ These recipes turn the SDK namespaces into complete applications: a bounded extr
 | [Event-driven assistant](./event-driven-assistant.md) | Events arrive over time from a webhook, queue, or watcher. | A resident node that wakes for each event. |
 | [Fan-out pipeline](./fan-out-pipeline.md) | One task needs independent research before a synthesis. | An orchestrator's final report. |
 | [Human approval](./human-approval.md) | A person must decide before work continues. | A node resumed by an inbox answer. |
-| [Application memory](./app-memory.md) | Several runs need the same durable application knowledge. | A profile-owned document read by a scoped run. |
 
 Start with typed extraction for a request/response job. Use a resident node when the same assistant should react again later. Use an orchestrator only when child work can proceed independently; otherwise keep the composition in your application.

package/docs/sdk/nodes.md

@@ -189,8 +189,6 @@ for (const report of reports) console.log(report.tier, report.body);
 
 List routes return what the daemon returns. `nodes.list`, `nodes.reports.list`, and `nodes.jobs.list` return plain arrays — there is no page object, no `hasNextPage()`, and no `after` cursor on them, because the daemon has no paging substrate behind those routes and an envelope there would promise a continuation that can never happen.
 
-The one place the page envelope exists is the phase-3 memory routes. See [Memory](./memory.md).
-
 ## Identifier validation
 
 Methods that take a node id validate it before the request: core node methods, lifecycle methods, `nodes.reports`, `nodes.jobs`, `nodes.worktree`, and `nodes.result`. An invalid id throws `TypeError` locally and sends no request. `nodes.outcome(id, { wait })` also throws `RangeError` locally when `wait` is not an integer from 0 through 25.

package/docs/sdk/resources.md

@@ -26,7 +26,6 @@ Every namespace exported by the client. Namespaces are camelCase. Verbs are `cre
 | `human.inbox` | `list`, `retrieve`, `respond`, `progress`, `cancel`, `history`, `response` | `/v1/human/inbox…` |
 | `models.credentials` | `list`, `install`, `remove` | `/v1/model-auth…` |
 | `models.config` | `update` | `PUT /v1/model-config` |
-| `memory` | `list`, `retrieve`, `create`, `update`, `delete`, `move`, `search`, `history`, `resolve` | `/v1/memory…`; see [Memory](./memory.md) |
 
 Action methods keep the product's literal name (`fork`, `revive`, `promote`, `yield`) rather than being renamed into a generic verb. Every request-capable method takes `RequestOptions` as its final argument after its path, body, or query arguments. `RequestOptions` is `{ headers?, signal?, timeout?, maxRetries? }`; stream event options exclude `timeout` and add `after`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.353",
+  "version": "0.3.354",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -131,7 +131,7 @@
     "@earendil-works/pi-ai": "0.87.1",
     "@earendil-works/pi-coding-agent": "0.87.1",
     "@earendil-works/pi-tui": "0.87.1",
-    "@north-light/crouter-identity": "^0.3.353",
+    "@north-light/crouter-identity": "^0.3.354",
     "cron-parser": "^5.6.0",
     "esbuild": "^0.27.7",
     "jose": "^6.2.12",

package/packages/crouter-identity/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter-identity",
-  "version": "0.3.353",
+  "version": "0.3.354",
   "description": "Northlight access-token verification and scope rules",
   "type": "module",
   "main": "./dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.353",
+  "version": "0.3.354",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.353",
+      "version": "0.3.354",
       "hasInstallScript": true,
       "license": "GPL-3.0-only",
       "workspaces": [
@@ -18,7 +18,7 @@
         "@earendil-works/pi-ai": "0.87.1",
         "@earendil-works/pi-coding-agent": "0.87.1",
         "@earendil-works/pi-tui": "0.87.1",
-        "@north-light/crouter-identity": "^0.3.353",
+        "@north-light/crouter-identity": "^0.3.354",
         "cron-parser": "^5.6.0",
         "esbuild": "^0.27.7",
         "jose": "^6.2.12",
@@ -10885,17 +10885,17 @@
     },
     "packages/crouter-api": {
       "name": "@north-light/crouter-api",
-      "version": "0.3.353",
+      "version": "0.3.354",
       "license": "GPL-3.0-only"
     },
     "packages/crouter-env-docker": {
       "name": "@north-light/crouter-env-docker",
-      "version": "0.3.353",
+      "version": "0.3.354",
       "license": "GPL-3.0-only"
     },
     "packages/crouter-identity": {
       "name": "@north-light/crouter-identity",
-      "version": "0.3.353",
+      "version": "0.3.354",
       "license": "GPL-3.0-only",
       "dependencies": {
         "jose": "^6.2.1"
@@ -10903,19 +10903,19 @@
     },
     "packages/crouter-plugin": {
       "name": "@north-light/crouter-plugin",
-      "version": "0.3.353",
+      "version": "0.3.354",
       "license": "GPL-3.0-only",
       "dependencies": {
-        "@north-light/crouter-api": "^0.3.353"
+        "@north-light/crouter-api": "^0.3.354"
       }
     },
     "packages/crouter-sdk": {
       "name": "@north-light/crouter-sdk",
-      "version": "0.3.353",
+      "version": "0.3.354",
       "license": "GPL-3.0-only",
       "dependencies": {
-        "@north-light/crouter-api": "^0.3.353",
-        "@north-light/crouter-identity": "^0.3.353",
+        "@north-light/crouter-api": "^0.3.354",
+        "@north-light/crouter-identity": "^0.3.354",
         "jose": "^6.2.1"
       }
     }

package/dist/api/dto/memory.d.ts

@@ -1,171 +0,0 @@
-export declare const MEMORY_SCOPES: readonly ["node", "project", "profile", "user", "builtin"];
-export type MemoryScopeName = typeof MEMORY_SCOPES[number];
-/** A canonical document address: slash-joined safe segments, carried as one percent-encoded path segment. */
-export declare function isMemoryDocName(name: string): boolean;
-export interface MemoryOriginConversationDTO {
-    session_file: string;
-}
-export interface MemoryScope {
-    node?: string;
-    cwd?: string;
-    profile?: string;
-    store?: MemoryScopeName;
-}
-export interface MemoryDocSummaryDTO {
-    name: string;
-    short_form: string;
-    kind: string;
-    privacy: 'public' | 'friends' | 'private';
-    scope: MemoryScopeName;
-    extensions: Record<string, Record<string, string | boolean | number>>;
-    path: string;
-    store_root: string;
-    physical_relative_path: string;
-    candidates?: MemoryCandidateDTO[];
-}
-export interface MemoryCandidateDTO {
-    winner: boolean;
-    scope: MemoryScopeName;
-    store_root: string;
-    physical_relative_path: string;
-    path: string;
-}
-export interface MemoryDocDTO extends MemoryDocSummaryDTO {
-    body: string;
-    frontmatter: Record<string, unknown> | null;
-    representation: 'leaf-file' | 'directory-index';
-    links: string[];
-    findings?: MemoryLintFindingDTO[];
-}
-export interface MemoryLintFindingDTO {
-    severity: string;
-    rule: string;
-    message: string;
-}
-export interface MemoryListQuery extends MemoryScope {
-    kind?: string;
-    limit?: number;
-    after?: string;
-}
-export interface MemoryDocCreateRequest extends MemoryScope {
-    name: string;
-    kind: string;
-    when_and_why_to_read: string;
-    body: string;
-    frontmatter?: Record<string, unknown>;
-    extensions?: Record<string, Record<string, string | boolean | number>>;
-}
-export interface MemoryDocUpdateRequest extends MemoryScope {
-    rationale: string;
-    body?: string;
-    frontmatter?: Record<string, unknown>;
-    extensions?: Record<string, Record<string, string | boolean | number>>;
-    unset?: string[];
-}
-export interface MemoryDocDeletedDTO {
-    name: string;
-    scope: MemoryScopeName;
-    path: string;
-    log_path: string;
-    deleted: true;
-}
-export interface MemoryDocMoveRequest extends MemoryScope {
-    to: string;
-}
-export interface MemoryDocMovedDTO {
-    name: string;
-    previous_name: string;
-    scope: MemoryScopeName;
-    path: string;
-    log_path: string;
-    refs_rewritten: Array<{
-        name: string;
-        scope: MemoryScopeName;
-        path: string;
-        refs: number;
-    }>;
-    follow_up: string;
-}
-export interface MemorySearchRequest extends MemoryScope {
-    query: string;
-    kind?: string;
-    grep?: boolean;
-    body?: boolean;
-    limit?: number;
-    after?: string;
-    min_score?: number;
-}
-export type MemorySearchHitDTO = MemoryRankedSearchHitDTO | MemoryGrepSearchHitDTO;
-export interface MemoryRankedSearchHitDTO {
-    name: string;
-    kind: string;
-    privacy: 'public' | 'friends' | 'private';
-    scope: MemoryScopeName;
-    score: number;
-    short_form: string;
-    path: string;
-    store_root: string;
-    physical_relative_path: string;
-    candidates?: MemoryCandidateDTO[];
-}
-export interface MemoryGrepSearchHitDTO {
-    name: string;
-    privacy: 'public' | 'friends' | 'private';
-    scope: MemoryScopeName;
-    line: number;
-    text: string;
-    path: string;
-    store_root: string;
-    physical_relative_path: string;
-    candidates?: MemoryCandidateDTO[];
-}
-export interface MemoryHistoryQuery extends MemoryScope {
-    limit?: number;
-    revision?: number;
-    diff?: boolean;
-}
-export interface MemoryHistoryRevisionDTO {
-    revision: number;
-    op: 'create' | 'edit' | 'delete' | 'move';
-    at: string;
-    node?: string;
-    rationale?: string;
-    verbatim?: true;
-    body_changed: boolean;
-    frontmatter_changed: string[];
-    diff?: string;
-}
-export interface MemoryHistoryRecordDTO {
-    revision: number;
-    op: 'create' | 'edit' | 'delete' | 'move';
-    at: string;
-    node?: string;
-    cwd: string;
-    from?: string;
-    rationale?: string;
-    verbatim?: boolean;
-    before: string;
-    after: string;
-}
-export interface MemoryHistoryDTO {
-    name: string;
-    scope: MemoryScopeName;
-    log_path: string;
-    total: number;
-    deleted?: unknown;
-    revisions?: MemoryHistoryRevisionDTO[];
-    record?: MemoryHistoryRecordDTO;
-}
-export interface MemoryDocRefDTO {
-    name: string;
-    scope: string;
-    path: string;
-    store_root: string;
-    physical_relative_path: string;
-    plugin?: string;
-}
-export interface MemoryListDTO<T> {
-    object: 'list';
-    data: T[];
-    has_more: boolean;
-}

package/dist/api/dto/memory.js

@@ -1 +0,0 @@
-var r=Object.defineProperty;var o=(e,t)=>r(e,"name",{value:t,configurable:!0});const i=["node","project","profile","user","builtin"];function c(e){return/^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/.test(e)}o(c,"isMemoryDocName");export{i as MEMORY_SCOPES,c as isMemoryDocName};

package/dist/builtin-memory/crouter-sdk/guides/app-memory.md

@@ -1,73 +0,0 @@
----
-kind: knowledge
-when-and-why-to-read: When an application's agents need shared durable
-  knowledge, read this because a profile store gives runs one owned memory
-  location and scopes can allow reading without writing.
----
-
-# Application memory
-
-Use this recipe when several runs need the same application guidance. Run `npx tsx examples/guides/app-memory.ts /path/to/repo`; it ensures a profile, creates a profile-owned knowledge document if it does not already exist, then starts a run allowed to read but not write memory.
-
-```ts
-import Crouter, { NotFoundError } from '@north-light/crouter-sdk';
-import { resolve } from 'node:path';
-import { z } from 'zod';
-
-const client = new Crouter();
-const cwd = resolve(process.argv[2] ?? process.cwd());
-const profileName = process.env.APP_PROFILE ?? 'release-notes-app';
-
-const profile = await client.profiles.ensure(profileName, {
-  projects: [{ path: cwd, memory: 'content' }],
-});
-
-try {
-  await client.memory.retrieve('release/voice', { profile: profile.id, store: 'profile' });
-} catch (error) {
-  if (!(error instanceof NotFoundError)) throw error;
-  await client.memory.create({
-    name: 'release/voice',
-    kind: 'knowledge',
-    when_and_why_to_read: 'When writing release notes, read this because it defines the product voice and terms customers recognize.',
-    body: 'Use short factual sentences. Name the user-visible result before implementation details.',
-    frontmatter: { surfaces: ['{"on":"boot","at":"preview"}'] },
-    profile: profile.id,
-    store: 'profile',
-  });
-}
-
-const result = await client.nodes.parse({
-  cwd,
-  model: process.env.GUIDE_MODEL,
-  profile: profile.id,
-  root: true,
-  root_lifecycle: 'terminal',
-  deadline: '5m',
-  scopes: ['memory:read'],
-  prompt: 'Write one short release note announcing that customers can download invoices as CSV from account settings. Do not write or update memory.',
-  output_schema: z.object({ release_note: z.string() }),
-});
-
-if (result.kind === 'result') {
-  console.log(result.output_parsed.release_note);
-} else if (result.reason === 'declined') {
-  console.error(`agent declined: ${result.declined?.reason ?? 'no reason supplied'}`);
-  process.exitCode = 2;
-} else {
-  console.error(`agent failed: ${result.reason}`, result.detail);
-  process.exitCode = 1;
-}
-```
-
-A profile is the application's durable identity: it names the memory store and the projects whose context the profile can reach. The routing line is part of the document, not decoration. State both the moment the agent should read it and the reason it matters; a document with a vague routing line will not surface when the agent needs it.
-
-The `boot`/`preview` surface exposes the document's routing line when this profile's agent starts. The task asks for a release note without naming `release/voice`; in the local run the agent read that document before producing the note. Without a surface entry, a memory document appears only in its directory listing and its routing line cannot select it at boot. The run passes `scopes: ['memory:read']`. That is an allow-list: node-targeted memory reads are allowed and writes are refused because `memory:write` is absent. The application itself is not narrowed by those node scopes, so keep application credentials and its memory mutation policy separate from the agent's capabilities.
-
-Observed against the local daemon with `APP_PROFILE=release-notes-app-guide-boot-preview GUIDE_MODEL=openai-codex/gpt-6-sol:high`:
-
-```text
-You can now download your invoices as a CSV from account settings.
-```
-
-Use profile memory for knowledge shared across the application's related projects. Put facts that belong to one repository in project memory instead, and temporary run notes in node memory. See [[crouter-concepts/memory]] for the ownership tiers and [[crouter-concepts/profiles-kinds-and-modes]] for what a profile changes.

package/dist/builtin-memory/crouter-sdk/memory.md

@@ -1,87 +0,0 @@
----
-kind: knowledge
-when-and-why-to-read: When you need Memory, this knowledge should be read
-  because Read and write memory documents with an explicit target for every
-  request.
----
-
-# `client.memory`
-
-Phase 3. `client.memory` reads and writes the memory documents that shape an agent run. Every call names its target; the daemon never uses its own working directory or environment to select memory.
-
-```ts
-const page = await client.memory.list({ node: nodeId, kind: 'knowledge', limit: 50 });
-const document = await client.memory.retrieve('insights/capture', { node: nodeId, frontmatter: true });
-```
-
-## Target
-
-```ts
-type MemoryScope = {
-  node?: string;
-  cwd?: string;
-  profile?: string;
-  store?: 'node' | 'project' | 'profile' | 'user' | 'builtin';
-};
-```
-
-Pass `node` to use that node's working directory and profile. Do not combine it with `cwd` or `profile`. With no target, only user and builtin memory are searched. `store` restricts the request to one memory tier; `store: 'node'` requires `node`, and `store: 'profile'` requires a profile target. `create` defaults to the nearest project store when one is available, otherwise the user store. `update`, `delete`, and `move` resolve the existing document through normal scope precedence when `store` is omitted. `builtin` is read-only.
-
-When a request supplies `node`, its node row must hold `memory:read` for `list`, `retrieve`, `search`, `history`, and `resolve`, or `memory:write` for `create`, `update`, `delete`, and `move`. Calls without `node` are external application calls and are not narrowed by a node scope list.
-
-## Methods
-
-Every method accepts `RequestOptions` as its final optional argument (`signal`, `timeout`, `maxRetries`, and `headers`). A document name can contain `/`; the SDK encodes it as one path segment.
-
-| Method | Parameters | Result |
-|---|---|---|
-| `memory.list(query?, options?)` | `MemoryScope & { kind?, limit?, after? }`; `limit` is 1–100 (default 100) | `MemoryPage<MemoryDocSummaryDTO>` |
-| `memory.retrieve(name, query?, options?)` | `name`; `MemoryScope & { frontmatter? }` | `MemoryDocDTO` |
-| `memory.create(params, options?)` | `MemoryDocCreateRequest` | `MemoryDocDTO` |
-| `memory.update(name, params, options?)` | `name`; `MemoryDocUpdateRequest` | `MemoryDocDTO` |
-| `memory.delete(name, scope?, options?)` | `name`; `MemoryScope` | `MemoryDocDeletedDTO` |
-| `memory.move(name, params, options?)` | `name`; `MemoryDocMoveRequest` | `MemoryDocMovedDTO` |
-| `memory.search(params, options?)` | `MemorySearchRequest` | `MemoryPage<MemorySearchHitDTO>` |
-| `memory.history(name, query?, options?)` | `name`; `MemoryHistoryQuery` | `MemoryHistoryDTO` |
-| `memory.resolve(name, scope?, options?)` | `name`; `MemoryScope` | `MemoryDocRefDTO` |
-
-`MemoryDocCreateRequest` requires `name`, `kind`, `when_and_why_to_read`, and `body`; it also accepts `frontmatter`, `extensions`, and the scope fields. `frontmatter.privacy` accepts `public`, `friends`, or `private`; creation defaults to persisted `public`. `MemoryDocUpdateRequest` requires `rationale`, which is stored in revision history rather than document text, and optionally accepts `body`, `frontmatter`, `extensions`, `unset`, and the scope fields. Set `frontmatter.privacy` to change the level; it cannot be unset. A legacy document without the field reads as `private`. `MemoryDocMoveRequest` requires `to` and accepts the scope fields.
-
-`retrieve` returns the body by default. With `frontmatter: true`, its `body` is the complete document source with the effective privacy level included for older documents. `MemoryDocDTO` also contains `privacy`, `frontmatter`, `representation` (`'leaf-file'` or `'directory-index'`), `links`, and any lint `findings`; document DTOs include their canonical name, kind, scope, extensions, path, store root, physical relative path, and any competing candidates. `resolve` returns the winning document's location and optional plugin name without reading its body.
-
-```ts
-await client.memory.create({
-  name: 'billing/refund-policy',
-  kind: 'knowledge',
-  when_and_why_to_read: 'When handling a refund request, read this because the eligibility window is not in the order record.',
-  body: 'Refunds are available for 60 days.',
-  profile: 'my-app',
-});
-
-await client.memory.update('billing/refund-policy', {
-  rationale: 'The eligibility window changed on 2026-01-04.',
-  body: 'Refunds are available for 90 days.',
-  profile: 'my-app',
-});
-```
-
-The daemon returns document text without expanding shell blocks. Builtin and plugin documents are read-only. `kind`, `when-and-why-to-read`, `origin`, and `last-updated` cannot be set or removed directly. Each mutation writes a complete before/after history record; delete leaves a tombstone. `retrieve` and `resolve` return `NotFoundError` with status 404 and code `memory_document_not_found` for a deleted document or an unknown name. Concurrent writes are last-write-wins.
-
-`search` uses ranked search by default. Set `body: true` to include document bodies in ranking, or `grep: true` for regular-expression line matches; `grep` and `body` cannot be combined, and `min_score` is only available in ranked search. Ranked hits contain `kind`, `score`, and `short_form`; grep hits contain `line` and `text`.
-
-`history` returns newest-first revision summaries, optionally with `diff`, or the full before/after record for one `revision`. A delete leaves history available through its tombstone.
-
-## Pages
-
-`list` and `search` return `{ object: 'list', data, has_more }` as a `MemoryPage`. A page has `hasNextPage()`, `getNextPage()`, and is async iterable across every page. The list cursor is the final document's canonical name. Ranked search uses the final hit's name; grep uses an opaque cursor that includes the match location, which the SDK handles.
-
-```ts
-const page = await client.memory.search({ query: 'refund window', node: nodeId });
-for (const hit of page.data) console.log(hit.name);
-
-if (page.hasNextPage()) {
-  const next = await page.getNextPage();
-}
-
-for await (const hit of page) console.log(hit.name);
-```

package/dist/commands/broker-permissions.d.ts

@@ -1,2 +0,0 @@
-/** Commands that mutate local installation state cannot be called through a broker's CLI relay. */
-export declare function requirePersonCli(): void;

package/dist/commands/broker-permissions.js

@@ -1 +0,0 @@
-var o=Object.defineProperty;var r=(e,n)=>o(e,"name",{value:n,configurable:!0});import{InputError as i}from"../core/io.js";function m(){if(process.env.CRTR_API_SOCKET!==void 0)throw new i({error:"permission_error",message:"this command is not available to a node",next:"Run this command from the person's terminal."})}r(m,"requirePersonCli");export{m as requirePersonCli};

package/dist/commands/memory/client.d.ts

@@ -1,11 +0,0 @@
-/** The daemon resolves memory against the caller's view, not its own cwd. A node names only itself:
- *  the daemon derives its cwd and profile from the node row and refuses a cwd a broker supplies. */
-export declare function memoryCaller(): {
-    cwd?: string;
-    node?: string;
-    profile?: string;
-};
-export declare function memorySelection(input: Record<string, unknown>): Record<string, string>;
-export declare function memoryRequest<T>(method: string, path: string, body?: unknown): Promise<T>;
-export declare function memoryExtensionHelp(operation: 'write' | 'edit'): Promise<string | null>;
-export declare function memoryQuery(params: Record<string, string | number | boolean | undefined>): string;

package/dist/commands/memory/client.js

@@ -1 +0,0 @@
-var m=Object.defineProperty;var t=(r,e)=>m(r,"name",{value:e,configurable:!0});import{envNodeId as f,envProfileId as l}from"../../shared/env.js";import{cliClient as y,rethrowAsCliError as u}from"../api-client.js";import{memoryExtensionFieldCatalogHelp as d}from"../../core/help/memory-extensions.js";function s(){const r=f();if(r)return{node:r};const e=l();return{cwd:process.cwd(),...e?{profile:e}:{}}}t(s,"memoryCaller");function A(r){return{...s(),...typeof r.scope=="string"?{store:r.scope}:{},...typeof r.dir=="string"?{dir:r.dir}:{},...typeof r.profile=="string"?{select_profile:r.profile}:{}}}t(A,"memorySelection");async function p(r,e,n){try{const o=await y().request(r,e,n);if(o!==null&&typeof o=="object"&&!Array.isArray(o)&&"diagnostics"in o){const{diagnostics:i,...c}=o;if(Array.isArray(i))for(const a of i)console.error(a);return c}return o}catch(o){u(o,e.startsWith("/v1/memory/resolve")&&o.status===404?"Find the canonical name with `crtr memory find <query>` or browse `crtr memory list`.":void 0)}}t(p,"memoryRequest");async function q(r){try{const e=await p("GET",`/v1/memory/extensions?${g(s())}`);return d(r,e)}catch{return null}}t(q,"memoryExtensionHelp");function g(r){const e=new URLSearchParams;for(const[n,o]of Object.entries(r))o!==void 0&&e.set(n,String(o));return e.toString()}t(g,"memoryQuery");export{s as memoryCaller,q as memoryExtensionHelp,g as memoryQuery,p as memoryRequest,A as memorySelection};

package/dist/commands/memory/delete.d.ts

@@ -1 +0,0 @@
-export declare const deleteLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/memory/delete.js

@@ -1 +0,0 @@
-var n=Object.defineProperty;var t=(e,a)=>n(e,"name",{value:a,configurable:!0});import{defineLeaf as r}from"../../core/command.js";import{memoryRequest as s,memorySelection as i}from"./client.js";import{MEMORY_WRITE_SCOPES as l,selectorParam as o}from"./shared.js";const u=r({name:"delete",description:"delete a memory document by name",whenToUse:"a stored document is wrong, obsolete, or superseded and should be removed \u2014 the sanctioned way to delete one, so you never rm the markdown off disk. Resolves the full canonical name exactly as `read` does and removes that one file: if you can read it, you can delete it. Refuses docs you do not own \u2014 builtin docs (shipped with the package) and installed-plugin docs (managed by `crtr pkg`). If two physical files in the selected store share the name, it selects the first physical path in stable lexical order and recovers the collision.",help:{name:"memory delete",summary:"resolve an exact canonical name and remove that document from its store",params:[{kind:"positional",name:"name",required:!0,constraint:"Full canonical name of the document \u2014 a project document is `<namespace>/<local name>`. Resolution is exact, as `read` resolves it: a file path, a bare leaf, a `<scope>/<name>` spelling, and a trailing `/INDEX` all fail. A canonical directory\u2019s own document is deleted at the directory name; its members are untouched and stay reachable. If two physical files in the selected store own the name, delete selects the first path in stable lexical order and reports it. Builtin and installed-plugin documents are read-only and refuse to delete, as does the repository-root document, which declares the immutable namespace for every document in the repository; a nested store\u2019s root guide is ordinary and may be deleted."},o("scope-read",{choices:[...l]},"Package-shipped documents cannot be deleted through this writable-scope selector."),o("dir",{},"Deletes from that one store, including a non-winning duplicate no target view resolves to.")],output:[{name:"name",type:"string",required:!0,constraint:"Full canonical name of the document that was deleted, as resolution settled it."},{name:"scope",type:"string",required:!0,constraint:"Scope the document was deleted from: node, user, project, or profile."},{name:"path",type:"string",required:!0,constraint:"Absolute path of the file that was removed."},{name:"log_path",type:"string",required:!0,constraint:"Absolute path to the document\u2019s revision log, which OUTLIVES the document \u2014 the delete is appended to it as a tombstone carrying the full final text, still readable with `crtr memory history`."},{name:"follow_up",type:"string",required:!1,constraint:"Present only when a same-store canonical collision was recovered by selecting the first physical path in lexical order."}],outputKind:"object",effects:["Permanently removes the resolved file from its store, and prunes any parent directories it leaves empty. Irreversible. Refuses the repository-root document: it declares the immutable `namespace:` every document in this repository composes under, so removing it would unmount the whole repository.","Appends a `delete` record carrying the document\u2019s full final text to `.history/<physical path>.jsonl` in the same store. The log itself is never removed."]},run:t(async e=>s("DELETE",`/v1/memory/docs/${encodeURIComponent(e.name)}`,{...i(e),mode:"cli"}),"run")});export{u as deleteLeaf};

package/dist/commands/memory/edit.d.ts

@@ -1 +0,0 @@
-export declare const editLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/memory/edit.js

@@ -1,21 +0,0 @@
-var i=Object.defineProperty;var r=(t,a)=>i(t,"name",{value:a,configurable:!0});import{defineLeaf as o}from"../../core/command.js";import{memoryExtensionHelp as s,memoryRequest as d,memorySelection as l}from"./client.js";import{DOC_RATIONALE_CONSTRAINT as c,GUIDE_CANONICAL_NAMES as h,GUIDE_DOC_LINKS as u,GUIDE_PREDICATE_VOCABULARY as m,GUIDE_ROUTING_LINE as p,GUIDE_SURFACES as y,overlayParam as e,selectorParam as n}from"./shared.js";const f=["short-form","gate","surfaces","unlisted","slash","rationale","lint-ignore"],g=["kind","privacy","when-and-why-to-read","origin","last-updated"],v=o({name:"edit",description:"revise an existing memory document, recording why",whenToUse:"a document that already exists needs to change \u2014 its body, its frontmatter, or both. Every revision carries a --rationale and is appended to the doc\u2019s revision history, so the corpus keeps a record of why it reached its current state. Resolves the name exactly as `read` does and revises the doc where it lives; use `crtr memory write` only to create one that does not exist yet.",help:{name:"memory edit",summary:"resolve an existing document and revise its body and/or frontmatter, appending a history record",guide:`The body you pipe is saved byte for byte. Nothing between stdin and disk parses, normalizes, summarizes, or rewrites it \u2014 the frontmatter fence is prepended and the text is otherwise untouched. Relaying a person\u2019s own words is therefore safe: pass them through unchanged and mark them with --verbatim.
-
-Two different rationales exist and they never share a flag. --rationale is why THIS REVISION is happening; it is required, it lands in the revision history, and it never touches the document text. --doc-rationale replaces the document\u2019s standing \`rationale\` frontmatter field \u2014 the observed gap the doc exists to close.
-
-Omitting stdin leaves the body exactly as it stands, which is how a frontmatter-only revision is made. Piping a body REPLACES the whole body; there is no partial or append mode. Emptying a document is not an edit \u2014 that intent is \`crtr memory delete\`.
-
-Omitted frontmatter flags preserve their fields; a legacy document without privacy is stamped private on edit. --unset is the only way to REMOVE a clearable field. The canonical clearable set (short-form, gate, surfaces, unlisted, slash, rationale, lint-ignore) is always accepted; any other field name is accepted only when the document\u2019s frontmatter already carries it \u2014 the path for dropping a legacy or non-canonical field. --surface replaces the whole surfaces list rather than adding to it.
-
-An edit that changes nothing fails. A rationale attached to zero change is noise in the trail the history exists to build \u2014 if the doc already says what you meant, there is nothing to record.
-
-\`last-updated\` is stamped on every successful edit; \`origin\` is preserved, so it keeps pointing at the conversation that created the doc rather than the last one to touch it.
-
-`+p+`
-
-`+y+`
-
-`+m+`
-
-`+h+`
-
-`+u+"\n\nCreate a document that does not exist yet with `crtr memory write`. Read the revisions back with `crtr memory history`.",params:[{kind:"positional",name:"name",required:!0,constraint:"Full canonical identity, resolved exactly in the target view or exact project store. A project document requires its complete `<namespace>/<local name>`; a directory document answers at the directory name, never with a trailing `/INDEX`. Same-store physical collisions are refused with both paths; `--dir` selects one exact project store. Builtin and installed-plugin docs are read-only corpora and are refused."},{kind:"flag",name:"rationale",type:"string",required:!0,constraint:"Why THIS REVISION is happening \u2014 the audit-trail entry, required on every edit. Recorded in the document\u2019s revision history, NEVER written into the document. To change the doc\u2019s standing `rationale` frontmatter field instead, use --doc-rationale."},{kind:"flag",name:"verbatim",type:"bool",required:!1,constraint:"Declares the piped body a verbatim payload from the principal \u2014 their own text, relayed unchanged \u2014 rather than agent-authored prose. Pure provenance recorded in the history record; the save path is identical either way, because there is only one save path and it never transforms."},e("kind"),e("privacy"),e("when-and-why-to-read"),e("short-form"),e("unlisted",{},"Presence SETS the field; remove it with `--unset unlisted`."),e("surface"),e("gate"),e("lint-ignore"),e("slash",{},"Presence SETS the field; remove it with `--unset slash`."),{kind:"flag",name:"doc-rationale",type:"string",required:!1,constraint:c},{kind:"flag",name:"extension",type:"string",required:!1,repeatable:!0,constraint:"Set one declared plugin field as `extensions.<plugin>.<field>=VALUE`. The path is required in full; booleans accept only true or false, numbers require finite numeric syntax, and strings/enums preserve the literal text after the first =. Every requested field validates before the document is revised."},{kind:"flag",name:"unset-extension",type:"string",required:!1,repeatable:!0,constraint:"Remove one explicitly persisted declared field by its full `extensions.<plugin>.<field>` path. A removed explicit value lets its declaration default apply only in structured output."},{kind:"flag",name:"unset",type:"string",required:!1,repeatable:!0,constraint:`Remove a frontmatter field. One field per occurrence. ${f.join(", ")} are always accepted, whether or not the doc currently carries them. Any other field name is accepted only when the target document's frontmatter already carries it \u2014 this is the path for dropping a legacy or otherwise non-canonical field (e.g. a stale \`name:\` or \`description:\` left over from before \`when-and-why-to-read\`). Requesting a field the doc does not have fails, naming the fields it does have. \`${g.join("`, `")}\` are never clearable.`},n("scope-read",{},"Edit resolves the address winner and refuses same-store physical collisions."),n("dir"),n("profile"),{kind:"stdin",name:"body",required:!1,constraint:"Full replacement body (markdown, no frontmatter), saved byte for byte. Piped on stdin only \u2014 this leaf already claims the one positional for NAME. Absent or empty stdin leaves the existing body untouched, which is how a frontmatter-only revision is made."}],output:[{name:"name",type:"string",required:!0,constraint:"Resolved document name."},{name:"kind",type:"string",required:!0,constraint:"Kind recorded in frontmatter after the revision."},{name:"scope",type:"string",required:!0,constraint:"Scope the document was revised in: node, project, profile, or user."},{name:"path",type:"string",required:!0,constraint:"Absolute path to the revised document."},{name:"revision",type:"number",required:!0,constraint:"This document\u2019s record count after the append \u2014 the revision number to pass to `crtr memory history --revision`."},{name:"changed",type:"string[]",required:!0,constraint:"`body` when the body text changed, plus the frontmatter field names whose values changed. `last-updated` is excluded \u2014 it is stamped on every edit, so naming it says nothing."}],outputKind:"object",effects:["Rewrites the selected physical memory document and appends one `edit` record to its mirrored `.history` sidecar."]},effectiveHelp:r(async()=>{const t=await s("edit");return{...v.help,dynamicState:r(()=>t,"dynamicState")}},"effectiveHelp"),run:r(async t=>d("PATCH",`/v1/memory/docs/${encodeURIComponent(t.name)}`,{...l(t),mode:"cli",fields:t}),"run")});export{v as editLeaf};

package/dist/commands/memory/find.d.ts

@@ -1 +0,0 @@
-export declare const findLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/memory/find.js

@@ -1 +0,0 @@
-var f=Object.defineProperty;var o=(e,t)=>f(e,"name",{value:t,configurable:!0});import{defineLeaf as g}from"../../core/command.js";import{usage as w}from"../../core/errors.js";import{memoryRequest as b,memorySelection as v}from"./client.js";import{MEMORY_KINDS as k,selectorParam as s}from"./shared.js";const A=g({name:"find",description:"relevance search across memory documents",whenToUse:"the discovery surface when you do NOT know a document\u2019s canonical name \u2014 ranks documents by relevance over the canonical name, the store-local name, the physical path, the read-routing line, and short-form (add --body to also weigh body text), and every hit reports the canonical name `crtr memory read` takes. Searches every scope by default regardless of any visibility gate; --scope narrows to one class of store, --dir to one exact store. Reach for `crtr memory list` instead when you want the whole inventory rather than a topic match, and --grep when you need an exact regex or literal-string match across document bodies.",help:{name:"memory find",summary:"bounded relevance search across memory documents, weighted over name/local name/physical path/routing-line/short-form (and body with --body)",params:[{kind:"positional",name:"query",required:!0,constraint:"With ranked search (default): whitespace-separated terms, matched case-insensitively and weighted over the document\u2019s names (canonical, store-local, and physical path), the read-routing line, and short-form (plus body with --body); documents matching more/stronger fields rank higher. By default returns at most 10 hits scoring at least half the top score. With --grep: an ECMAScript regex applied to each document body line."},{kind:"flag",name:"kind",type:"enum",choices:[...k],required:!1,constraint:"Filter to a single kind. Default: all kinds."},s("scope-read",{},"Default: every resolved scope, builtin included."),s("dir",{},"Searches that store alone, and searches it physically: two documents sharing one canonical name are both searched and both reported, where the default view searches only the winner."),{kind:"flag",name:"grep",type:"bool",required:!1,constraint:"Treat the query as an ECMAScript regex and match it against document bodies, instead of weighted relevance ranking. Mutually exclusive with --body."},{kind:"flag",name:"body",type:"bool",required:!1,constraint:"Also weigh document body text in the relevance ranking (in addition to name/when/why/short-form). Ignored under --grep, which always scans bodies."},{kind:"flag",name:"limit",type:"int",required:!1,constraint:"Maximum hits to return per page after relevance filtering. Default 10, hard max 100."},{kind:"flag",name:"cursor",type:"string",required:!1,constraint:"Opaque token from next_cursor. Omit on first call."},{kind:"flag",name:"min-score",type:"int",required:!1,constraint:"Ranked mode only. Minimum score to return, replacing the default adaptive floor of half the top score. Must be at least 1."},{kind:"flag",name:"paths",type:"bool",required:!1,constraint:"Include each hit\u2019s physical location \u2014 absolute path, store root, store-relative path, and every other physical document sharing its canonical name. Off by default; the canonical name is sufficient for `crtr memory read <name>`."}],output:[{name:"query",type:"string",required:!0,constraint:"Echo of the input query."},{name:"matches",type:"integer",required:!0,constraint:"Total matches before the default relevance floor and limit are applied (ranked mode) or total matching lines (grep mode) \u2014 across all pages, not just this one."},{name:"hits",type:"object[]",required:!0,constraint:"Ranked mode \u2014 each: {name, kind, privacy, scope, score, short_form}, sorted by score descending. Grep mode \u2014 each: {name, privacy, scope, line, text}, sorted by name then line. `name` is always the canonical name, whatever field matched. With --paths, each shape also carries path, store_root, physical_relative_path, and candidates when several physical documents share the name. Paginated via --limit/--cursor."},{name:"next_cursor",type:"string | null",required:!0,constraint:"Opaque token for the next page; null means no more items."},{name:"follow_up",type:"string",required:!0,constraint:"Concrete next commands for reading a hit in full or refining the search."}],outputKind:"object",effects:["Records this search page as listing context for the current node without marking any matched document as loaded."]},run:o(async e=>{const t=e.query,i=e.kind,c=e.grep,d=e.body,a=e.limit,l=e.cursor,h=e.minScore,m=e.paths;if(a!==void 0&&(a<1||a>100))throw w("--limit must be between 1 and 100.");const u=a??10,n=await b("POST","/v1/memory/search",{...v(e),mode:"cli",query:t,...i===void 0?{}:{kind:i},grep:c,body:d,limit:u,cursor:l,min_score:h}),y=o(r=>{const{path:q,store_root:x,physical_relative_path:_,candidates:R,...p}=r;return p},"omitPaths");return{query:t,matches:n.matches,hits:n.hits.map(r=>m?r:y(r)),next_cursor:n.next_cursor,follow_up:"Read a hit with `crtr memory read <name>`. Run `crtr memory find -h` for filters and verbosity."}},"run")});export{A as findLeaf};

package/dist/commands/memory/history.d.ts

@@ -1 +0,0 @@
-export declare const historyLeaf: import("../../core/command.js").LeafDef;