@cilow/sdk 0.2.1 → 0.3.0

package/dist/client.d.ts

@@ -1,224 +1,563 @@
-import { CilowConfig, CreateMemoryOptions, SearchResult, Memory, UpdateMemoryOptions, PaginatedResponse, MemorySummary, SearchQuery, AdvancedSearchOptions, ContextResult, ConversationTurn, GraphNode, GraphEdge, GraphTraversalOptions, GraphSubgraph, MemoryStats, TagCount, UserStats, HealthCheck } from './types.js';
-
+import type { AnswerResponse, Branch, ConsolidateResponse, Fact, FeedbackResponse, ContextPackResponse, ExplainResponse, ForgetResponse, IngestResponse, BlobGetResponse, BlobMetaResponse, BlobListResponse, ForkResponse, IngestAudioResponse, IngestImageResponse, IngestPdfResponse, IngestAnyResponse, IngestStructuredResponse, Outcome, RecallResponse, RememberResponse, RememberTextResponse, Scope, Source, TimelineEntry, TrackEntityResponse, WorkspaceResponse, EvidenceResponse, InvestigateResponse, CompileContextResponse, TraceResponse, EpisodeResponse, MemoryResponse } from "./types.js";
+/** Current wall clock as epoch MICROSECONDS — the unit every Cilow time field uses. */
+export declare function nowMicros(): number;
+/** The content forms `ingest` accepts — exactly one. `url` is sent as `text` (the wire's one text
+ *  field is "raw text or a URL"; the server fetches + snapshots a bare URL). */
+export type IngestContent = {
+    facts: Fact[];
+} | {
+    text: string;
+} | {
+    url: string;
+} | {
+    contentBase64: string;
+    mime?: string;
+};
 /**
- * Cilow Client - Core HTTP Client for Cilow API
- *
- * Provides a clean, type-safe interface for interacting with the Cilow
- * memory system API.
+ * The idempotency key `ingest` sends when you pass no `sourceId`: a sha256 CONTENT HASH.
+ * The wire requires `source_id` (`RememberRequest.source_id` / `IngestAnyRequest.source_id` are
+ * non-optional) and a timestamp would make every retry a fresh write; hashing the content makes a
+ * retry of the same payload an idempotent no-op (the engine dedups under the tenant on this key).
+ * Pre-image: `"<form>:<content>"`, facts as canonical JSON (sorted keys, compact). The Python SDK's
+ * `ingest_source_id` computes the identical key.
  */
