cognia-sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# cognia-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Cognia for your model calls. One line, and every request your agent makes gets the Memories and Skills its identity
+may use, with provenance the model can cite. It fails open: if Cognia is slow or down, the model call proceeds without
+context.
+
+```ts
+import { Cognia, withCognia, CogniaSession } from "cognia-sdk";
+
+const cognia = new Cognia({ apiKey: process.env.COGNIA_API_KEY!, scope: "organization" });
+
+// Vercel AI SDK, OpenAI or Anthropic clients: detected by shape, no provider import here
+const model = withCognia(openai("gpt-5.6"), { cognia, budget: { memories: 3, skills: 1 },
+  onInjected: (items) => ui.showSources(items) });
+
+// direct
+const ctx = await cognia.context({ task: userMessage });            // INJECT | ABSTAIN | UNAVAILABLE
+await cognia.outcome(ctx.contextId!, { itemId, used: true, outcome: "success" });
+
+// session learning: proposes, never saves
+const session = new CogniaSession(cognia, conversationId);
+const proposals = await session.end();
+```
+
+## What is and is not a receipt
+
+| receipt | meaning | evidence? |
+|---|---|---|
+| SEARCHED, RETRIEVED | Cognia looked, and returned items that cleared its gates | no |
+| INJECTED | the SDK placed an item in front of the model | no |
+| USED, success / failure | you said so with `outcome()`, or a human confirmed it | yes |
+
+Injecting something never counts as using it. Only `outcome()` creates evidence, and only for items this context
+returned. Dogfood, canary and operator traffic is classified server-side and never counts.
+
+## Scope
+
+`mine` = the identity's own memories and Skills. `organization` (default) = plus everything its organizations share
+with it. `network` = plus the public network. Nothing private to another owner is ever returned; another owner is only
+ever named by their public agent name.
+
+## Abstention
+
+When nothing clears the relevance gates the answer is `ABSTAIN` with a reason and no items. The SDK adds nothing to the
+request in that case. Budgets default to 3 memories and 1 Skill; the gate is never loosened. The lookup times out after 1500 ms by default (`timeoutMs`), and a timeout is fail-open.
+
+Docs: https://cognia.fun/developers · Source: github.com/cognia-dev/memory-backend (`packages/sdk`)

package/dist/cjs/client.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cognia = exports.CogniaError = void 0;
+class CogniaError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "CogniaError";
+    }
+}
+exports.CogniaError = CogniaError;
+class Cognia {
+    baseUrl;
+    scope;
+    budget;
+    timeoutMs;
+    key;
+    f;
+    onError;
+    constructor(o) {
+        if (!o.apiKey)
+            throw new Error("Cognia: apiKey is required");
+        this.key = o.apiKey;
+        this.baseUrl = (o.baseUrl ?? "https://api.cognia.fun").replace(/\/$/, "");
+        this.scope = o.scope ?? "organization";
+        this.budget = o.budget;
+        this.timeoutMs = o.timeoutMs ?? 1500;
+        this.f = o.fetch ?? fetch;
+        this.onError = o.onError;
+    }
+    async call(method, path, body, timeoutMs) {
+        const ac = new AbortController();
+        const t = timeoutMs ? setTimeout(() => ac.abort(), timeoutMs) : null;
+        try {
+            const r = await this.f(this.baseUrl + path, { method, headers: { authorization: `Bearer ${this.key}`, "content-type": "application/json", "user-agent": "cognia-sdk/0.1.0" }, body: body === undefined ? undefined : JSON.stringify(body), signal: ac.signal });
+            let j = null;
+            try {
+                j = await r.json();
+            }
+            catch { /* no body */ }
+            if (!r.ok)
+                throw new CogniaError(`Cognia ${method} ${path} → ${r.status}`, r.status, j);
+            return j;
+        }
+        finally {
+            if (t)
+                clearTimeout(t);
+        }
+    }
+    /**
+     * The Memories and Skills this identity may use for `task`, or an explicit ABSTAIN. Never throws: on a timeout or a
+     * server error it resolves to `{ decision: "UNAVAILABLE" }` so the model call proceeds without context (fail-open).
+     * A bad credential is also reported this way, with the reason, so a misconfigured app degrades instead of breaking.
+     */
+    async context(req) {
+        const body = typeof req === "string" ? { task: req } : req;
+        const payload = { task: body.task, scope: body.scope ?? this.scope, ...(body.budget ?? this.budget ? { budget: { ...this.budget, ...body.budget } } : {}), ...(body.session ? { session: body.session } : {}) };
+        try {
+            return await this.call("POST", "/v1/context", payload, this.timeoutMs);
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            this.onError?.(err);
+            return { contextId: null, decision: "UNAVAILABLE", items: [], reason: err.name === "AbortError" ? "timeout" : err.message };
+        }
+    }
+    /** Tell Cognia which returned items were actually placed in front of the model. A usage receipt, never evidence. */
+    async injected(contextId, itemIds) {
+        if (!contextId || !itemIds.length)
+            return;
+        try {
+            await this.call("POST", `/v1/context/${encodeURIComponent(contextId)}/injected`, { itemIds }, 2000);
+        }
+        catch (e) {
+            this.onError?.(e instanceof Error ? e : new Error(String(e)));
+        }
+    }
+    /** Report what happened with one item: used or not, success / failure (/ neutral for a Skill). This is the only path to USED. */
+    outcome(contextId, input) {
+        return this.call("POST", `/v1/context/${encodeURIComponent(contextId)}/outcome`, input);
+    }
+    /** Session learning: propose memories from a session's turns. Nothing is saved; the host shows the proposals. */
+    extract(markdown, filename = "session.md") {
+        return this.call("POST", "/v1/memories/extract", { markdown, filename }, 60_000);
+    }
+}
+exports.Cognia = Cognia;

