@keb-org/consol 0.2.1 → 0.3.0

package/README.md

@@ -1,6 +1,7 @@
 # @keb-org/consol
 
-TypeScript SDK for the consol memory engine, for three uses:
+The consol memory engine as one package: the MCP server (`npx -y @keb-org/consol`) and a TypeScript SDK.
+The SDK has three uses:
 
 1. **Local**: a vault on disk (or S3), with the engine running in your own process as a native addon.
 2. **Hosted client**: the same `Vault` methods against a backend over HTTP.
@@ -9,6 +10,41 @@ TypeScript SDK for the consol memory engine, for three uses:
 Node >= 22 or Bun, no dependencies; `import` and `require` share one implementation. The behaviour
 is the same in every mode.
 
+## MCP server
+
+`npx -y @keb-org/consol --vault PATH --agent NAME` serves MCP on stdio for one vault that already
+exists (`consol create --vault PATH` makes it; the MCP never creates a vault). The engine runs in
+its process through the same addon as the SDK, so it needs the database too: every `CONSOL_*`
+variable of its process is an engine setting (`CONSOL_DB_URL` is required, `CONSOL_EMBED_*` turn on
+embeddings). Engine logs go to stderr at the level of `RUST_LOG` (default `warn`).
+
+| Flag | Variable | |
+|---|---|---|
+| `--vault` | `CONSOL_VAULT` | a directory or `s3://bucket/prefix/name`; with `--remote`, the vault's name on the backend |
+| `--remote` | `CONSOL_REMOTE_URL` | a backend URL (use 3) to forward to, instead of opening a vault; its headers come from `CONSOL_REMOTE_HEADERS` (one `Name: value` per line) |
+| `--agent` | `CONSOL_AGENT` | the default agent of every call; a call's `agent` argument overrides it |
+
+In an MCP client, or in Claude Code (the options go before the name):
+
+```bash
+claude mcp add --env CONSOL_DB_URL=postgres://postgres:pw@127.0.0.1:5432/postgres \
+  consol -- npx -y @keb-org/consol --vault /abs/path/vault --agent assistant
+```
+
+```json
+{ "mcpServers": { "consol": {
+  "command": "npx",
+  "args": ["-y", "@keb-org/consol", "--vault", "/abs/path/vault", "--agent", "assistant"],
+  "env": { "CONSOL_DB_URL": "postgres://postgres:pw@127.0.0.1:5432/postgres" }
+} } }
+```
+
+A hosted backend needs no database here:
+`npx -y @keb-org/consol --remote https://api.acme.dev/v1/consol --vault demo --agent assistant`, with the
+backend's credentials in `CONSOL_REMOTE_HEADERS`. The
+tool list, the instructions and each result are the engine's, the same ones `consol serve` mounts
+over streamable HTTP at `<path>/mcp`, which is unchanged.
+
 ## The engine addon and database
 
 The engine is the native addon `consol.node`, loaded the first time you start a vault or a
@@ -109,19 +145,25 @@ Each method takes one object with the tool's wire argument names, plus optional
 
 | Method | Arguments | Returns |
 |---|---|---|