-
+export declare function ingestSourceId(content: IngestContent): string;
+/** Options for `new CilowClient(...)`. */
+export interface CilowClientOptions {
+    /** Base URL of a running cilow-serve, e.g. `http://localhost:8080`. */
+    baseUrl: string;
+    /** Bearer token (the `CILOW_TOKENS` entry). Required for `/rpc`; the server stamps its scope. */
+    token: string;
+    /**
+     * Default scope sent with every call. Over HTTP this is ignored (the server stamps it
+     * from the token), but it is honored by the stdio MCP transport, so it is kept for parity.
+     */
+    scope?: Scope;
+    /** Optional `fetch` implementation (defaults to global `fetch`). */
+    fetch?: typeof fetch;
+    /** Per-request timeout in milliseconds (default 30000). */
+    timeoutMs?: number;
+}
+export interface RememberOptions {
+    scope?: Scope;
+    /** Provenance kind (default `operator`). */
+    source?: Source;
+    /** Idempotency / provenance id for this batch (dedup key). Defaults to a generated id. */
+    sourceId?: string;
+    /** Observation time in epoch µs — the claims' `valid_from` (default: now). */
+    observedAt?: number;
+    /**
+     * The RAW source text these facts were extracted from (recommended). Captured durably into the
+     * engine's verbatim lane and made searchable — the lossless backstop, so a detail the extractor
+     * dropped is still recallable from the raw text. Without it the engine stores only the lossy claims.
+     * Mirrors the engine's `RememberRequest.raw_context`.
+     */
+    rawContext?: string;
+    /** Track A1: the git-style branch NAME to write to (default `"main"` = trunk). A fork's writes are
+     *  isolated from main and other branches. */
+    branch?: string;
+}
+export interface RecallOptions {
+    scope?: Scope;
+    /** The valid-time `T` to read as-of, in epoch µs (default: now). `< now` ⇒ a historical read. */
+    asOf?: number;
+    /** The present clock in epoch µs (default: now). */
+    now?: number;
+    /** Optional fast-path entity-surface hint, e.g. `"Maya"`. */
+    anchor?: string;
+    /** Optional fast-path predicate hint, e.g. `"employer"`. */
+    attribute?: string;
+    /** Track A1: the git-style branch NAME to read from (default `"main"` = trunk). An anchored read on a
+     *  branch sees the branch's values, falling back to the base as-of the fork point for keys it never
+     *  wrote. */
+    branch?: string;
+}
+export interface AnswerOptions {
+    scope?: Scope;
+    /** The present clock in epoch µs (default: now). */
+    now?: number;
+    anchor?: string;
+    attribute?: string;
+    /** Track A1: the git-style branch NAME to answer from (default `"main"` = trunk). */
+    branch?: string;
+}
+export interface ForkOptions {
+    scope?: Scope;
+    /** The base branch to fork from (default `"main"` = trunk). */
+    from?: string;
+    /** The fork instant in epoch µs — the valid-time cap the branch's read falls back under (default now). */
+    now?: number;
+}
+export interface TimelineOptions {
+    scope?: Scope;
+    /** The instant the `active` flag is computed against, in epoch µs (default: now). */
+    at?: number;
+    /** Optional window start (epoch µs). */
+    from?: number;
+    /** Optional window end (epoch µs). */
+    to?: number;
+}
+export interface TrackEntityOptions {
+    scope?: Scope;
+    /** The instant the alias class is resolved as-of, in epoch µs (default: now). */
+    at?: number;
+}
+export interface FeedbackOptions {
+    scope?: Scope;
+}
+export interface ConsolidateOptions {
+    scope?: Scope;
+    /** The present clock in epoch µs the decay/recency pass reads against (default: now). */
+    now?: number;
+}
+export interface RememberTextOptions {
+    scope?: Scope;
+    /** Idempotency / provenance id (default: generated). */
+    sourceId?: string;
+    /** Observation time in epoch µs — the claims' `valid_from` (default: now). */
+    observedAt?: number;
+}
+export interface IngestImageOptions {
+    scope?: Scope;
+    sourceId?: string;
+    observedAt?: number;
+}
+export interface IngestAudioOptions {
+    scope?: Scope;
+    sourceId?: string;
+    observedAt?: number;
+}
+export interface IngestPdfOptions {
+    scope?: Scope;
+    sourceId?: string;
+    observedAt?: number;
+}
+export interface IngestStructuredOptions {
+    scope?: Scope;
+    /** The column/key whose value names the entity (omit ⇒ subjectHint + row index). */
+    subjectField?: string;
+    sourceId?: string;
+    observedAt?: number;
+}
+export interface IngestAnyOptions {
+    scope?: Scope;
+    /** Optional mime HINT (the sniff verifies; bytes win a contradiction). */
+    mime?: string;
+    /** The subject derived facts anchor to when the content names none (defaults to the document). */
+    subjectHint?: string;
+    /** Free-form provenance pairs — each becomes a claim on the document entity. */
+    metadata?: Record<string, string>;
+    sourceId?: string;
+    observedAt?: number;
+}
+export interface ForgetOptions {
+    scope?: Scope;
+    /** Scope the forget to one attribute (omit to forget the whole entity). */
+    attribute?: string;
+    /** Forget exactly this value (requires `attribute`). */
+    value?: string;
+    /**
+     * When true, destroy the entity (OF1): truth + verbatim + span/claim ANN + known embed-cache
+     * keys. Attribute/value are ignored. Not complete Art.17 (query-cache residual).
+     */
+    erase?: boolean;
+    /** The instant the claims are retired as-of, in epoch µs (default: now). */
+    at?: number;
+}
+export interface IngestOptions {
+    scope?: Scope;
+    /** Idempotency / provenance key. Default: a content hash (see `ingestSourceId`) — retries dedup. */
+    sourceId?: string;
+    /** Observation time in epoch µs — the claims' `valid_from` (default: now). */
+    observedAt?: number;
+    /** Provenance kind (default `operator`). */
+    source?: Source;
+    /** The RAW source text the facts were extracted from — captured into the verbatim lane (lossless backstop). */
+    rawContext?: string;
+    /** Track A1: the git-style branch NAME to write to (default `"main"`). */
+    branch?: string;
+    /** The subject derived facts anchor to when the content names none (defaults to the document). */
+    subjectHint?: string;
+    /** Free-form provenance pairs — each becomes a claim on the document entity. */
+    metadata?: Record<string, string>;
+}
+export interface ContextPackOptions {
+    scope?: Scope;
+    /** Epoch µs — default now. */
+    now?: number;
+    /** Read truth as-of this instant (default: now). */
+    asOf?: number;
+    anchor?: string;
+    attribute?: string;
+}
+/** One claim minted by `memories.add`, with its opaque id. */
+export interface AddedMemory {
+    id: string;
+    subject: string;
+    predicate: string;
+    object: string;
+}
+/** `memories.add` result — the episode echo handle + the per-claim memory ids. */
+export interface MemoryAddResult {
+    id: string;
+    status: string;
+    count: number;
+    memories: AddedMemory[];
+    error?: string;
+}
+/** One search hit — `text` is a ready-to-inject line; the structured fields are kept alongside. */
+export interface SearchHit {
+    id: string;
+    text: string;
+    entity: string;
+    subject?: string;
+    predicate?: string;
+    value: string;
+    score: number;
+}
+/** `memories.search` result — check `abstained` FIRST (when true, `results` is empty). */
+export interface MemorySearchResult {
+    abstained: boolean;
+    trace_id: number;
+    results: SearchHit[];
+    reason?: string;
+    /** The MACHINE-readable abstain code (`below_threshold` | `no_candidates` | `provider_unavailable`). */
+    reason_code?: string;
+    /** The configured gate's confidence margin (q̂ − n). */
+    margin?: number;
+    /** Token-efficiency of the packed working set. */
+    packed_tokens?: number;
+    coverage_score?: number;
+    /** working_set: a ready-to-inject context block; answer: the synthesized prose answer. */
+    context_text?: string;
+}
+/** One memory as returned by `memories.get` / `memories.list`. */
+export interface MemoryView {
+    id: string;
+    entity: string;
+    subject?: string;
+    predicate_id: number;
+    predicate?: string;
+    value: string;
+    confidence: number;
+    valid_from: number;
+    valid_until?: number;
+    active: boolean;
+}
+export interface MemoryListResult {
+    memories: MemoryView[];
+    total: number;
+    offset: number;
+    limit: number;
+}
+export interface MemoryUpdateResult {
+    ok: boolean;
+    id?: string;
+    previous_id?: string;
+    error?: string;
+}
+export interface MemoryDeleteResult {
+    ok: boolean;
+    deleted: number;
+}
+export interface AddMemoryOptions {
+    /** Base64 bytes of ANY type — routed through the never-reject ingest_any pipeline. */
+    contentBase64?: string;
+    /** Optional mime hint for `contentBase64` (the sniff verifies). */
+    mime?: string;
+    /** Default subject when the text names none (e.g. a user id). */
+    subjectHint?: string;
+    /** Dedup / idempotency key. */
+    customId?: string;
+    /** When the fact was observed, in epoch µs (default: server clock). */
+    observedAt?: number;
+    /** Reserved free-form metadata (accepted + echoed; not yet indexed). */
+    metadata?: Record<string, unknown>;
+}
+export interface SearchMemoryOptions {
+    /** Optional entity hint (exact fast-path lookup). */
+    anchor?: string;
+    /** Optional predicate hint (exact fast-path lookup). */
+    attribute?: string;
+    /** Result shape: "claims" (default) | "working_set" (adds a ready-to-inject context block) | "answer". */
+    mode?: "claims" | "working_set" | "answer";
+}
+export interface ListMemoryOptions {
+    offset?: number;
+    limit?: number;
+    /** When true, exclude retired/superseded history. */
+    activeOnly?: boolean;
+}
 /**
- * Custom error class for Cilow API errors
+ * The friendly id-based memories surface — the same six verbs as the HTTP API (`/v1/memories/*`) and
+ * the MCP tools. Reached via `client.memories`.
+ *
+ * ```ts
+ * const m = await cilow.memories.add("Maya is a senior engineer at Acme", { subjectHint: "Maya" });
+ * const r = await cilow.memories.search("where does Maya work", { anchor: "Maya", attribute: "employer" });
+ * if (!r.abstained) await cilow.memories.delete(r.results[0].id);
+ * ```
  */