package/dist/cjs/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.provenanceLine = exports.renderContextBlock = exports.textOf = exports.prependSystem = exports.contextFor = exports.withCognia = exports.CogniaSession = exports.CogniaError = exports.Cognia = void 0;
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "Cognia", { enumerable: true, get: function () { return client_js_1.Cognia; } });
+Object.defineProperty(exports, "CogniaError", { enumerable: true, get: function () { return client_js_1.CogniaError; } });
+var session_js_1 = require("./session.js");
+Object.defineProperty(exports, "CogniaSession", { enumerable: true, get: function () { return session_js_1.CogniaSession; } });
+var middleware_js_1 = require("./middleware.js");
+Object.defineProperty(exports, "withCognia", { enumerable: true, get: function () { return middleware_js_1.withCognia; } });
+Object.defineProperty(exports, "contextFor", { enumerable: true, get: function () { return middleware_js_1.contextFor; } });
+Object.defineProperty(exports, "prependSystem", { enumerable: true, get: function () { return middleware_js_1.prependSystem; } });
+Object.defineProperty(exports, "textOf", { enumerable: true, get: function () { return middleware_js_1.textOf; } });
+var render_js_1 = require("./render.js");
+Object.defineProperty(exports, "renderContextBlock", { enumerable: true, get: function () { return render_js_1.renderContextBlock; } });
+Object.defineProperty(exports, "provenanceLine", { enumerable: true, get: function () { return render_js_1.provenanceLine; } });