-| `recall` | `{ query, include_history?, limit?, intents?, agent? }` | `RecallResult`: `text` is the progressive disclosure to give a model (cards by tier, intent block, hints); `candidates` are the same cards as data. Cards are leads: read a note before relying on it |
+| `recall` | `{ query, agent? }` | `RecallResult`: `text` is the progressive disclosure to give a model (cards by tier, the blocks the query's symbols ask for, hints); `candidates` are the same cards as data. Cards are leads: read a note before relying on it |
 | `read` | `{ id, continuation?, agent? }` | `ReadResult`; `text` is the exact file |
-| `remember` | `{ id, content?, expected_version?, summary?, entities?, facets?, scope?, team?, valid_from?, valid_to?, reflection?, agent? }` | `RememberResult` |
-| `remove` | `{ id, expected_version, reflection?, agent? }` | `RemoveResult`: the note is archived, its body stays readable |
-| `reflect` | one mode: `{}` discovery, `{ ids }`, `{ work_ids }` or `{ decisions }`; `limit?`, `agent?` | `ReflectResult`; delivered sources carry their `text` |
+| `remember` | `{ id, content?, meta?, expected_version?, token?, agent? }`; `meta` is `{ summary?, entities?, facets?, scope?, team?, valid_from?, valid_to? }` | `RememberResult` |
+| `remove` | `{ id, expected_version, token?, agent? }` | `RemoveResult`: the note is archived, its body stays readable |
+| `reflect` | `{ focus?, decisions?, agent? }`; call it with no arguments and follow `next` | `ReflectResult`: `next`, the delivered `items` (sources carry their `text`), every unresolved `writes` entry, the `blocked` tokens |
 | `callTool` | `(name, args)` with raw wire arguments | the raw `Reply`; tool errors come back as `reply.error` |
 | `close` | | final and idempotent |
 
 - `remember` without `expected_version` is create-only. To update, pass `source.content_version`
-  from your last `read`; a stale one fails with `version_conflict`. Omitted or `null` fields keep
-  their stored value, `""` or `[]` clears them.
-- `remember` and `remove` also take `{ resume: true, reflection, agent? }` to resume a pending
-  reflection-bound write. `reflection` is `{ work_id, basis_hash, action_key }`.
+  from your last `read`; a stale one fails with `version_conflict`. Omitted or `null` `content` keeps
+  the body. In `meta` a key left out keeps its stored value, `null`, `""` or `[]` clears it (not
+  `scope` or `team`); a key the server does not know is ignored and listed in the receipt's
+  `ignored`.
+- `token` on `remember` and `remove` is an item's work token from `reflect`: it binds that one write to the
+  work (the server derives the write's key). `{ token, agent? }` alone, with a write token from
+  `reflect().writes` or a write receipt, resumes that write.
+- `reflect` holds nothing between calls: a cold `reflect()` lists every unresolved write, the open work and
+  the blocked work. Decide an item with `{ token, verdict, reason, refs?, outputs? }`, `verdict` one of the
+  item's `verdicts`; the server sizes each batch (about 64 KiB of source Markdown, at most 16 items).
 - `byte_range` values are UTF-8 byte offsets: `sliceUtf8(text, start, end)` slices a JS string by them.
 - `vault.serverVersion` is the server version of the last reply. An agent exists from its first
   `remember`; reading as an agent that wrote nothing finds nothing.
@@ -147,7 +189,7 @@ Markdown inline.
 
 The tool list is not on the wire. `consol schema` prints its JSON Schema: `oneOf` holds one
 envelope per tool, with the `args` schema and the description the model reads. An MCP client can
-use `consol mcp` instead.
+use the MCP server of this package instead (above).
 
 ## Loading many notes
 
@@ -181,8 +223,8 @@ try {
 ```
 
 - `ConsolError.is(error)` also works across duplicate copies of the package, where `instanceof` fails.
-- `field` names the input at fault, relative to the call's arguments (`limit`,
-  `decisions[2].temporal`), `tool` the tool, and `result` keeps the raw `Reply` of a failed tool
+- `field` names the input at fault, relative to the call's arguments (`query`,
+  `decisions[2].refs[0]`), `tool` the tool, and `result` keeps the raw `Reply` of a failed tool
   call, including the durable state of a pending write (`error.result.result`).
 - Tool codes (contract section 4; accept unknown future ones): `invalid_argument`, `forbidden`,
   `not_found`, `already_exists`, `version_conflict`, `team_not_attached`, `secret_rejected`,
@@ -216,7 +258,7 @@ the default for `db`), so a stray host variable cannot change the agent or the v
 | `vaultRoot` / `vault` | `Consol.start`: a directory or `s3://` prefix of many vaults, or one vault |
 | `agent` | default agent of every call; a call's `agent` argument overrides it |
 | `db` | database URL (`CONSOL_DB_URL`): PostgreSQL with pgvector, or CockroachDB |
-| `embedding` | `{ url, model, apiKey?, dims?, queryPrefix?, batchSize?, timeoutMs? }` (`CONSOL_EMBED_*`); without it recall is lexical-only |
+| `embedding` | `{ url, model, apiKey?, dims?, timeoutMs? }` (`CONSOL_EMBED_*`); without it recall is lexical-only |
 | `jev` | `{ url?, apiKey?, model?, auto? }` (`CONSOL_JEV_*`); experimental advice |
 | `env` | any other engine setting (a `CONSOL_*` name), applied last |
 | `addonPath` | the `consol.node` to load, see above |

package/dist/index.d.ts

@@ -2,5 +2,5 @@ export { ConsolError, type ConsolErrorCode } from "./errors";
 export { Consol, httpStatus, type ConsolOptions } from "./consol";
 export type { CallOptions, Context } from "./transport";
 export type { EmbeddingOptions, EngineOptions, JevOptions } from "./native";
-export { Vault, createVault, openVault, sliceUtf8, type VaultOptions, type HostedOptions, type Intent, type RecallArgs, type ReadArgs, type RememberArgs, type RemoveArgs, type ResumeArgs, type ReflectArgs, type ReflectionContext, type Decision, type InspectedSource, type InspectedSpan, type TemporalAssessment, type PairAssertion, } from "./vault";
-export type { Reply, ToolError, Unavailable, Status, ByteRange, Scope, SourceRef, RelationshipKind, Relationship, RecallRetrieval, SourceExcerpt, RecallCard, RecallResult, ReadResult, RememberResult, RemoveResult, ReflectResult, AffectedDoc, EntityAffectedGroup, WriteState, WriteFailureCode, WriteReceipt, WriteResolution, WriteOutcome, ReflectionWork, SourceWork, PairWork, HubWork, PromotionWork, DeliveredSource, CompleteDelivery, FailedDelivery, ReflectDelivery, DecisionReceipt, SourceDisposition, PairDisposition, } from "./types";
+export { Vault, createVault, openVault, sliceUtf8, type VaultOptions, type HostedOptions, type RecallArgs, type ReadArgs, type RememberArgs, type RemoveArgs, type ResumeArgs, type ReflectArgs, type Decision, } from "./vault";
+export type { Reply, ToolError, Unavailable, Status, ByteRange, Scope, SourceRef, RelationshipKind, Relationship, RecallRetrieval, SourceExcerpt, RecallCard, RecallResult, ReadResult, RememberResult, RemoveResult, ReflectResult, AffectedDoc, EntityAffectedGroup, WriteState, WriteFailureCode, WriteReceipt, WriteResolution, WriteOutcome, UnresolvedWrite, ReflectItem, SourceItem, PairItem, HubItem, PromotionItem, DeliveredSource, DecisionReceipt, FocusError, ReflectNext, } from "./types";

package/dist/index.js

@@ -193,10 +193,6 @@ function engineSettings(o) {
     s.CONSOL_EMBED_MODEL = e.model;
     if (e.dims !== undefined)
       s.CONSOL_EMBED_DIMS = String(e.dims);
-    if (e.queryPrefix !== undefined)
-      s.CONSOL_EMBED_QUERY_PREFIX = e.queryPrefix;
-    if (e.batchSize !== undefined)
-      s.CONSOL_EMBED_BATCH = String(e.batchSize);
     if (e.timeoutMs !== undefined)
       s.CONSOL_EMBED_TIMEOUT_MS = String(e.timeoutMs);
   }
@@ -373,7 +369,7 @@ function sliceUtf8(text, start, end) {
 }
 
 // src/vault.ts
-var CLIENT_INFO = { name: "consol-js-client", version: "0.2.1" };
+var CLIENT_INFO = { name: "consol-js-client", version: "0.3.0" };
 var LOCAL = "default";
 function payload(tool, reply) {
   const error = replyError(reply, tool);

package/dist/mcp.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};