cogmemory 0.0.1-beta.2

package/dist/index.d.ts

@@ -0,0 +1,1086 @@
+import { $Fetch } from 'ofetch';
+
+export declare interface AddTensionRequest {
+    claimA: string;
+    claimB: string;
+    impact?: Impact;
+    actionableQuestion: string;
+}
+
+export declare interface ArbiterEvaluationResult {
+    promotions: Array<{
+        memoryId: string;
+        targetTier: "L1";
+        signalType: "anticipatory" | "tension" | "proprioceptive" | "recency";
+        urgency: number;
+    }>;
+    demotions: Array<{
+        memoryId: string;
+        targetTier: "L2";
+        reason: string;
+    }>;
+    pins: Array<{
+        memoryId: string;
+        targetTier: "L0";
+        reason: string;
+    }>;
+    detectedTensions: Array<{
+        claimA: string;
+        claimB: string;
+        impact: TensionImpact;
+        actionableQuestion: string;
+    }>;
+    trajectoryPrediction?: TrajectoryPrediction;
+    selfModelUpdate?: {
+        domain: string;
+        success?: boolean;
+        failurePatternObserved?: string;
+    };
+}
+
+export declare type ArbiterFn = (params: {
+    turnText: string;
+    assistantReply: string;
+    l0Prompt: string;
+    l1Summaries: Array<{
+        id: string;
+        bookmark: string;
+        domains: string[];
+    }>;
+    candidates: Array<{
+        id: string;
+        bookmark: string;
+        domains: string[];
+        hasTension?: boolean;
+    }>;
+}) => Promise<ArbiterEvaluationResult>;
+
+/**
+ * Floor for *candidate* recall, not a similarity decision.
+ *
+ * Deliberately low. This only decides who gets adjudicated; a tight gate misses
+ * exactly the paraphrases worth merging.
+ */
+export declare const CANDIDATE_FLOOR = 0.3;
+
+export declare interface Claim {
+    source: string;
+    statement: string;
+    timestamp: number;
+}
+
+/**
+ * The client.
+ *
+ * Named `Cogmem` rather than `CognitiveMemory` because that name belongs to the
+ * in-process engine, and has for as long as this layer existed. Two exports
+ * cannot share a name, and the engine's is the older public API: quietly
+ * redefining it to mean an HTTP client would break every consumer of it.
+ *
+ * Resource classes rather than a flat list of functions, because
+ * `memory.memories.` in an editor shows every operation on memories and nothing
+ * else. The methods stay one-to-one with endpoints, so the class never becomes a
+ * second, divergent copy of the service.
+ *
+ * `readonly` on the resources is not decoration: it stops a caller reassigning
+ * `memory.memories` and wondering why the other half of the client stopped
+ * seeing the change.
+ */
+export declare class Cogmem {
+    private readonly client;
+    readonly baseUrl: string;
+    readonly memories: MemoriesResource;
+    readonly context: ContextResource;
+    readonly recall: RecallResource;
+    readonly turns: TurnsResource;
+    readonly tensions: TensionsResource;
+    readonly selfModel: SelfModelResource;
+    readonly stats: StatsResource;
+    constructor(config: CognitiveMemoryConfig);
+    /**
+     * Liveness and limits, without spending a request on the configured key.
+     *
+     * Useful in a readiness probe: if `extractor` is `rules-only` the service is up
+     * but is not doing model-backed extraction, and `problems` is non-empty when a
+     * setting is present but unusable.
+     */
+    health(): Promise<Health>;
+}
+
+export declare class CognitiveMemory {
+    private activeTensions;
+    private selfModel;
+    private activeTaskTrace;
+    private l1HotCache;
+    private l2WarmStore;
+    private l3ColdArchive;
+    private maxL0Tokens;
+    private maxL1Tokens;
+    /** Ceiling on everything injected into one prompt, index and bodies together. */
+    private maxTotalTokens;
+    private arbiter;
+    private autoExtractMemories;
+    /** Model-backed turn extractor; the regex fallback runs when this is absent. */
+    private reconcile?;
+    private extract?;
+    private onPersist?;
+    private stats;
+    constructor(options?: CognitiveMemoryOptions);
+    /**
+     * Sub-1ms synchronous call to produce the prompt context block.
+     * Concatenates L0 (active tensions + self-model) and pre-staged L1.
+     * Adds zero latency to TTFT.
+     */
+    /**
+     * Decide what goes into this turn's prompt, and record why.
+     *
+     * Follows the index/body split that Claude Code's `MEMORY.md` and Letta's
+     * progressive disclosure both converged on: a short index of every memory is
+     * always present, and a body is only spent where a deterministic signal earned
+     * it. Always injecting bodies costs an order of magnitude more tokens and, per
+     * Chroma's context-rot work, injects distractors by construction.
+     *
+     * @param forceFull memory ids whose body should be included regardless of tier.
+     */
+    planInjection(options?: {
+        userMessage?: string;
+        forceFull?: Iterable<string>;
+    }): MemoryInjectionReport;
+    /** Prompt text only. Prefer `planInjection` when you want to log what went in. */
+    getPromptContext(currentUserMessage?: string): string;
+    /**
+     * Search every tier for memories relevant to `query`.
+     *
+     * This is the on-demand path, exposed to the agent as a tool. Pre-staging into
+     * the prompt is a best-effort optimisation; a model that does not read the
+     * block, or whose question shares no words with it, can still ask. Ranking is
+     * deterministic — no model involved — so recall does not depend on model
+     * quality.
+     */
+    search(query: string, limit?: number): Array<{
+        item: MemoryItem;
+        score: number;
+    }>;
+    /**
+     * Post-turn asynchronous execution.
+     * Fired when the agent finishes streaming its response to the user.
+     * Evaluates turn, manages L1 cache, detects tensions, updates self-model.
+     */
+    postTurnAsync(params: {
+        userMessage: string;
+        assistantResponse: string;
+        detectedDomains?: string[];
+    }): Promise<void>;
+    /**
+     * Fold extracted memories and tensions in, skipping anything already known.
+     *
+     * Extracted items land in L2 rather than L1: they are candidates, and the
+     * arbiter decides what is worth pre-staging. That is what gives the tiering
+     * something to actually do — previously nothing ever wrote to L2, so every
+     * arbiter run evaluated an empty candidate set.
+     */
+    private applyExtraction;
+    /** Drop an entry by its exact content. */
+    private removeByContent;
+    /** Rewrite one entry's text in place, matched on its old value. */
+    private replaceByContent;
+    /** Replace an entry's content, keeping its identity and tags. */
+    private enrich;
+    /**
+     * Fold a duplicate into its survivor, refusing rewrites that drop anything.
+     *
+     * `merge` returns the model's idea of the fuller statement, and overwriting
+     * with it deletes whatever the model happened to leave out. The under-merge
+     * bias covers merging the *wrong* pair, but nothing covered a lossy rewrite
+     * of the right pair, so containment is checked first.
+     *
+     * @returns false when the rewrite would lose information, in which case the
+     * caller keeps both entries.
+     */
+    private mergeInto;
+    /** Retire the entries a replacement supersedes, keeping them out of retrieval. */
+    private supersede;
+    /**
+     * Existing memories worth adjudicating a candidate against.
+     *
+     * Cheap and deliberately over-inclusive. An identical string short-circuits
+     * because it is never worth a model call; anything else above the recall floor
+     * is offered to the adjudicator, which decides.
+     */
+    private recallSimilar;
+    /**
+     * Keep the pinned tiers within budget.
+     *
+     * `maxL0Tokens`/`maxL1Tokens` were stored but never read, so L1 grew for the
+     * lifetime of the process. Evict least-recently-accessed first, and demote to
+     * L2 rather than dropping, so nothing is lost.
+     */
+    private enforceBudgets;
+    /**
+     * Add a known tension manually or from an external source.
+     */
+    addTension(tension: KnowledgeTension): void;
+    /**
+     * Mark a tension resolved with an optional reusable pattern.
+     */
+    resolveTension(id: string, resolution: {
+        resolvedBy: string;
+        pattern: string;
+    }): boolean;
+    /**
+     * Add a memory directly to L2 warm storage or promote to L1.
+     */
+    addMemory(item: MemoryItem, targetTier?: CognitiveMemoryTier): void;
+    /**
+     * Drop one memory by id, from whichever tier holds it.
+     *
+     * The counterpart to `addMemory`, and the only way to retire a fact that has
+     * turned out to be wrong. One map is not enough to look in: a promotion or a
+     * demotion moves an id between them, so an id that is absent from the hot
+     * cache may still be in the warm store or the archive. Short-circuiting on the
+     * first hit is therefore safe — an id lives in exactly one of the three.
+     */
+    removeMemory(id: string): boolean;
+    /**
+     * Update the proprioceptive capability record for a domain.
+     */
+    recordDomainOutcome(domain: string, success: boolean, failurePattern?: string): void;
+    getSnapshot(): CognitiveMemoryStateSnapshot;
+    loadSnapshot(snapshot: CognitiveMemoryStateSnapshot): void;
+    private applyArbiterDecision;
+    /**
+     * Fast default heuristic arbiter when an LLM arbiter model is not supplied.
+     */
+    private runHeuristicArbiter;
+    private autoExtractTurnMemory;
+}
+
+export declare interface CognitiveMemoryConfig {
+    apiKey: string;
+    /** Defaults to the current origin in a browser, or localhost otherwise. */
+    baseUrl?: string;
+    /** Per-request timeout in ms. */
+    timeout?: number;
+    /** Retries for transient failures. 0 disables. */
+    retry?: number;
+    /**
+     * Log every request and response.
+     *
+     * On by default for anyone who has been burned by a wrong base URL, which is
+     * everyone exactly once.
+     */
+    debug?: boolean;
+    headers?: Record<string, string>;
+}
+
+/**
+ * One error class for every failure the service can produce.
+ *
+ * The service already returns a structured envelope — a tag, a message, the
+ * scope that was missing, the fields that failed validation — so the SDK's job is
+ * to hand that over as a typed object instead of making callers dig through
+ * `error.response.data`.
+ *
+ * The predicate methods exist so callers ask semantic questions. `status === 403`
+ * scatters a magic number through every integration and means something slightly
+ * different at each one; `isScopeError()` means the same thing everywhere.
+ */
+export declare class CognitiveMemoryError extends Error {
+    /**
+     * Set as a real value, because a minifier renames the class and that silently
+     * changes what monitoring groups on. `error.name` is correct either way — the
+     * constructor assigns it — but `SomeError.name` and `error.constructor.name`
+     * are how a reporter identifies a class, and a minified `"h"` breaks that.
+     */
+    static readonly name = "CognitiveMemoryError";
+    /** The service's own tag: `Unauthorized`, `Forbidden`, `InvalidRequest`, … */
+    readonly code: string;
+    readonly status: number;
+    /** Present on a 403: the scope the key would have needed. */
+    readonly requiredScope?: string;
+    /** Present on a 400: which field, and why. */
+    readonly issues?: string[];
+    readonly body?: CognitiveMemoryErrorBody;
+    constructor(message: string, init: {
+        status: number;
+        code: string;
+        body?: CognitiveMemoryErrorBody;
+        requiredScope?: string;
+        issues?: string[];
+    });
+    /** The key is missing, malformed, expired or revoked. */
+    isAuthError(): boolean;
+    /** The key is valid but lacks a scope. `requiredScope` says which. */
+    isScopeError(): boolean;
+    /** The request body did not match the schema. `issues` says where. */
+    isValidationError(): boolean;
+    /** Nothing exists at that id — or it belongs to another organisation. */
+    isNotFoundError(): boolean;
+    isRateLimitError(): boolean;
+    /** A dependency of ours failed, not the request. Safe to retry. */
+    isServerError(): boolean;
+}
+
+/** The error envelope every non-2xx response carries. */
+export declare interface CognitiveMemoryErrorBody {
+    error: string;
+    message: string;
+    requiredScope?: string;
+    resource?: string;
+    id?: string;
+    issues?: string[];
+}
+
+export declare interface CognitiveMemoryOptions {
+    /** Maximum token budget for L0 (default: 2000) */
+    maxL0Tokens?: number;
+    /** Maximum token budget for L1 hot cache (default: 8000) */
+    maxL1Tokens?: number;
+    /** Ceiling on everything injected into a single prompt (index + bodies). Default 2000. */
+    maxTotalTokens?: number;
+    /** Custom Arbiter evaluator function (e.g. powered by Jev, Gemini Flash, or local model) */
+    arbiter?: ArbiterFn;
+    /** Initial self-model */
+    initialSelfModel?: Partial<ProprioceptiveSelfModel>;
+    /** Auto-extract candidate items from completed turns (default: true) */
+    autoExtractMemories?: boolean;
+    /**
+     * Adjudicate a candidate memory against ones that already exist.
+     *
+     * Lexical overlap cannot make this call: it peaks on identical strings and
+     * bottoms out on the paraphrases that actually add information. Every mature
+     * memory system therefore recalls candidates cheaply and then asks a model,
+     * explicitly allowing "no match". `remember` is the low-bar candidate
+     * recall; `decide` is the precision step.
+     */
+    reconcile?: (input: {
+        /** Every candidate from this turn that resembles something we hold. */
+        items: Array<{
+            candidate: string;
+            remember: string[];
+        }>;
+    }) => Promise<MemoryReconciliation[]>;
+    /**
+     * Model-backed turn extractor. Preferred over the built-in regex, which only
+     * recognises "always/never/make sure to/remember to" and therefore never
+     * learned ordinary project facts. Return an empty array to learn nothing.
+     */
+    extract?: (turn: {
+        userMessage: string;
+        assistantResponse: string;
+    }) => Promise<{
+        memories: Array<{
+            content: string;
+            domains?: string[];
+        }>;
+        tensions?: Array<{
+            claimA: string;
+            claimB: string;
+            impact: "low" | "medium" | "critical";
+            actionableQuestion: string;
+        }>;
+    }>;
+    /** Persistence callback to save L2/L3 state */
+    onPersist?: (state: CognitiveMemoryStateSnapshot) => Promise<void> | void;
+}
+
+export declare interface CognitiveMemoryStateSnapshot {
+    l0: {
+        tensions: KnowledgeTension[];
+        selfModel: ProprioceptiveSelfModel;
+        activeTaskTrace: string;
+    };
+    l1: MemoryItem[];
+    l2: MemoryItem[];
+    l3: MemoryItem[];
+    stats: {
+        totalTurnsProcessed: number;
+        predictionsHit: number;
+        predictionsTotal: number;
+        tensionsDetected: number;
+    };
+}
+
+/**
+ * Cognitive Memory types and contracts for not-another-harness.
+ */
+export declare type CognitiveMemoryTier = "L0" | "L1" | "L2" | "L3";
+
+/** Two results this similar are the same memory, restated. */
+export declare const COLLAPSE_THRESHOLD = 0.8;
+
+export declare interface ContextEntry {
+    id: string;
+    tier: MemoryTier;
+    reason: InclusionReason;
+    gist: string;
+    /** Absent for `index` entries: a line is all those cost. */
+    body?: string;
+    tokens: number;
+}
+
+export declare interface ContextReport {
+    /** Prepend this to the system prompt. Empty when there is nothing to say. */
+    text: string;
+    entries: ContextEntry[];
+    totalTokens: number;
+    /** True when the token budget forced something out. */
+    truncated: boolean;
+}
+
+export declare interface ContextRequest {
+    /** The message about to be answered. Drives the triggers. */
+    userMessage?: string;
+    /** Ids whose body to include regardless of tier. */
+    forceFull?: string[];
+    maxTokens?: number;
+}
+
+/**
+ * The prompt block.
+ *
+ * One call per turn, and the reason the service exists: a one-line index of
+ * everything remembered, plus full bodies only where a named identifier, an
+ * unresolved contradiction, or a weak domain earned them.
+ */
+export declare class ContextResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    build(request?: ContextRequest): Promise<ContextReport>;
+}
+
+/**
+ * Both construction styles, deliberately.
+ *
+ * Some people prefer `new Cogmem(...)` and some prefer `createClient(...)`; there
+ * is no reason to make anyone rename. The factory is also the easier one to mock
+ * in tests, which is the whole reason `createHttpClient` is a function.
+ */
+export declare function createClient(config: CognitiveMemoryConfig): Cogmem;
+
+/**
+ * Configuration, as a factory rather than a constructor.
+ *
+ * A constructor with fifteen options is a dumping ground: configuration and
+ * instantiation get tangled, tests have to construct a whole class to check one
+ * header, and "the client with a different timeout" becomes a subclass. A factory
+ * is a plain function — no `new`, no `this`, composable, trivially mockable.
+ *
+ * The real work happens in the interceptors. Authentication, error translation
+ * and debug logging are configured once here instead of being repeated in each
+ * of the twenty-odd methods below, which is the difference between changing how
+ * auth works in one place and in twenty.
+ */
+export declare function createHttpClient(config: CognitiveMemoryConfig): $Fetch;
+
+/**
+ * Deterministic fact extraction.
+ *
+ * A model extractor is good at judgement but it is still a model: it can
+ * refuse, hedge, or return nothing, and a fact the user plainly stated then
+ * never gets learned. Everything stated unambiguously is captured here with
+ * plain pattern matching, and the model is layered on top for the subtler cases.
+ *
+ * Only high-confidence shapes are matched. Being wrong in this direction writes
+ * a useless memory; being silent loses a real one, which is the worse failure.
+ */
+export declare interface DeterministicMemory {
+    readonly content: string;
+    readonly domains: Array<string>;
+}
+
+/**
+ * Tokens that carry a fact's identity: identifiers, numbers, codes.
+ *
+ * Function words and generic nouns are dropped because they recur in every
+ * restatement and hide real differences.
+ */
+export declare const distinctiveTokens: (value: string) => Set<string>;
+
+export declare interface DomainCapability {
+    reliabilityScore: number;
+    sampleCount: number;
+    knownFailurePatterns: string[];
+    recommendedStrategies: string[];
+}
+
+declare interface DomainCapability_2 {
+    reliabilityScore: number;
+    sampleCount: number;
+    knownFailurePatterns: string[];
+    recommendedStrategies: string[];
+}
+
+export declare interface DomainOutcomeRequest {
+    domain: string;
+    success: boolean;
+    failurePattern?: string;
+    strategy?: string;
+}
+
+/** Approximate token cost of a string. */
+export declare const estimateTokens: (value: string) => number;
+
+/**
+ * Extract statements the user made that are worth remembering, without a model.
+ */
+export declare const extractDeterministic: (userMessage: string) => Array<DeterministicMemory>;
+
+export declare const extractDomains: (text: string) => string[];
+
+/**
+ * Identifiers worth matching a memory against: URLs, paths, hostnames,
+ * SCREAMING_SNAKE, camelCase, long kebab-case and hex-ish codes.
+ *
+ * The same idea as Aider's `mentioned_idents`: a user naming a concrete thing
+ * is a much stronger signal than the words around it. This is what turns a
+ * recall into a full-body injection without asking a model.
+ */
+export declare const extractIdentifiers: (text: string) => string[];
+
+/**
+ * Fast Heuristic Gate
+ *
+ * Synchronous, sub-5ms gate running on the critical path before model invocation.
+ * Detects explicit user corrections/contradictions and significant domain pivots
+ * without triggering an LLM call.
+ */
+export declare interface FastGateResult {
+    action: "proceed" | "inject_caution";
+    cautionNote?: string;
+    detectedDomains?: string[];
+}
+
+/**
+ * Liveness, and this deployment's limits and extractor mode.
+ *
+ * Takes an explicit base URL because it is the one call that must work with no
+ * key at all — including from a health check that has no credentials.
+ */
+export declare const fetchHealth: (baseUrl: string) => Promise<Health>;
+
+/**
+ * The index line: short, scannable, no body.
+ *
+ * Falling back to the first sentence keeps an index line readable when a memory
+ * arrives from the API without a gist.
+ */
+export declare const gistOf: (item: {
+    readonly content: string;
+    readonly gist?: string | undefined;
+}) => string;
+
+export declare interface Health {
+    ok: boolean;
+    service: string;
+    version: string;
+    /** `rules-only` means no model key is configured; learning is still on. */
+    extractor: "rules-only" | "rules+model";
+    limits: {
+        maxTotalTokens: number;
+        maxIndexItems: number;
+        defaultRecallLimit: number;
+    };
+    /** Non-empty only when a setting was present but unusable. */
+    problems: string[];
+}
+
+export declare type HttpClient = ReturnType<typeof createHttpClient>;
+
+export declare type Impact = "low" | "medium" | "critical";
+
+/** Why a memory body was included. Each reason costs differently. */
+export declare type InclusionReason = "index" | "trigger" | "tension" | "guardrail";
+
+export declare const isInteractionScoped: (content: string) => boolean;
+
+/**
+ * Whether rewriting `original` as `replacement` would drop information.
+ *
+ * Distinctive tokens carry a fact's identity, so a replacement missing one has
+ * deleted something — usually the qualifier that made the two statements differ
+ * at all ("never production", a build id, a port). Trailing plurals are folded
+ * so "deploys" merging into "deploy" is not read as a deletion.
+ *
+ * Biased towards reporting a loss: a false positive costs a duplicate entry,
+ * which is recoverable, while a false negative deletes a fact for good.
+ */
+export declare const isLossyRewrite: (original: string, replacement: string) => boolean;
+
+export declare interface KnowledgeTension {
+    id: string;
+    status: TensionStatus_2;
+    claimA: {
+        source: string;
+        statement: string;
+        timestamp: number;
+    };
+    claimB: {
+        source: string;
+        statement: string;
+        timestamp: number;
+    };
+    impact: TensionImpact;
+    taskRelevance: number;
+    actionableQuestion: string;
+    resolution?: {
+        resolvedAt: number;
+        resolvedBy: string;
+        pattern: string;
+    };
+}
+
+export declare interface LearnResult {
+    /** Newly created. */
+    stored: Memory[];
+    /** Restatements folded into what was already held, and what survived. */
+    mergedInto: Memory[];
+    counts: {
+        stored: number;
+        merged: number;
+        rejected: number;
+        tensions: number;
+        promoted: number;
+    };
+    /** Never silent: a client that sent ten and got three needs the other seven. */
+    rejected: RejectedStatement[];
+}
+
+export declare interface ListMemoriesParams {
+    limit?: number;
+    tier?: MemoryTier;
+}
+
+/** How many existing memories to put in front of an adjudicator. */
+export declare const MAX_CANDIDATES = 8;
+
+/**
+ * Reading and writing what is stored.
+ *
+ * Deliberately thin: one method, one endpoint, no cleverness. The class is a
+ * namespace, so `memory.memories.` offers the whole surface in an editor, but it
+ * is not a place for business logic. The workflow that composes these calls lives
+ * in `../helpers`.
+ */
+export declare class MemoriesResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * The envelope is unwrapped here rather than passed on.
+     *
+     * The service replies with `{ memories, stats }` so a dashboard can get both in
+     * one call, but an SDK caller who asked for a list wants a list. Deciding that
+     * in one place here is better than making every integration know the shape.
+     */
+    list(params?: ListMemoriesParams): Promise<Memory[]>;
+    get(id: string): Promise<Memory>;
+    /**
+     * State facts outright.
+     *
+     * Restatements of something already held are folded in rather than stored
+     * twice, and the result says which ones were folded and into what — a write
+     * that silently did nothing is indistinguishable from a bug.
+     */
+    create(request: RememberRequest): Promise<LearnResult>;
+    /** Move a memory between tiers. L1 is pre-staged into every context build. */
+    promote(id: string, tier: MemoryTier): Promise<Memory>;
+    remove(id: string): Promise<{
+        deleted: boolean;
+        id: string;
+    }>;
+}
+
+export declare interface Memory {
+    id: string;
+    content: string;
+    gist?: string;
+    tier: MemoryTier;
+    domains: string[];
+    accessCount: number;
+    source?: MemorySource;
+    sessionId?: string;
+    /** Epoch milliseconds. */
+    createdAt: number;
+    lastAccessedAt: number;
+}
+
+export declare type MemoryInclusionReason = 
+/** Shown in the always-present index as a gist only. */
+"index"
+/** Unseen identifier in the user's message matched this memory: body included. */
+| "trigger"
+/** Active knowledge tension: body included. */
+| "tension"
+/** Proprioceptive guardrail: body included. */
+| "guardrail";
+
+export declare interface MemoryInjectionEntry {
+    id: string;
+    tier: CognitiveMemoryTier;
+    reason: MemoryInclusionReason;
+    /** Index line only. */
+    gist: string;
+    /** Present only when the body was worth the tokens. */
+    body?: string;
+    /** Rough token cost of what was included. */
+    tokens: number;
+}
+
+/** What was put in the prompt this turn, and why. */
+export declare interface MemoryInjectionReport {
+    text: string;
+    entries: MemoryInjectionEntry[];
+    totalTokens: number;
+    /** True when the total budget forced something out. */
+    truncated: boolean;
+}
+
+export declare interface MemoryItem {
+    id: string;
+    content: string;
+    /** Dense 1-2 sentence representation for fast arbiter scanning */
+    bookmark: string;
+    /**
+     * Short label shown in the pre-staged index (Claude Code's `MEMORY.md` pattern:
+     * the index is always in context, the body is fetched on demand). Falls back to
+     * a truncation of `content` when the extractor did not supply one.
+     */
+    gist?: string;
+    /** Dense embedding vector (empty array if embedding disabled) */
+    embedding?: number[];
+    tier: CognitiveMemoryTier;
+    metadata: MemoryMetadata;
+}
+
+export declare interface MemoryMetadata {
+    domains: string[];
+    isFailurePattern?: boolean;
+    isSuccessfulStrategy?: boolean;
+    isGuardrail?: boolean;
+    sourceSessionId?: string;
+    createdAt: number;
+    lastAccessedAt: number;
+    accessCount: number;
+}
+
+/** Why a memory ended up in the prompt — the thing you tune once you log it. */
+/** What to do with a candidate memory once compared against what we hold. */
+export declare type MemoryReconciliation = {
+    /**
+     * `add` keeps it as a new memory and is the safe default when unsure: an
+     * unmerged duplicate costs a row, while a wrong merge corrupts what we believe.
+     * `merge` collapses a restatement into the existing entry, keeping whichever
+     * carries more information. `replace` supersedes the existing entry. `reject`
+     * drops it as not worth storing.
+     */
+    action: "add" | "merge" | "replace" | "reject";
+    /** Content to store when merging or replacing; defaults to the candidate. */
+    content?: string;
+    /** Why, so a bad merge is diagnosable rather than mysterious. */
+    reason?: string;
+};
+
+/** Where a statement came from. `rules` means no model was involved. */
+export declare type MemorySource = "rules" | "model" | "api";
+
+/**
+ * The wire contract, in one file, before any implementation.
+ *
+ * Two rules run through all of it:
+ *
+ * - **Literal unions, not `string`.** `tier: MemoryTier` means an editor offers
+ *   exactly four values and a typo is a compile error. `tier: string` means a
+ *   runtime surprise instead.
+ * - **Request and response types are separate.** A request has optional fields
+ *   with defaults; a response has ids, timestamps and computed values. Deriving
+ *   one from the other produces optional ids and a type that lies about both.
+ *
+ * Where a request value is constrained by a response value, it is written as a
+ * reference (`RememberRequest["items"][number]["tier"]`) so the two cannot drift
+ * apart when a new tier is added.
+ */
+export declare type MemoryTier = "L0" | "L1" | "L2" | "L3";
+
+export declare const normalise: (value: string) => string;
+
+/** Overlap of two token sets, normalised by the smaller side. */
+export declare const overlapScore: (query: Set<string>, candidate: Set<string>) => number;
+
+/** Above this, a memory is worth promoting into the pre-staged index. */
+export declare const PROMOTE_THRESHOLD = 0.12;
+
+export declare interface ProprioceptiveSelfModel {
+    /** Map of domain tag (e.g. "auth", "db-migration", "css") to capability stats */
+    domains: Record<string, DomainCapability_2>;
+    /** Overall calibration score (1.0 = well-calibrated, <0.7 = overconfident) */
+    calibrationFactor: number;
+    /** Active domains detected in current work */
+    activeDomains: string[];
+}
+
+export declare interface RecallHit {
+    memory: Memory;
+    score: number;
+}
+
+/**
+ * Recall, phrased for injection into a prompt.
+ *
+ * Returns text rather than results because the caller's next step is almost
+ * always "put this in the prompt", and doing the formatting here means every
+ * integration handles the empty case the same way: by saying so, rather than
+ * letting a model fill the gap with a guess.
+ */
+export declare function recallOrExplain(memory: Cogmem, query: string, options?: RecallOrExplainOptions): Promise<string>;
+
+export declare interface RecallOrExplainOptions {
+    limit?: number;
+    /** Overrides the default "you were not told this" wording. */
+    emptyMessage?: string;
+}
+
+export declare interface RecallRequest {
+    query: string;
+    limit?: number;
+}
+
+/**
+ * Deterministic ranked lookup.
+ *
+ * No model is involved, so recall quality does not change when a provider is
+ * down or a different model is configured. `empty: true` is the signal to admit
+ * ignorance rather than guess.
+ */
+export declare class RecallResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    search(request: RecallRequest): Promise<RecallResponse>;
+}
+
+export declare interface RecallResponse {
+    results: RecallHit[];
+    /** True when nothing matched, so the model can admit ignorance. */
+    empty: boolean;
+}
+
+export declare interface RejectedStatement {
+    content: string;
+    reason: string;
+}
+
+/** Content words worth matching a memory against. */
+export declare const relevanceTokens: (value: string) => Set<string>;
+
+export declare interface RememberRequest {
+    items: Array<{
+        content: string;
+        domains?: string[];
+        tier?: MemoryTier;
+    }>;
+    /** Groups memories from one conversation. */
+    sessionId?: string;
+}
+
+export declare interface ResolveTensionRequest {
+    resolvedBy: string;
+    /** The reusable pattern the resolution revealed. */
+    pattern?: string;
+}
+
+export declare const runFastGate: (userMessage: string) => FastGateResult;
+
+/**
+ * One turn of an agent loop, with memory handled correctly.
+ *
+ * The order is the point:
+ *
+ * 1. build context *before* the model runs, keyed on the message being answered;
+ * 2. run the model;
+ * 3. learn from the finished exchange;
+ * 4. record how the domain went, so the self-model moves.
+ *
+ * Steps 3 and 4 never fail the turn. Memory is an enhancement; an outage in it
+ * must not take down the agent that was working fine without it, and the errors
+ * are surfaced through `onLearn` and the returned skip reason rather than
+ * swallowed.
+ */
+export declare function runTurn(memory: Cogmem, input: {
+    userMessage: string;
+    run: (context: string) => Promise<string>;
+}, options?: TurnOptions): Promise<RunTurnResult>;
+
+export declare interface RunTurnResult {
+    context: ContextReport;
+    learning: LearnResult | null;
+    /**
+     * Why learning did not happen, if it did not.
+     *
+     * Present because a silent skip looks identical to a working one until the
+     * thing you taught it never comes back.
+     */
+    learningSkipped?: string;
+}
+
+export declare type Scope = "memories:read" | "memories:write" | "stats:read" | "keys:manage";
+
+/**
+ * Store a set of statements once, tolerating the ones already held.
+ *
+ * For a migration or a first run, where you have a list of facts and no way to
+ * know which the service already knows. Restatements come back under
+ * `mergedInto` rather than as errors, so re-running it is safe.
+ */
+export declare function seedMemories(memory: Cogmem, options: SeedOptions): Promise<{
+    stored: Memory[];
+    merged: Memory[];
+    rejected: LearnResult["rejected"];
+}>;
+
+export declare interface SeedOptions {
+    /** Statements worth keeping regardless of how they are phrased. */
+    facts: string[];
+    sessionId?: string;
+}
+
+export declare interface SelfModel {
+    calibrationFactor: number;
+    activeDomains: string[];
+    domains: Record<string, DomainCapability>;
+    /** Below the 75% line, a guardrail is injected into every context build. */
+    weakDomains: string[];
+}
+
+/**
+ * The proprioceptive self-model: how reliably this agent has done in each domain.
+ *
+ * Nothing here is inferred. Without outcomes recorded through `record`, the
+ * model stays at its priors and no guardrail ever fires — which is the most
+ * common reason a self-model looks like it is not working.
+ */
+export declare class SelfModelResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    get(): Promise<SelfModel>;
+    record(request: DomainOutcomeRequest): Promise<SelfModel>;
+}
+
+/** Similarity of two statements by the tokens that carry identity. */
+export declare const similarity: (a: string, b: string) => number;
+
+export declare interface Stats {
+    memories: {
+        total: number;
+        byTier: Record<MemoryTier, number>;
+        sessions: number;
+        firstStoredAt: number;
+        lastAccessedAt: number;
+    };
+    tensions: {
+        active: number;
+    };
+    weakDomains: Array<{
+        domain: string;
+        reliabilityScore: number;
+        sampleCount: number;
+    }>;
+    recent: Memory[];
+    activeTensions: Tension[];
+}
+
+/** What the memory currently holds, and what the service can do. */
+export declare class StatsResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    /** Needs only `stats:read`, so monitoring can watch without reading memories. */
+    get(): Promise<Stats>;
+}
+
+export declare interface Tension {
+    id: string;
+    status: TensionStatus;
+    claimA: Claim;
+    claimB: Claim;
+    impact: Impact;
+    actionableQuestion: string;
+    resolvedBy?: string;
+    pattern?: string;
+}
+
+export declare type TensionImpact = "low" | "medium" | "critical";
+
+/**
+ * Knowledge tensions: two claims that cannot both be true.
+ *
+ * A tension is worth more than either claim alone, so it is pinned into every
+ * context build with an actionable question until it is resolved.
+ */
+export declare class TensionsResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    list(status?: TensionStatus): Promise<Tension[]>;
+    create(request: AddTensionRequest): Promise<Tension>;
+    resolve(id: string, request: ResolveTensionRequest): Promise<Tension>;
+}
+
+export declare type TensionStatus = "active" | "latent" | "resolved";
+
+declare type TensionStatus_2 = "active" | "latent" | "resolved";
+
+export declare interface TrajectoryPrediction {
+    predictedDomains: string[];
+    predictedFiles: string[];
+    prefetchMemoryIds: string[];
+    confidence: number;
+}
+
+/**
+ * Workflows.
+ *
+ * Resource methods are one call each. These compose them into the sequences
+ * people actually get wrong when they write the loop themselves — and the
+ * mistakes are mundane: forgetting to learn from a turn, learning from a question,
+ * letting a memory failure take down the turn it was meant to help, or never
+ * telling the service how a task went so the guardrails never fire.
+ *
+ * Each helper takes the client explicitly rather than closing over one, so it
+ * works with a second client without a module-level singleton.
+ */
+export declare interface TurnOptions {
+    /** Groups everything learned in one conversation. */
+    sessionId?: string;
+    /**
+     * What the turn turned out to be about, e.g. `"database"`.
+     *
+     * Recorded against the self-model, which is what eventually produces a
+     * guardrail for a domain the agent keeps failing in. Cheap to send and the
+     * difference between a self-model that learns and one that sits at its priors.
+     */
+    domain?: string;
+    /** What went wrong, when the turn was a failure. */
+    failurePattern?: string;
+    /** What worked, when the turn was a success. */
+    strategy?: string;
+    /** Set false to skip learning — a retrieval-only turn, say. */
+    learn?: boolean;
+    onLearn?: (result: LearnResult) => void;
+}
+
+export declare interface TurnRequest {
+    userMessage: string;
+    assistantResponse: string;
+    sessionId?: string;
+}
+
+/**
+ * Learning from a completed turn.
+ *
+ * A turn whose user message contains a question is treated as a lookup rather
+ * than a lesson, so this is called after work is done, not before.
+ */
+export declare class TurnsResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    learn(request: TurnRequest): Promise<LearnResult>;
+}
+
+export { }