package/dist/cjs/middleware.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.textOf = textOf;
+exports.contextFor = contextFor;
+exports.prependSystem = prependSystem;
+exports.withCognia = withCognia;
+const render_js_1 = require("./render.js");
+/** text of a message's content whatever the provider's shape (string, or parts with `text`) */
+function textOf(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content))
+        return content.map((p) => (p && typeof p === "object" && typeof p.text === "string" ? p.text : "")).filter(Boolean).join("\n");
+    return "";
+}
+const lastUser = (messages) => { for (let i = messages.length - 1; i >= 0; i--)
+    if (messages[i].role === "user")
+        return textOf(messages[i].content) || null; return null; };
+/**
+ * One lookup for a request: the context block to prepend (or ""), plus the receipt side effects. Shared by every adapter.
+ * Fails open: an UNAVAILABLE or ABSTAIN result yields "" and the model call proceeds untouched.
+ */
+async function contextFor(o, messages) {
+    const task = (o.taskFrom ?? lastUser)(messages);
+    if (!task)
+        return { block: "", ctx: null };
+    const res = await o.cognia.context({ task, scope: o.scope, budget: o.budget, ...(o.session ? { session: o.session.next() } : {}) });
+    if (res.decision === "UNAVAILABLE") {
+        o.onEmpty?.(res.reason);
+        return { block: "", ctx: null };
+    }
+    if (res.decision !== "INJECT") {
+        o.onEmpty?.(res.abstain?.reason ?? "abstain");
+        return { block: "", ctx: null };
+    }
+    const block = (0, render_js_1.renderContextBlock)(res);
+    void o.cognia.injected(res.contextId, res.items.map((i) => i.id));
+    o.onInjected?.(res.items, res);
+    if (o.session)
+        o.session.add({ role: "user", content: task });
+    return { block, ctx: res };
+}
+const hasFn = (x, k) => !!x && typeof x[k] === "function";
+const get = (x, path) => path.reduce((a, k) => (a && typeof a === "object" ? a[k] : undefined), x);
+/** Prepend a system message (OpenAI / Anthropic message arrays): one system entry, Cognia first, then the host's own. */
+function prependSystem(messages, block) {
+    if (!block)
+        return messages;
+    return [{ role: "system", content: block }, ...messages];
+}
+/**
+ * Wrap a model client so every call gets Cognia context first and the session learns from the replies.
+ * Supported shapes, detected structurally (no provider import):
+ *   Vercel AI SDK LanguageModel (doGenerate/doStream)   → a model whose `prompt` gets a leading system part
+ *   OpenAI client (chat.completions.create)              → a client whose create() prepends a system message
+ *   Anthropic client (messages.create)                   → a client whose create() prefixes `system`
+ * Anything else is returned unchanged with a console warning, so a wrong import never breaks a call.
+ */
+function withCognia(target, o) {
+    if (hasFn(target, "doGenerate") || hasFn(target, "doStream"))
+        return wrapVercel(target, o);
+    if (hasFn(get(target, ["chat", "completions"]), "create"))
+        return wrapOpenAI(target, o);
+    if (hasFn(get(target, ["messages"]), "create"))
+        return wrapAnthropic(target, o);
+    console.warn("withCognia: unrecognised client shape; returning it unwrapped");
+    return target;
+}
+function wrapVercel(model, o) {
+    const transform = async (params) => {
+        const { block } = await contextFor(o, params.prompt);
+        if (!block)
+            return params;
+        return { ...params, prompt: [{ role: "system", content: block }, ...params.prompt] };
+    };
+    const learn = (r) => { if (o.session) {
+        const text = typeof r?.text === "string" ? r.text : "";
+        if (text)
+            o.session.add({ role: "assistant", content: text });
+    } return r; };
+    return new Proxy(model, {
+        get(t, k, recv) {
+            if (k === "doGenerate")
+                return async (p) => learn(await t.doGenerate(await transform(p)));
+            if (k === "doStream")
+                return async (p) => t.doStream(await transform(p));
+            return Reflect.get(t, k, recv);
+        },
+    });
+}
+function wrapOpenAI(client, o) {
+    const create = client.chat.completions.create.bind(client.chat.completions);
+    const wrapped = async (p, ...rest) => {
+        const { block } = await contextFor(o, p.messages);
+        const r = await create(block ? { ...p, messages: prependSystem(p.messages, block) } : p, ...rest);
+        if (o.session) {
+            const text = textOf(get(r, ["choices", "0", "message", "content"]));
+            if (text)
+                o.session.add({ role: "assistant", content: text });
+        }
+        return r;
+    };
+    return new Proxy(client, { get(t, k, recv) { if (k === "chat")
+            return { ...t.chat, completions: { ...t.chat.completions, create: wrapped } }; return Reflect.get(t, k, recv); } });
+}
+function wrapAnthropic(client, o) {
+    const create = client.messages.create.bind(client.messages);
+    const wrapped = async (p, ...rest) => {
+        const { block } = await contextFor(o, p.messages);
+        let next = p;
+        if (block) {
+            const sys = typeof p.system === "string" ? `${block}\n\n${p.system}` : Array.isArray(p.system) ? [{ type: "text", text: block }, ...p.system] : block;
+            next = { ...p, system: sys };
+        }
+        const r = await create(next, ...rest);
+        if (o.session) {
+            const text = textOf(get(r, ["content"]));
+            if (text)
+                o.session.add({ role: "assistant", content: text });
+        }
+        return r;
+    };
+    return new Proxy(client, { get(t, k, recv) { if (k === "messages")
+            return { ...t.messages, create: wrapped }; return Reflect.get(t, k, recv); } });
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/render.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.provenanceLine = provenanceLine;
+exports.renderContextBlock = renderContextBlock;
+/** One provenance line the model can cite and a reader can look up: reference · owner · organization · evidence. */
+function provenanceLine(it) {
+    const who = it.owner === "mine" ? "yours" : it.owner === "organization" ? `shared by ${it.provenance.ownerName ?? "a colleague"}` : `public, by ${it.provenance.ownerName ?? "another owner"}`;
+    const ev = it.provenance.verifiedUses > 0 ? `${it.provenance.verifiedUses} verified ${it.provenance.verifiedUses === 1 ? "use" : "uses"}` : "no verified use yet";
+    const mat = it.provenance.maturity ? ` · ${String(it.provenance.maturity).toLowerCase()}` : "";
+    return `[${it.displayId} · ${who}${mat} · ${ev}]`;
+}
+/** The context block placed before the model's instructions. Plain text, deterministic, nothing invented. */
+function renderContextBlock(ctx) {
+    if (ctx.decision !== "INJECT" || !ctx.items.length)
+        return "";
+    const parts = [
+        "Cognia context: prior knowledge this identity may use. Each item names its source. Rely on it only when it fits the task; say which item you used by its reference; when none fits, say so.",
+    ];
+    ctx.items.forEach((it, i) => {
+        const n = i + 1;
+        if (it.kind === "memory") {
+            parts.push(`\n[${n}] MEMORY ${provenanceLine(it)}\nTitle: ${it.title}\n${it.body.text}`);
+        }
+        else {
+            const steps = it.body.procedure.map((s, j) => `  ${j + 1}. ${s}`).join("\n");
+            const when = it.body.trigger.length ? `When: ${it.body.trigger.join("; ")}\n` : "";
+            const not = it.body.doNotApplyWhen.length ? `Do not apply when: ${it.body.doNotApplyWhen.join("; ")}\n` : "";
+            const verify = it.body.verification.length ? `Verify: ${it.body.verification.join("; ")}\n` : "";
+            parts.push(`\n[${n}] SKILL ${provenanceLine(it)}\nTitle: ${it.title}\n${it.body.summary}\n${when}${not}Procedure:\n${steps}\n${verify}`.trimEnd());
+        }
+    });
+    return parts.join("\n");
+}

package/dist/cjs/session.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CogniaSession = void 0;
+/**
+ * A conversation the middleware observes. `end()` proposes the few things worth remembering through Cognia's
+ * extraction endpoint (private-first, reviewed before anything is saved). It never saves by itself.
+ */
+class CogniaSession {
+    cognia;
+    id;
+    turns = [];
+    turn = 0;
+    constructor(cognia, id) {
+        this.cognia = cognia;
+        this.id = id;
+    }
+    next() { return { id: this.id, turn: this.turn++ }; }
+    add(t) { if (t.content && t.content.trim())
+        this.turns.push({ role: t.role, content: t.content.slice(0, 20_000) }); }
+    /** The session as Markdown, the shape the extraction endpoint reads. */
+    toMarkdown() {
+        return `# Session ${this.id}\n\n` + this.turns.filter((t) => t.role === "user" || t.role === "assistant").map((t) => `## ${t.role === "user" ? "User" : "Assistant"}\n\n${t.content}\n`).join("\n");
+    }
+    /** Propose memories from this session. Returns the server's proposals; saving is the host's decision. */
+    async end() {
+        if (!this.turns.some((t) => t.role === "assistant"))
+            return null;
+        const md = this.toMarkdown();
+        if (md.length > 180_000)
+            return this.cognia.extract(md.slice(-180_000), `session-${this.id}.md`);
+        return this.cognia.extract(md, `session-${this.id}.md`);
+    }
+}
+exports.CogniaSession = CogniaSession;

package/dist/cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/esm/client.d.ts

@@ -0,0 +1,50 @@
+import type { ContextRequest, ContextResult, OutcomeInput, OutcomeResponse, ExtractResponse, Scope } from "./types.js";
+export interface CogniaOptions {
+    /** the agent's credential (cognia_sk_…); never logged, never put in a URL */
+    apiKey: string;
+    baseUrl?: string;
+    /** default scope for context(); the identity's grants decide what that means */
+    scope?: Scope;
+    /** default budget */
+    budget?: {
+        memories?: number;
+        skills?: number;
+    };
+    /** how long a context lookup may take before the model call goes on without it (fail-open). Default 1500 ms: a
+        network-scope lookup that routes Skills measured about 1.3 s server-side on 2026-10-06; mine-scope about 50 ms. */
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+    /** receives every non-fatal problem (timeouts, 5xx); nothing is thrown out of context() */
+    onError?: (e: Error) => void;
+}
+export declare class CogniaError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+export declare class Cognia {
+    readonly baseUrl: string;
+    readonly scope: Scope;
+    readonly budget: {
+        memories?: number;
+        skills?: number;
+    } | undefined;
+    readonly timeoutMs: number;
+    private readonly key;
+    private readonly f;
+    private readonly onError;
+    constructor(o: CogniaOptions);
+    private call;
+    /**
+     * The Memories and Skills this identity may use for `task`, or an explicit ABSTAIN. Never throws: on a timeout or a
+     * server error it resolves to `{ decision: "UNAVAILABLE" }` so the model call proceeds without context (fail-open).
+     * A bad credential is also reported this way, with the reason, so a misconfigured app degrades instead of breaking.
+     */
+    context(req: ContextRequest | string): Promise<ContextResult>;
+    /** Tell Cognia which returned items were actually placed in front of the model. A usage receipt, never evidence. */
+    injected(contextId: string, itemIds: string[]): Promise<void>;
+    /** Report what happened with one item: used or not, success / failure (/ neutral for a Skill). This is the only path to USED. */
+    outcome(contextId: string, input: OutcomeInput): Promise<OutcomeResponse>;
+    /** Session learning: propose memories from a session's turns. Nothing is saved; the host shows the proposals. */
+    extract(markdown: string, filename?: string): Promise<ExtractResponse>;
+}

package/dist/esm/client.js

@@ -0,0 +1,85 @@
+export class CogniaError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "CogniaError";
+    }
+}
+export class Cognia {
+    baseUrl;
+    scope;
+    budget;
+    timeoutMs;
+    key;
+    f;
+    onError;
+    constructor(o) {
+        if (!o.apiKey)
+            throw new Error("Cognia: apiKey is required");
+        this.key = o.apiKey;
+        this.baseUrl = (o.baseUrl ?? "https://api.cognia.fun").replace(/\/$/, "");
+        this.scope = o.scope ?? "organization";
+        this.budget = o.budget;
+        this.timeoutMs = o.timeoutMs ?? 1500;
+        this.f = o.fetch ?? fetch;
+        this.onError = o.onError;
+    }
+    async call(method, path, body, timeoutMs) {
+        const ac = new AbortController();
+        const t = timeoutMs ? setTimeout(() => ac.abort(), timeoutMs) : null;
+        try {
+            const r = await this.f(this.baseUrl + path, { method, headers: { authorization: `Bearer ${this.key}`, "content-type": "application/json", "user-agent": "cognia-sdk/0.1.0" }, body: body === undefined ? undefined : JSON.stringify(body), signal: ac.signal });
+            let j = null;
+            try {
+                j = await r.json();
+            }
+            catch { /* no body */ }
+            if (!r.ok)
+                throw new CogniaError(`Cognia ${method} ${path} → ${r.status}`, r.status, j);
+            return j;
+        }
+        finally {
+            if (t)
+                clearTimeout(t);
+        }
+    }
+    /**
+     * The Memories and Skills this identity may use for `task`, or an explicit ABSTAIN. Never throws: on a timeout or a
+     * server error it resolves to `{ decision: "UNAVAILABLE" }` so the model call proceeds without context (fail-open).
+     * A bad credential is also reported this way, with the reason, so a misconfigured app degrades instead of breaking.
+     */
+    async context(req) {
+        const body = typeof req === "string" ? { task: req } : req;
+        const payload = { task: body.task, scope: body.scope ?? this.scope, ...(body.budget ?? this.budget ? { budget: { ...this.budget, ...body.budget } } : {}), ...(body.session ? { session: body.session } : {}) };
+        try {
+            return await this.call("POST", "/v1/context", payload, this.timeoutMs);
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            this.onError?.(err);
+            return { contextId: null, decision: "UNAVAILABLE", items: [], reason: err.name === "AbortError" ? "timeout" : err.message };
+        }
+    }
+    /** Tell Cognia which returned items were actually placed in front of the model. A usage receipt, never evidence. */
+    async injected(contextId, itemIds) {
+        if (!contextId || !itemIds.length)
+            return;
+        try {
+            await this.call("POST", `/v1/context/${encodeURIComponent(contextId)}/injected`, { itemIds }, 2000);
+        }
+        catch (e) {
+            this.onError?.(e instanceof Error ? e : new Error(String(e)));
+        }
+    }
+    /** Report what happened with one item: used or not, success / failure (/ neutral for a Skill). This is the only path to USED. */
+    outcome(contextId, input) {
+        return this.call("POST", `/v1/context/${encodeURIComponent(contextId)}/outcome`, input);
+    }
+    /** Session learning: propose memories from a session's turns. Nothing is saved; the host shows the proposals. */
+    extract(markdown, filename = "session.md") {
+        return this.call("POST", "/v1/memories/extract", { markdown, filename }, 60_000);
+    }
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,5 @@
+export { Cognia, CogniaError, type CogniaOptions } from "./client.js";
+export { CogniaSession, type SessionTurn } from "./session.js";
+export { withCognia, contextFor, prependSystem, textOf, type WithCogniaOptions } from "./middleware.js";
+export { renderContextBlock, provenanceLine } from "./render.js";
+export type * from "./types.js";

package/dist/esm/index.js

@@ -0,0 +1,4 @@
+export { Cognia, CogniaError } from "./client.js";
+export { CogniaSession } from "./session.js";
+export { withCognia, contextFor, prependSystem, textOf } from "./middleware.js";
+export { renderContextBlock, provenanceLine } from "./render.js";

package/dist/esm/middleware.d.ts

@@ -0,0 +1,48 @@
+import type { Cognia } from "./client.js";
+import type { CogniaSession } from "./session.js";
+import type { ContextItem, ContextResponse, Scope } from "./types.js";
+export interface WithCogniaOptions {
+    cognia: Cognia;
+    scope?: Scope;
+    budget?: {
+        memories?: number;
+        skills?: number;
+    };
+    session?: CogniaSession;
+    /** called with the items that were placed in front of the model (and the contextId), e.g. to show "Sources" */
+    onInjected?: (items: ContextItem[], ctx: ContextResponse) => void;
+    /** called when Cognia abstained or was unavailable */
+    onEmpty?: (reason: string) => void;
+    /** which message to read the task from; default: the last user message */
+    taskFrom?: (messages: Array<{
+        role: string;
+        content: unknown;
+    }>) => string | null;
+}
+/** text of a message's content whatever the provider's shape (string, or parts with `text`) */
+export declare function textOf(content: unknown): string;
+/**
+ * One lookup for a request: the context block to prepend (or ""), plus the receipt side effects. Shared by every adapter.
+ * Fails open: an UNAVAILABLE or ABSTAIN result yields "" and the model call proceeds untouched.
+ */
+export declare function contextFor(o: WithCogniaOptions, messages: Array<{
+    role: string;
+    content: unknown;
+}>): Promise<{
+    block: string;
+    ctx: ContextResponse | null;
+}>;
+/** Prepend a system message (OpenAI / Anthropic message arrays): one system entry, Cognia first, then the host's own. */
+export declare function prependSystem<M extends {
+    role: string;
+    content: unknown;
+}>(messages: M[], block: string): M[];
+/**
+ * Wrap a model client so every call gets Cognia context first and the session learns from the replies.
+ * Supported shapes, detected structurally (no provider import):
+ *   Vercel AI SDK LanguageModel (doGenerate/doStream)   → a model whose `prompt` gets a leading system part
+ *   OpenAI client (chat.completions.create)              → a client whose create() prepends a system message
+ *   Anthropic client (messages.create)                   → a client whose create() prefixes `system`
+ * Anything else is returned unchanged with a console warning, so a wrong import never breaks a call.
+ */
+export declare function withCognia<T>(target: T, o: WithCogniaOptions): T;

package/dist/esm/middleware.js

@@ -0,0 +1,119 @@
+import { renderContextBlock } from "./render.js";
+/** text of a message's content whatever the provider's shape (string, or parts with `text`) */
+export function textOf(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content))
+        return content.map((p) => (p && typeof p === "object" && typeof p.text === "string" ? p.text : "")).filter(Boolean).join("\n");
+    return "";
+}
+const lastUser = (messages) => { for (let i = messages.length - 1; i >= 0; i--)
+    if (messages[i].role === "user")
+        return textOf(messages[i].content) || null; return null; };
+/**
+ * One lookup for a request: the context block to prepend (or ""), plus the receipt side effects. Shared by every adapter.
+ * Fails open: an UNAVAILABLE or ABSTAIN result yields "" and the model call proceeds untouched.
+ */
+export async function contextFor(o, messages) {
+    const task = (o.taskFrom ?? lastUser)(messages);
+    if (!task)
+        return { block: "", ctx: null };
+    const res = await o.cognia.context({ task, scope: o.scope, budget: o.budget, ...(o.session ? { session: o.session.next() } : {}) });
+    if (res.decision === "UNAVAILABLE") {
+        o.onEmpty?.(res.reason);
+        return { block: "", ctx: null };
+    }
+    if (res.decision !== "INJECT") {
+        o.onEmpty?.(res.abstain?.reason ?? "abstain");
+        return { block: "", ctx: null };
+    }
+    const block = renderContextBlock(res);
+    void o.cognia.injected(res.contextId, res.items.map((i) => i.id));
+    o.onInjected?.(res.items, res);
+    if (o.session)
+        o.session.add({ role: "user", content: task });
+    return { block, ctx: res };
+}
+const hasFn = (x, k) => !!x && typeof x[k] === "function";
+const get = (x, path) => path.reduce((a, k) => (a && typeof a === "object" ? a[k] : undefined), x);
+/** Prepend a system message (OpenAI / Anthropic message arrays): one system entry, Cognia first, then the host's own. */
+export function prependSystem(messages, block) {
+    if (!block)
+        return messages;
+    return [{ role: "system", content: block }, ...messages];
+}
+/**
+ * Wrap a model client so every call gets Cognia context first and the session learns from the replies.
+ * Supported shapes, detected structurally (no provider import):
+ *   Vercel AI SDK LanguageModel (doGenerate/doStream)   → a model whose `prompt` gets a leading system part
+ *   OpenAI client (chat.completions.create)              → a client whose create() prepends a system message
+ *   Anthropic client (messages.create)                   → a client whose create() prefixes `system`
+ * Anything else is returned unchanged with a console warning, so a wrong import never breaks a call.
+ */
+export function withCognia(target, o) {
+    if (hasFn(target, "doGenerate") || hasFn(target, "doStream"))
+        return wrapVercel(target, o);
+    if (hasFn(get(target, ["chat", "completions"]), "create"))
+        return wrapOpenAI(target, o);
+    if (hasFn(get(target, ["messages"]), "create"))
+        return wrapAnthropic(target, o);
+    console.warn("withCognia: unrecognised client shape; returning it unwrapped");
+    return target;
+}
+function wrapVercel(model, o) {
+    const transform = async (params) => {
+        const { block } = await contextFor(o, params.prompt);
+        if (!block)
+            return params;
+        return { ...params, prompt: [{ role: "system", content: block }, ...params.prompt] };
+    };
+    const learn = (r) => { if (o.session) {
+        const text = typeof r?.text === "string" ? r.text : "";
+        if (text)
+            o.session.add({ role: "assistant", content: text });
+    } return r; };
+    return new Proxy(model, {
+        get(t, k, recv) {
+            if (k === "doGenerate")
+                return async (p) => learn(await t.doGenerate(await transform(p)));
+            if (k === "doStream")
+                return async (p) => t.doStream(await transform(p));
+            return Reflect.get(t, k, recv);
+        },
+    });
+}
+function wrapOpenAI(client, o) {
+    const create = client.chat.completions.create.bind(client.chat.completions);
+    const wrapped = async (p, ...rest) => {
+        const { block } = await contextFor(o, p.messages);
+        const r = await create(block ? { ...p, messages: prependSystem(p.messages, block) } : p, ...rest);
+        if (o.session) {
+            const text = textOf(get(r, ["choices", "0", "message", "content"]));
+            if (text)
+                o.session.add({ role: "assistant", content: text });
+        }
+        return r;
+    };
+    return new Proxy(client, { get(t, k, recv) { if (k === "chat")
+            return { ...t.chat, completions: { ...t.chat.completions, create: wrapped } }; return Reflect.get(t, k, recv); } });
+}
+function wrapAnthropic(client, o) {
+    const create = client.messages.create.bind(client.messages);
+    const wrapped = async (p, ...rest) => {
+        const { block } = await contextFor(o, p.messages);
+        let next = p;
+        if (block) {
+            const sys = typeof p.system === "string" ? `${block}\n\n${p.system}` : Array.isArray(p.system) ? [{ type: "text", text: block }, ...p.system] : block;
+            next = { ...p, system: sys };
+        }
+        const r = await create(next, ...rest);
+        if (o.session) {
+            const text = textOf(get(r, ["content"]));
+            if (text)
+                o.session.add({ role: "assistant", content: text });
+        }
+        return r;
+    };
+    return new Proxy(client, { get(t, k, recv) { if (k === "messages")
+            return { ...t.messages, create: wrapped }; return Reflect.get(t, k, recv); } });
+}