-declare class CilowApiError extends Error {
-    readonly code: string;
-    readonly statusCode: number;
-    readonly details?: Record<string, unknown> | undefined;
-    constructor(message: string, code: string, statusCode: number, details?: Record<string, unknown> | undefined);
+export interface MemoriesApi {
+    add(content: string, opts?: AddMemoryOptions): Promise<MemoryAddResult>;
+    search(query: string, opts?: SearchMemoryOptions): Promise<MemorySearchResult>;
+    /** Fetch one memory by id; resolves to `null` if it doesn't exist (or isn't this tenant's). */
+    get(id: string): Promise<MemoryView | null>;
+    list(opts?: ListMemoryOptions): Promise<MemoryListResult>;
+    update(id: string, value: string, opts?: {
+        observedAt?: number;
+    }): Promise<MemoryUpdateResult>;
+    delete(id: string, opts?: {
+        at?: number;
+    }): Promise<MemoryDeleteResult>;
+    batchAdd(items: Array<{
+        content: string;
+    } & AddMemoryOptions>): Promise<{
+        count: number;
+        results: MemoryAddResult[];
+    }>;
 }
 /**
- * CilowClient - Main client class for interacting with the Cilow API
- *
- * @example
- * ```typescript
- * const client = new CilowClient({
- *   apiUrl: 'https://api.cilow.ai',
- *   apiKey: 'your-api-key'
- * });
+ * A thin, typed client for a running cilow-serve. One instance, five verbs:
  *
- * // Store a memory
- * const memoryId = await client.remember("User prefers dark mode", {
- *   tags: ["preference", "ui"]
- * });
- *
- * // Search memories
- * const results = await client.recall("user preferences");
- *
- * // Delete memories
- * await client.forget({ tags: ["old"] });
+ * ```ts
+ * const cilow = new CilowClient({ baseUrl: "http://localhost:8080", token: "demo" });
+ * await cilow.remember([{ subject: "Maya", predicate: "employer", object: "Acme" }]);
+ * const r = await cilow.recall("where does Maya work", { anchor: "Maya", attribute: "employer" });
+ * if (r.abstained) console.log("engine doesn't know:", r.reason);
+ * else console.log(r.claims[0].value); // "Acme"
  * ```
+ *
+ * Handles the JSON-RPC 2.0 envelope, bearer auth, and error mapping. The abstention
+ * contract is surfaced as a plain `abstained` boolean on `recall`/`answer` — never an
+ * exception. CilowError is thrown only for protocol / transport / auth failures.
  */
-declare class CilowClient {
+export declare class CilowClient {
     private readonly baseUrl;
-    private readonly apiKey;
-    private readonly timeout;
-    private readonly retries;
-    private readonly headers;
-    private readonly debug;
-    constructor(config: CilowConfig);
-    /**
-     * Make an API request
-     */
-    private request;
+    private readonly token;
+    private readonly scope;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    /** The friendly id-based memories surface: `client.memories.add(...)` etc. */
+    readonly memories: MemoriesApi;
+    constructor(opts: CilowClientOptions);
+    /** Liveness probe — `GET /health`, no auth. Returns true iff the server is up. */
+    health(): Promise<boolean>;
+    /** Ingest `(subject, predicate, object)` facts as bitemporal claims. Returns the write receipt. */
+    remember(facts: Fact[], opts?: RememberOptions): Promise<RememberResponse>;
     /**
-     * Store a memory (simple API)
-     *
-     * @param content - The content to remember
-     * @param options - Optional configuration
-     * @returns The created memory ID
-     *
-     * @example
-     * ```typescript
-     * await cilow.remember("User prefers dark mode", {
-     *   tags: ["preference"],
-     *   userId: "user-123"
-     * });
-     * ```
+     * Retrieve claims as-of a valid-time T, OR a calibrated abstain. Check `abstained`
+     * first. When true, `claims` is empty; use the caller's fallback or safe-deferral policy.
      */
-    remember(content: string, options?: CreateMemoryOptions): Promise<string>;
+    recall(query: string, opts?: RecallOptions): Promise<RecallResponse>;
     /**
-     * Search memories (simple API)
-     *
-     * @param query - Search query text
-     * @param options - Search options
-     * @returns Array of search results
-     *
-     * @example
-     * ```typescript
-     * const memories = await cilow.recall("user preferences", {
-     *   limit: 10,
-     *   tags: ["preference"]
-     * });
-     * ```
-     */
-    recall(query: string, options?: {
-        limit?: number;
-        minRelevance?: number;
-        tags?: string[];
-        userId?: string;
-    }): Promise<SearchResult[]>;
-    /**
-     * Delete memories (simple API)
-     *
-     * @param filter - Filter criteria for deletion
-     * @returns Number of memories deleted
-     *
-     * @example
-     * ```typescript
-     * // Delete by tags
-     * await cilow.forget({ tags: ["temporary"] });
-     *
-     * // Delete by user
-     * await cilow.forget({ userId: "user-123" });
-     *
-     * // Delete specific memory
-     * await cilow.forget({ memoryId: "mem-abc" });
-     * ```
+     * Present-time synthesized answer with citations, OR a calibrated abstain. When
+     * `abstained` is true, `text` is the honored abstain message and `citations` is empty.
      */
-    forget(filter: {
-        memoryId?: string;
-        tags?: string[];
-        userId?: string;
-        sessionId?: string;
-        olderThan?: string;
-    }): Promise<number>;
+    answer(query: string, opts?: AnswerOptions): Promise<AnswerResponse>;
     /**
-     * Create a new memory
+     * Track A1 — create a git-style BRANCH of this tenant's memory (O(1), copies nothing). Write/
+     * supersede facts on the branch (`remember(facts, { branch: name })`) and they stay ISOLATED from
+     * `main` and other branches; an anchored `recall(q, { branch: name })` inherits main's value as of
+     * the fork for keys the branch never wrote. Check `ok`: false ⇒ rejected (see `error`).
      */
-    createMemory(content: string, options?: CreateMemoryOptions): Promise<Memory>;
+    fork(name: string, opts?: ForkOptions): Promise<ForkResponse>;
+    /** Track A1 — list this tenant's git-style branches (`main` first, then forks in name order). */
+    branchList(opts?: {
+        scope?: Scope;
+    }): Promise<Branch[]>;
+    /** The as-of-T bitemporal history of an entity's claims, ascending by `valid_from`. */
+    timeline(entity: string, opts?: TimelineOptions): Promise<TimelineEntry[]>;
+    /** Register / resolve an entity name to its canonical id + alias class as-of `at`. */
+    trackEntity(name: string, opts?: TrackEntityOptions): Promise<TrackEntityResponse>;
     /**
-     * Get a memory by ID
-     */
-    getMemory(memoryId: string): Promise<Memory>;
-    /**
-     * Update a memory
-     */
-    updateMemory(memoryId: string, updates: UpdateMemoryOptions): Promise<Memory>;
-    /**
-     * Delete a memory
-     */
-    deleteMemory(memoryId: string): Promise<void>;
-    /**
-     * List memories with pagination
+     * Report the outcome of a prior `recall` (by its `traceId`) so memory LEARNS — the
+     * outcome-feedback loop. A `"positive"` outcome reinforces the cited claims; `"negative"`
+     * down-weights them; either way the calibrated abstain gate's q̂ self-tunes. This is
+     * in-context learning at the memory layer — no model retraining.
+     *
+     * Check `.applied`: when FALSE the feedback was rejected (`.error` is `"unknown_trace"` or
+     * `"cross_tenant"`) and nothing was mutated. A cross-tenant attempt does NOT consume the
+     * owner's trace.
      */
-    listMemories(options?: {
-        limit?: number;
-        offset?: number;
-        userId?: string;
-        sessionId?: string;
-        tags?: string[];
-        tier?: string;
-    }): Promise<PaginatedResponse<MemorySummary>>;
+    feedback(traceId: number, outcome: Outcome, opts?: FeedbackOptions): Promise<FeedbackResponse>;
     /**
-     * Search memories with full options
+     * Run the idle-time episodic→semantic pass for this tenant: promote corroborated claims,
+     * collapse supersession chains into queryable transitions, and decay stale never-recalled
+     * claims. Retire-not-delete — as-of-T history is preserved. Returns the counts.
      */
-    searchMemories(query: SearchQuery): Promise<SearchResult[]>;
+    consolidate(opts?: ConsolidateOptions): Promise<ConsolidateResponse>;
     /**
-     * Advanced search with reranking and boosts
+     * "Just add text": ingest free PROSE. A language model extracts (subject, predicate, object) facts,
+     * written as calibrated bitemporal claims — no hand-structuring. `subjectHint` is the default subject
+     * for a fact the text does not name. Check `.ok`: false ⇒ the text couldn't be read (`.error` says why).
      */
-    advancedSearch(query: AdvancedSearchOptions): Promise<SearchResult[]>;
+    rememberText(text: string, subjectHint: string, opts?: RememberTextOptions): Promise<RememberTextResponse>;
     /**
-     * Get context for AI applications
+     * Make an image part of memory: a vision model reads it into a caption + facts, written as claims —
+     * so the image is recallable by an ordinary TEXT query. `imageBase64` is the raw base64 (no data: prefix).
+     * Check `.ok`: false ⇒ the image couldn't be read (`.error`).
      */
-    getContext(query: string, options?: {
-        maxTokens?: number;
-        userId?: string;
-        tags?: string[];
-    }): Promise<ContextResult>;
+    ingestImage(imageBase64: string, mime: string, subjectHint: string, opts?: IngestImageOptions): Promise<IngestImageResponse>;
     /**
-     * Store a conversation turn
+     * Make an audio clip part of memory: it's transcribed, then the transcript is written as a claim AND
+     * run through the same text→facts extraction prose uses — so the audio is recallable by an ordinary
+     * TEXT query. `audioBase64` is the raw base64 (no data: prefix). Check `.ok`: false ⇒ couldn't read (`.error`).
      */
-    storeConversation(turn: ConversationTurn & {
-        userId: string;
-    }): Promise<string>;
+    ingestAudio(audioBase64: string, mime: string, subjectHint: string, opts?: IngestAudioOptions): Promise<IngestAudioResponse>;
     /**
-     * Get conversation history for a session
+     * Make a PDF part of memory via the hybrid path: the text layer is extracted AND each page is rendered
+     * to an image read by a VLM, both written as claims — so a document (text-based or scanned) is
+     * recallable by an ordinary TEXT query. `pdfBase64` is the raw base64 (no data: prefix). Check `.ok`.
      */
-    getConversationHistory(sessionId: string, options?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<MemorySummary[]>;
+    ingestPdf(pdfBase64: string, subjectHint: string, opts?: IngestPdfOptions): Promise<IngestPdfResponse>;
     /**
-     * Get a graph node
+     * Ingest clean CSV or JSON DIRECTLY into claims — no LLM, no hallucination, no token cost. Each row is
+     * an entity, each column/key a predicate, each value an object. `format` is "csv" or "json";
+     * `subjectField` names the column/key that is the entity (omit ⇒ subjectHint + row index).
      */
-    getGraphNode(nodeId: string): Promise<GraphNode>;
+    ingestStructured(data: string, format: "csv" | "json", subjectHint: string, opts?: IngestStructuredOptions): Promise<IngestStructuredResponse>;
     /**
-     * Create a graph node
+     * Primary universal save API: hand Cilow literally any data. Pass exactly one of
+     * `contentBase64` (any bytes) or `text` (prose / CSV / JSON / a bare URL) in `content`. The data is
+     * sniffed, the ORIGINAL retained durably (`raw_id`/`blob_id`), a document entity + metadata claims
+     * written (so even unknown bytes are findable), and the matching typed reader runs when one exists.
+     * Reader/provider failures are surfaced in-band as `status: "degraded"` + `reader_error`, not as a
+     * calibrated "memory does not know" read abstain.
      */
-    createGraphNode(type: string, name: string, properties?: Record<string, unknown>): Promise<GraphNode>;
+    save(content: {
+        contentBase64: string;
+    } | {
+        text: string;
+    }, opts?: IngestAnyOptions): Promise<IngestAnyResponse>;
     /**
-     * Create a graph edge
+     * Legacy alias for `save`: the universal NEVER-REJECT ingest. Pass exactly one of
+     * `contentBase64` (any bytes) or `text` (prose / CSV / JSON / a bare URL) in `content`. The data is
+     * sniffed, the ORIGINAL retained durably (`blob_id`), a document entity + metadata claims written
+     * (so even unknown bytes are findable), and the matching typed reader runs when one exists (a URL
+     * is fetched + snapshotted; replay never re-fetches). `ok` is false only for malformed ARGUMENTS;
+     * unknown types and reader failures are `ok: true` with `routed` absent + `reader_error` set.
      */
-    createGraphEdge(sourceId: string, targetId: string, type: string, properties?: Record<string, unknown>): Promise<GraphEdge>;
+    ingestAny(content: {
+        contentBase64: string;
+    } | {
+        text: string;
+    }, opts?: IngestAnyOptions): Promise<IngestAnyResponse>;
     /**
-     * Traverse the graph from a starting node
+     * Retire memory (retire-not-delete), or destroy it when `erase: true` (OF1).
+     *
+     * Retire: omit `attribute` to forget the whole entity, set it to forget one attribute, add
+     * `value` to forget one value. As-of-T history before `at` is preserved.
+     *
+     * Erase: whole-entity destruction; counters on the receipt. Not complete Art.17.
      */
-    traverseGraph(options: GraphTraversalOptions): Promise<GraphSubgraph>;
+    forget(entity: string, opts?: ForgetOptions): Promise<ForgetResponse>;
+    /** Destructive right-to-be-forgotten path — `forget(entity, { erase: true })`. */
+    erase(entity: string, opts?: {
+        scope?: Scope;
+        at?: number;
+    }): Promise<ForgetResponse>;
     /**
-     * Get related nodes for a memory
+     * Curated injectible pack + citations + trunk/suffix — no free-form synthesis (D2).
+     * When session trunk is on and `session != 0`, `trunk` is the stable multi-turn prefix.
      */
-    getRelatedNodes(memoryId: string): Promise<GraphNode[]>;
+    contextPack(query: string, opts?: ContextPackOptions): Promise<ContextPackResponse>;
     /**
-     * Get memory statistics
+     * The ONE write door (core verb #1): store `{ facts }` | `{ text }` | `{ url }` | `{ contentBase64 }`.
+     *
+     * - `facts` — `[{ subject, predicate, object, multi? }]`. Rides the `remember` path. A new value for
+     *   an exclusive attribute SUPERSEDES the old one (history stays queryable via `contextPack({ asOf })`);
+     *   `multi: true` on a fact lets values coexist. `source` / `rawContext` / `branch` apply here.
+     * - `text` (prose / CSV / JSON), `url` (a bare URL — sent as `text`; the server fetches + snapshots
+     *   it), `contentBase64` (+ `mime` hint) — ride the never-reject `ingest_any` path: the original is
+     *   retained durably (`content.blob_id`), a document entity + `metadata` claims are written, and the
+     *   matching typed reader runs when one exists. `subjectHint` / `metadata` apply here.
+     *
+     * `sourceId` defaults to a CONTENT HASH (`ingestSourceId`) so a retry of the same payload is an
+     * idempotent no-op; the key actually sent is echoed on `source_id`. Never throws for content —
+     * only for a transport / auth failure.
      */
-    getStats(): Promise<MemoryStats>;
+    ingest(content: IngestContent, opts?: IngestOptions): Promise<IngestResponse>;
     /**
-     * Get all tags with counts
+     * Why did a pack / recall surface what it surfaced? (core verb #4) Pass the `trace_id` from a
+     * `contextPack` / `recall` response. The report carries the cited claims (labels resolved, each with
+     * its inclusion probability), the read's `best_nonconformity` vs the tenant's grounding threshold
+     * `q_hat`, and whether the read was grounded (`isGrounded(r)`) or a gap. Read-only: explaining never
+     * consumes the feedback trace. `found: false` + `error` (`unknown_trace` / `cross_tenant`) is in-band.
      */
-    getTags(): Promise<TagCount[]>;
+    explain(traceId: number, opts?: {
+        scope?: Scope;
+    }): Promise<ExplainResponse>;
     /**
-     * Get user statistics
+     * Read a retained original back by its hex `blob_id` (from an ingest receipt or `blobList`).
+     * Full sha256-verified read by default; pass `offset`/`length` for a chunk-indexed RANGE read
+     * of a large blob (EOF-clamped; `total_len` in the response lets you paginate; `byte_len` is
+     * the returned window). `found:false` with no `error` is an ordinary miss; `error` in
+     * {invalid_id, invalid_range, storage, corrupt} means the range read FAILED — never treat it
+     * as absence. Bytes ride back in `data_base64`.
      */
-    getUserStats(userId: string): Promise<UserStats>;
+    blobGet(blobId: string, opts?: {
+        offset?: number;
+        length?: number;
+        scope?: Scope;
+    }): Promise<BlobGetResponse>;
     /**
-     * Health check
+     * One retained blob's METADATA (mime, byte length, provenance, metadata pairs, chunk count) by
+     * hex `blob_id` — no bytes. `found:false` ⇒ this tenant retains no such blob.
      */
-    healthCheck(): Promise<HealthCheck>;
+    blobMeta(blobId: string, scope?: Scope): Promise<BlobMetaResponse>;
+    /** Enumerate this tenant's retained original blobs with metadata (no bytes), deterministically ordered. */
+    blobList(scope?: Scope): Promise<BlobListResponse>;
+    createContextWorkspace(name: string, scope?: Scope): Promise<WorkspaceResponse>;
+    ingestEvidence(input: {
+        workspaceId: string;
+        sourceId: string;
+        sourceRevision: string;
+        text: string;
+        mime?: string;
+        metadata?: Record<string, string>;
+        coordinates?: Array<Record<string, unknown>>;
+        trust?: "untrusted" | "user_provided" | "tool_observed" | "operator_verified";
+        aclPrincipals?: string[];
+        scope?: Scope;
+    }): Promise<EvidenceResponse>;
+    investigate(workspaceId: string, query: string, opts?: {
+        tokenBudget?: number;
+        scope?: Scope;
+    }): Promise<InvestigateResponse>;
+    compileContext(workspaceId: string, query: string, opts: {
+        modelId: string;
+        tokenizerId: string;
+        modelContextTokenBudget?: number;
+        auditPayloadByteBudget?: number;
+        promptTemplateId?: string;
+        asOf?: number;
+        scope?: Scope;
+    }): Promise<CompileContextResponse>;
+    getCompiledContext(receiptId: string, scope?: Scope): Promise<CompileContextResponse>;
+    getContextTrace(traceId: string, scope?: Scope): Promise<TraceResponse>;
+    recordAgentEpisode(workspaceId: string, summary: string, evidenceIds: string[], scope?: Scope): Promise<EpisodeResponse>;
+    proposeMemory(input: {
+        workspaceId: string;
+        episodeId: string;
+        subject: string;
+        predicate: string;
+        value: string;
+        evidenceIds: string[];
+        scope?: Scope;
+    }): Promise<MemoryResponse>;
+    verifyMemory(proposalId: string, accept: boolean, reason: string, scope?: Scope): Promise<MemoryResponse>;
+    private mergeScope;
     /**
-     * Batch create memories
+     * Issue one JSON-RPC `tools/call` and return the engine's `structuredContent`.
+     * Maps every failure mode (transport, HTTP, JSON-RPC error, malformed body) to a CilowError.
      */
-    batchCreate(items: Array<{
-        content: string;
-        options?: CreateMemoryOptions;
-    }>): Promise<string[]>;
+    private call;
     /**
-     * Batch delete memories
+     * POST to `/v1/memories/<verb>` and return the parsed JSON body (plain REST, not JSON-RPC). With
+     * `allow404`, a 404 resolves to `null` (used by `memories.get`). Other 4xx/5xx throw a CilowError
+     * carrying the body's `error` string.
      */
-    batchDelete(memoryIds: string[]): Promise<number>;
+    private callRest;
 }
-/**
- * Create a Cilow client instance (convenience function)
- */
-declare function createClient(config: CilowConfig): CilowClient;
-
-export { CilowApiError, CilowClient, createClient };
+//# sourceMappingURL=client.d.ts.map