package/dist/esm/render.d.ts

@@ -0,0 +1,5 @@
+import type { ContextItem, ContextResponse } from "./types.js";
+/** One provenance line the model can cite and a reader can look up: reference · owner · organization · evidence. */
+export declare function provenanceLine(it: ContextItem): string;
+/** The context block placed before the model's instructions. Plain text, deterministic, nothing invented. */
+export declare function renderContextBlock(ctx: ContextResponse): string;

package/dist/esm/render.js

@@ -0,0 +1,29 @@
+/** One provenance line the model can cite and a reader can look up: reference · owner · organization · evidence. */
+export function provenanceLine(it) {
+    const who = it.owner === "mine" ? "yours" : it.owner === "organization" ? `shared by ${it.provenance.ownerName ?? "a colleague"}` : `public, by ${it.provenance.ownerName ?? "another owner"}`;
+    const ev = it.provenance.verifiedUses > 0 ? `${it.provenance.verifiedUses} verified ${it.provenance.verifiedUses === 1 ? "use" : "uses"}` : "no verified use yet";
+    const mat = it.provenance.maturity ? ` · ${String(it.provenance.maturity).toLowerCase()}` : "";
+    return `[${it.displayId} · ${who}${mat} · ${ev}]`;
+}
+/** The context block placed before the model's instructions. Plain text, deterministic, nothing invented. */
+export function renderContextBlock(ctx) {
+    if (ctx.decision !== "INJECT" || !ctx.items.length)
+        return "";
+    const parts = [
+        "Cognia context: prior knowledge this identity may use. Each item names its source. Rely on it only when it fits the task; say which item you used by its reference; when none fits, say so.",
+    ];
+    ctx.items.forEach((it, i) => {
+        const n = i + 1;
+        if (it.kind === "memory") {
+            parts.push(`\n[${n}] MEMORY ${provenanceLine(it)}\nTitle: ${it.title}\n${it.body.text}`);
+        }
+        else {
+            const steps = it.body.procedure.map((s, j) => `  ${j + 1}. ${s}`).join("\n");
+            const when = it.body.trigger.length ? `When: ${it.body.trigger.join("; ")}\n` : "";
+            const not = it.body.doNotApplyWhen.length ? `Do not apply when: ${it.body.doNotApplyWhen.join("; ")}\n` : "";
+            const verify = it.body.verification.length ? `Verify: ${it.body.verification.join("; ")}\n` : "";
+            parts.push(`\n[${n}] SKILL ${provenanceLine(it)}\nTitle: ${it.title}\n${it.body.summary}\n${when}${not}Procedure:\n${steps}\n${verify}`.trimEnd());
+        }
+    });
+    return parts.join("\n");
+}

package/dist/esm/session.d.ts

@@ -0,0 +1,26 @@
+import type { Cognia } from "./client.js";
+import type { ExtractResponse } from "./types.js";
+export interface SessionTurn {
+    role: "user" | "assistant" | "system" | "tool";
+    content: string;
+}
+/**
+ * A conversation the middleware observes. `end()` proposes the few things worth remembering through Cognia's
+ * extraction endpoint (private-first, reviewed before anything is saved). It never saves by itself.
+ */
+export declare class CogniaSession {
+    private readonly cognia;
+    readonly id: string;
+    readonly turns: SessionTurn[];
+    private turn;
+    constructor(cognia: Cognia, id: string);
+    next(): {
+        id: string;
+        turn: number;
+    };
+    add(t: SessionTurn): void;
+    /** The session as Markdown, the shape the extraction endpoint reads. */
+    toMarkdown(): string;
+    /** Propose memories from this session. Returns the server's proposals; saving is the host's decision. */
+    end(): Promise<ExtractResponse | null>;
+}

package/dist/esm/session.js

@@ -0,0 +1,30 @@
+/**
+ * A conversation the middleware observes. `end()` proposes the few things worth remembering through Cognia's
+ * extraction endpoint (private-first, reviewed before anything is saved). It never saves by itself.
+ */
+export class CogniaSession {
+    cognia;
+    id;
+    turns = [];
+    turn = 0;
+    constructor(cognia, id) {
+        this.cognia = cognia;
+        this.id = id;
+    }
+    next() { return { id: this.id, turn: this.turn++ }; }
+    add(t) { if (t.content && t.content.trim())
+        this.turns.push({ role: t.role, content: t.content.slice(0, 20_000) }); }
+    /** The session as Markdown, the shape the extraction endpoint reads. */
+    toMarkdown() {
+        return `# Session ${this.id}\n\n` + this.turns.filter((t) => t.role === "user" || t.role === "assistant").map((t) => `## ${t.role === "user" ? "User" : "Assistant"}\n\n${t.content}\n`).join("\n");
+    }
+    /** Propose memories from this session. Returns the server's proposals; saving is the host's decision. */
+    async end() {
+        if (!this.turns.some((t) => t.role === "assistant"))
+            return null;
+        const md = this.toMarkdown();
+        if (md.length > 180_000)
+            return this.cognia.extract(md.slice(-180_000), `session-${this.id}.md`);
+        return this.cognia.extract(md, `session-${this.id}.md`);
+    }
+}

package/dist/esm/types.d.ts

@@ -0,0 +1,117 @@
+/** The wire shapes of POST /v1/context and its two follow-ups (docs/V2_AUTOMATIC_COGNIA.md). */
+export type Scope = "mine" | "organization" | "network";
+export type Owner = "mine" | "organization" | "network";
+export interface ContextRequest {
+    task: string;
+    scope?: Scope;
+    budget?: {
+        memories?: number;
+        skills?: number;
+    };
+    session?: {
+        id: string;
+        turn: number;
+    };
+}
+export interface MemoryItem {
+    kind: "memory";
+    id: string;
+    displayId: string;
+    title: string;
+    owner: Owner;
+    body: {
+        text: string;
+        kind: string | null;
+    };
+    provenance: {
+        ownerName: string | null;
+        organizationName: string | null;
+        maturity: string | null;
+        verifiedUses: number;
+        created: string | null;
+    };
+    score: number | null;
+}
+export interface SkillItem {
+    kind: "skill";
+    id: string;
+    displayId: string;
+    title: string;
+    owner: Owner;
+    body: {
+        summary: string;
+        trigger: string[];
+        procedure: string[];
+        verification: string[];
+        doNotApplyWhen: string[];
+    };
+    provenance: {
+        ownerName: string | null;
+        maturity: string;
+        verifiedUses: number;
+        routeId: string | null;
+    };
+    score: number | null;
+}
+export type ContextItem = MemoryItem | SkillItem;
+export interface ContextResponse {
+    contextId: string;
+    decision: "INJECT" | "ABSTAIN";
+    abstain?: {
+        reason: string;
+    };
+    scope: Scope;
+    items: ContextItem[];
+    receipts: Array<{
+        kind: "SEARCHED" | "RETRIEVED";
+        itemId?: string;
+        at: string;
+    }>;
+    metrics: {
+        ms: {
+            search: number;
+            total: number;
+        };
+        considered: number;
+        returned: number;
+    };
+}
+/** What `context()` returns when Cognia could not answer in time: the model call goes on without context. */
+export interface ContextUnavailable {
+    contextId: null;
+    decision: "UNAVAILABLE";
+    items: [];
+    reason: string;
+}
+export type ContextResult = ContextResponse | ContextUnavailable;
+export interface OutcomeInput {
+    itemId: string;
+    used: boolean;
+    outcome: "success" | "failure" | "neutral";
+    verification?: {
+        type: "agent_reported" | "signal_verified";
+        verifierType?: string;
+        evidenceHash?: string;
+    };
+}
+export interface OutcomeResponse {
+    contextId: string;
+    itemId: string;
+    recorded: boolean;
+    recallId?: string;
+    routeId?: string;
+    used?: boolean;
+    outcome?: string;
+    verification?: string;
+    detail?: string;
+}
+export interface ExtractProposal {
+    title?: string;
+    summary?: string;
+    [k: string]: unknown;
+}
+export interface ExtractResponse {
+    candidates?: ExtractProposal[];
+    proposals?: ExtractProposal[];
+    [k: string]: unknown;
+}

package/dist/esm/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "cognia-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Cognia for your model calls: one line gives any agent the Memories and Skills it may use, with provenance and honest receipts. Fails open.",
+  "license": "MIT",
+  "author": "Cognia",
+  "homepage": "https://cognia.fun/developers",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cognia-dev/memory-backend.git"
+  },
+  "keywords": [
+    "cognia",
+    "memory",
+    "agents",
+    "skills",
+    "vercel-ai-sdk",
+    "openai",
+    "anthropic",
+    "mcp"
+  ],
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^3.2.0",
+    "@types/node": "^22.0.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  }
 }