cognia-sdk 0.1.6 → 0.2.0

package/README.md

@@ -61,3 +61,49 @@ When nothing clears the relevance gates the answer is `ABSTAIN` with a reason an
 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`)
+
+## Receipts: what Cognia knows about each turn (0.1.7)
+
+Every model call through `withCognia` leaves a chain of receipts. Each step is a fact about usage; **only the last one is evidence**.
+
+| receipt | meaning | who records it |
+|---|---|---|
+| INJECTED | the item was placed in front of the model | the middleware, automatically |
+| CITED | the model's reply named the item (its `cognia://…` id or its title) | the middleware, automatically |
+| USED | your agent actually used it | you: `cognia.used(contextId, [itemId])` |
+| success / failure | what happened, with or without verification | you: `cognia.success(contextId, itemId, verification?)` |
+
+```ts
+const model = withCognia(openai, {
+  cognia,
+  onResponse: ({ contextId, cited, text }) => {
+    // cited = injected items the reply referenced; the cheapest honest next step is to say which were used
+    if (cited.length) void cognia.used(contextId, cited.map((i) => i.id));
+  },
+});
+// later, when a test, a check or a person confirms it worked:
+await cognia.success(contextId, itemId, { type: "signal_verified", verifierType: "test-suite" });
+// or, if you only know the agent used it:
+await cognia.success(contextId, itemId);   // recorded as agent-reported: counts as used, never as verified
+```
+
+A verified success needs a signal (a test, a check, a metric) or a human. Injected and cited never count as used; used never
+counts as success. Your Cognia Cloud Overview shows the loop per week: turns with context → cited → used → verified, with
+unverified reports listed apart.
+
+**Credits.** Reporting on other owners' knowledge earns Cloud credits (verified outcomes most, used receipts a little,
+context calls that injected a little), and your own memories earn when an independent agent's verified success lands on
+them. Credits pay for Workbench messages beyond your plan. They are not money. `GET /v1/cloud/me/credits` lists them.
+
+## Namespaces: one key, many end users (0.2.0)
+
+If you build an app where many people each have their own agent, give each of them a namespace:
+
+```ts
+const cognia = new Cognia({ apiKey: process.env.COGNIA_API_KEY, namespace: `user:${userId}` });
+```
+
+Every context call then carries that namespace. A private memory saved under it is returned only to the same
+namespace: the `mine` scope never crosses from one of your users to another, and the `organization` and `network`
+scopes add only what is shared with your organizations or public. Omit the namespace for a single-agent integration.
+Your own Cognia Cloud still shows everything the key owns: you are the data controller for your users' memories.

package/dist/cjs/client.js

@@ -62,7 +62,9 @@ class Cognia {
     tokenProvider;
     f;
     onError;
+    namespace;
     constructor(o) {
+        this.namespace = o.namespace;
         if (!o.apiKey && !o.tokenProvider)
             throw new Error("Cognia: apiKey or tokenProvider is required");
         this.key = o.apiKey ?? null;
@@ -166,7 +168,8 @@ class Cognia {
      */
     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 } : {}) };
+        const ns = body.identity?.namespace ?? this.namespace;
+        const payload = { task: body.task, scope: body.scope ?? this.scope, ...(body.budget ?? this.budget ? { budget: { ...this.budget, ...body.budget } } : {}), ...(body.session ? { session: body.session } : {}), ...(ns ? { identity: { namespace: ns } } : {}) };
         try {
             const r = await this.call("POST", "/v1/context", payload, this.timeoutMs);
             const shaped = shapeContext(r);
@@ -194,10 +197,41 @@ class Cognia {
             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. */
+    /** CITED: the model's reply referenced these items (the middleware detects this by itself). A usage receipt, never evidence. */
+    async cited(contextId, itemIds) {
+        if (!contextId || !itemIds.length)
+            return;
+        try {
+            await this.call("POST", `/v1/context/${encodeURIComponent(contextId)}/cited`, { itemIds }, 2000);
+        }
+        catch (e) {
+            this.onError?.(e instanceof Error ? e : new Error(String(e)));
+        }
+    }
+    /** USED: your agent actually used these items, whether or not you know yet how it turned out. The cheapest honest signal. */
+    async used(contextId, itemIds) {
+        if (!contextId || !itemIds.length)
+            return null;
+        try {
+            return await this.call("POST", `/v1/context/${encodeURIComponent(contextId)}/used`, { itemIds }, 3000);
+        }
+        catch (e) {
+            this.onError?.(e instanceof Error ? e : new Error(String(e)));
+            return null;
+        }
+    }
+    /** Report what happened with one item: used or not, success / failure (/ neutral for a Skill). This is the only path to success. */
     outcome(contextId, input) {
         return this.call("POST", `/v1/context/${encodeURIComponent(contextId)}/outcome`, input);
     }
+    /** One-liners for the two outcomes. Pass `verification` when a signal (a test, a check, a metric) or a human confirmed it;
+     *  without it the report is recorded as agent-reported, which counts as used but never as verified success. */
+    success(contextId, itemId, verification) {
+        return this.outcome(contextId, { itemId, used: true, outcome: "success", ...(verification ? { verification } : {}) });
+    }
+    failure(contextId, itemId, verification) {
+        return this.outcome(contextId, { itemId, used: true, outcome: "failure", ...(verification ? { verification } : {}) });
+    }
     /** 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/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.provenanceLine = exports.renderContextBlock = exports.textOf = exports.prependSystem = exports.contextFor = exports.withCognia = exports.CogniaSession = exports.shapeContext = exports.CogniaError = exports.Cognia = void 0;
+exports.provenanceLine = exports.renderContextBlock = exports.textOf = exports.prependSystem = exports.contextFor = exports.afterReply = exports.citedItems = exports.withCognia = exports.CogniaSession = exports.shapeContext = 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; } });
@@ -9,6 +9,8 @@ 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, "citedItems", { enumerable: true, get: function () { return middleware_js_1.citedItems; } });
+Object.defineProperty(exports, "afterReply", { enumerable: true, get: function () { return middleware_js_1.afterReply; } });
 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; } });

package/dist/cjs/middleware.js

@@ -1,10 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.citedItems = citedItems;
+exports.afterReply = afterReply;
 exports.textOf = textOf;
 exports.contextFor = contextFor;
 exports.prependSystem = prependSystem;
 exports.withCognia = withCognia;
 const render_js_1 = require("./render.js");
+/** Which injected items the reply referenced: its display id (cognia://…, cognia-skill://…) or its title. A citation is
+ *  a usage receipt the SDK can see without the host doing anything; it is never used and never success. */
+function citedItems(text, items) {
+    if (!text)
+        return [];
+    const t = text.toLowerCase();
+    return items.filter((it) => (it.displayId && t.includes(it.displayId.toLowerCase())) || (it.title && it.title.length >= 12 && t.includes(it.title.toLowerCase())));
+}
+/** After the reply is complete: the session learns it, the citations are reported, the host is told. Fire-and-forget. */
+function afterReply(o, ctx, text) {
+    if (text && o.session)
+        o.session.add({ role: "assistant", content: text });
+    if (!ctx)
+        return;
+    const cited = (o.citedBy ?? citedItems)(text, ctx.items);
+    if (cited.length)
+        void o.cognia.cited(ctx.contextId, cited.map((i) => i.id));
+    try {
+        o.onResponse?.({ contextId: ctx.contextId, items: ctx.items, text, cited });
+    }
+    catch { /* a host hook never breaks the call */ }
+}
 /** text of a message's content whatever the provider's shape (string, or parts with `text`) */
 function textOf(content) {
     if (typeof content === "string")
@@ -104,25 +128,23 @@ function withCognia(target, o) {
 }
 function wrapVercel(model, o) {
     const transform = async (params) => {
-        const { block } = await contextFor(o, params.prompt);
+        const { block, ctx } = await contextFor(o, params.prompt);
         if (!block)
-            return params;
-        return { ...params, prompt: [{ role: "system", content: block }, ...params.prompt] };
+            return { params, ctx };
+        return { params: { ...params, prompt: [{ role: "system", content: block }, ...params.prompt] }, ctx };
     };
-    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; };
+    const vercelText = (r) => { const t = r?.text; if (typeof t === "string")
+        return t; const c = r?.content; return Array.isArray(c) ? textOf(c) : ""; };
     return new Proxy(model, {
         get(t, k, recv) {
             if (k === "doGenerate")
-                return async (p) => learn(await t.doGenerate(await transform(p)));
+                return async (p) => { const { params, ctx } = await transform(p); const r = await t.doGenerate(params); afterReply(o, ctx, vercelText(r)); return r; };
             if (k === "doStream")
                 return async (p) => {
-                    const r = (await t.doStream(await transform(p)));
-                    if (o.session && r && r.stream instanceof ReadableStream)
-                        return { ...r, stream: teeStream(r.stream, (text) => o.session.add({ role: "assistant", content: text })) };
+                    const { params, ctx } = await transform(p);
+                    const r = (await t.doStream(params));
+                    if ((o.session || ctx) && r && r.stream instanceof ReadableStream)
+                        return { ...r, stream: teeStream(r.stream, (text) => afterReply(o, ctx, text)) };
                     return r;
                 };
             return Reflect.get(t, k, recv);
@@ -132,14 +154,12 @@ function wrapVercel(model, o) {
 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 { block, ctx } = await contextFor(o, p.messages);
         const r = await create(block ? { ...p, messages: prependSystem(p.messages, block) } : p, ...rest);
-        if (o.session) {
+        if (o.session || ctx) {
             if (isAsyncIterable(r) && !get(r, ["choices"]))
-                return teeIterable(r, (text) => o.session.add({ role: "assistant", content: text })); // stream: true
-            const text = textOf(get(r, ["choices", "0", "message", "content"]));
-            if (text)
-                o.session.add({ role: "assistant", content: text });
+                return teeIterable(r, (text) => afterReply(o, ctx, text)); // stream: true
+            afterReply(o, ctx, textOf(get(r, ["choices", "0", "message", "content"])));
         }
         return r;
     };
@@ -149,19 +169,17 @@ function wrapOpenAI(client, o) {
 function wrapAnthropic(client, o) {
     const create = client.messages.create.bind(client.messages);
     const wrapped = async (p, ...rest) => {
-        const { block } = await contextFor(o, p.messages);
+        const { block, ctx } = 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) {
+        if (o.session || ctx) {
             if (isAsyncIterable(r) && !get(r, ["content"]))
-                return teeIterable(r, (text) => o.session.add({ role: "assistant", content: text })); // stream: true
-            const text = textOf(get(r, ["content"]));
-            if (text)
-                o.session.add({ role: "assistant", content: text });
+                return teeIterable(r, (text) => afterReply(o, ctx, text)); // stream: true
+            afterReply(o, ctx, textOf(get(r, ["content"])));
         }
         return r;
     };

package/dist/esm/client.d.ts

@@ -1,5 +1,8 @@
-import type { ContextRequest, ContextResponse, ContextResult, OutcomeInput, OutcomeResponse, ExtractResponse, Scope } from "./types.js";
+import type { ReceiptResponse, ContextRequest, ContextResponse, ContextResult, OutcomeInput, OutcomeResponse, ExtractResponse, Scope } from "./types.js";
 export interface CogniaOptions {
+    /** end-user namespace sent on every context call (0.2.0). Use one per end user of YOUR app: their private memories
+     *  are then invisible to every other namespace under the same key. Omit for a single-agent integration. */
+    namespace?: string;
     /** the agent's credential (cognia_sk_…, a developer or SDK credential); never logged, never put in a URL */
     apiKey?: string;
     /** Delegated auth: called at REQUEST time to obtain the bearer (e.g. an MCP OAuth access token the host already
@@ -39,6 +42,7 @@ export declare class Cognia {
     private readonly tokenProvider;
     private readonly f;
     private readonly onError;
+    readonly namespace: string | undefined;
     constructor(o: CogniaOptions);
     /** Every string that reaches the host through an error or a reason has the bearer removed first (independent E2E F28). */
     private scrub;
@@ -51,8 +55,16 @@ export declare class Cognia {
     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. */
+    /** CITED: the model's reply referenced these items (the middleware detects this by itself). A usage receipt, never evidence. */
+    cited(contextId: string, itemIds: string[]): Promise<void>;
+    /** USED: your agent actually used these items, whether or not you know yet how it turned out. The cheapest honest signal. */
+    used(contextId: string, itemIds: string[]): Promise<ReceiptResponse | null>;
+    /** Report what happened with one item: used or not, success / failure (/ neutral for a Skill). This is the only path to success. */
     outcome(contextId: string, input: OutcomeInput): Promise<OutcomeResponse>;
+    /** One-liners for the two outcomes. Pass `verification` when a signal (a test, a check, a metric) or a human confirmed it;
+     *  without it the report is recorded as agent-reported, which counts as used but never as verified success. */
+    success(contextId: string, itemId: string, verification?: OutcomeInput["verification"]): Promise<OutcomeResponse>;
+    failure(contextId: string, itemId: string, verification?: OutcomeInput["verification"]): 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

@@ -57,7 +57,9 @@ export class Cognia {
     tokenProvider;
     f;
     onError;
+    namespace;
     constructor(o) {
+        this.namespace = o.namespace;
         if (!o.apiKey && !o.tokenProvider)
             throw new Error("Cognia: apiKey or tokenProvider is required");
         this.key = o.apiKey ?? null;
@@ -161,7 +163,8 @@ export class Cognia {
      */
     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 } : {}) };
+        const ns = body.identity?.namespace ?? this.namespace;
+        const payload = { task: body.task, scope: body.scope ?? this.scope, ...(body.budget ?? this.budget ? { budget: { ...this.budget, ...body.budget } } : {}), ...(body.session ? { session: body.session } : {}), ...(ns ? { identity: { namespace: ns } } : {}) };
         try {
             const r = await this.call("POST", "/v1/context", payload, this.timeoutMs);
             const shaped = shapeContext(r);
@@ -189,10 +192,41 @@ export class Cognia {
             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. */
+    /** CITED: the model's reply referenced these items (the middleware detects this by itself). A usage receipt, never evidence. */
+    async cited(contextId, itemIds) {
+        if (!contextId || !itemIds.length)
+            return;
+        try {
+            await this.call("POST", `/v1/context/${encodeURIComponent(contextId)}/cited`, { itemIds }, 2000);
+        }
+        catch (e) {
+            this.onError?.(e instanceof Error ? e : new Error(String(e)));
+        }
+    }
+    /** USED: your agent actually used these items, whether or not you know yet how it turned out. The cheapest honest signal. */
+    async used(contextId, itemIds) {
+        if (!contextId || !itemIds.length)
+            return null;
+        try {
+            return await this.call("POST", `/v1/context/${encodeURIComponent(contextId)}/used`, { itemIds }, 3000);
+        }
+        catch (e) {
+            this.onError?.(e instanceof Error ? e : new Error(String(e)));
+            return null;
+        }
+    }
+    /** Report what happened with one item: used or not, success / failure (/ neutral for a Skill). This is the only path to success. */
     outcome(contextId, input) {
         return this.call("POST", `/v1/context/${encodeURIComponent(contextId)}/outcome`, input);
     }
+    /** One-liners for the two outcomes. Pass `verification` when a signal (a test, a check, a metric) or a human confirmed it;
+     *  without it the report is recorded as agent-reported, which counts as used but never as verified success. */
+    success(contextId, itemId, verification) {
+        return this.outcome(contextId, { itemId, used: true, outcome: "success", ...(verification ? { verification } : {}) });
+    }
+    failure(contextId, itemId, verification) {
+        return this.outcome(contextId, { itemId, used: true, outcome: "failure", ...(verification ? { verification } : {}) });
+    }
     /** 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

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

package/dist/esm/index.js

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

package/dist/esm/middleware.d.ts

@@ -18,7 +18,22 @@ export interface WithCogniaOptions {
         role: string;
         content: unknown;
     }>) => string | null;
+    /** called once the model's reply is complete (streams included): the context, the reply text and which injected items
+     *  the reply cited. The place to call `cognia.used(...)` / `cognia.success(...)` from, or to show sources that were used. */
+    onResponse?: (r: {
+        contextId: string;
+        items: ContextItem[];
+        text: string;
+        cited: ContextItem[];
+    }) => void;
+    /** detect citations in the reply yourself (default: display id, or the title when it is 12+ characters, found in the text) */
+    citedBy?: (text: string, items: ContextItem[]) => ContextItem[];
 }
+/** Which injected items the reply referenced: its display id (cognia://…, cognia-skill://…) or its title. A citation is
+ *  a usage receipt the SDK can see without the host doing anything; it is never used and never success. */
+export declare function citedItems(text: string, items: ContextItem[]): ContextItem[];
+/** After the reply is complete: the session learns it, the citations are reported, the host is told. Fire-and-forget. */
+export declare function afterReply(o: WithCogniaOptions, ctx: ContextResponse | null, text: string): void;
 /** text of a message's content whatever the provider's shape (string, or parts with `text`) */
 export declare function textOf(content: unknown): string;
 /**

package/dist/esm/middleware.js

@@ -1,4 +1,26 @@
 import { renderContextBlock } from "./render.js";
+/** Which injected items the reply referenced: its display id (cognia://…, cognia-skill://…) or its title. A citation is
+ *  a usage receipt the SDK can see without the host doing anything; it is never used and never success. */
+export function citedItems(text, items) {
+    if (!text)
+        return [];
+    const t = text.toLowerCase();
+    return items.filter((it) => (it.displayId && t.includes(it.displayId.toLowerCase())) || (it.title && it.title.length >= 12 && t.includes(it.title.toLowerCase())));
+}
+/** After the reply is complete: the session learns it, the citations are reported, the host is told. Fire-and-forget. */
+export function afterReply(o, ctx, text) {
+    if (text && o.session)
+        o.session.add({ role: "assistant", content: text });
+    if (!ctx)
+        return;
+    const cited = (o.citedBy ?? citedItems)(text, ctx.items);
+    if (cited.length)
+        void o.cognia.cited(ctx.contextId, cited.map((i) => i.id));
+    try {
+        o.onResponse?.({ contextId: ctx.contextId, items: ctx.items, text, cited });
+    }
+    catch { /* a host hook never breaks the call */ }
+}
 /** text of a message's content whatever the provider's shape (string, or parts with `text`) */
 export function textOf(content) {
     if (typeof content === "string")
@@ -98,25 +120,23 @@ export function withCognia(target, o) {
 }
 function wrapVercel(model, o) {
     const transform = async (params) => {
-        const { block } = await contextFor(o, params.prompt);
+        const { block, ctx } = await contextFor(o, params.prompt);
         if (!block)
-            return params;
-        return { ...params, prompt: [{ role: "system", content: block }, ...params.prompt] };
+            return { params, ctx };
+        return { params: { ...params, prompt: [{ role: "system", content: block }, ...params.prompt] }, ctx };
     };
-    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; };
+    const vercelText = (r) => { const t = r?.text; if (typeof t === "string")
+        return t; const c = r?.content; return Array.isArray(c) ? textOf(c) : ""; };
     return new Proxy(model, {
         get(t, k, recv) {
             if (k === "doGenerate")
-                return async (p) => learn(await t.doGenerate(await transform(p)));
+                return async (p) => { const { params, ctx } = await transform(p); const r = await t.doGenerate(params); afterReply(o, ctx, vercelText(r)); return r; };
             if (k === "doStream")
                 return async (p) => {
-                    const r = (await t.doStream(await transform(p)));
-                    if (o.session && r && r.stream instanceof ReadableStream)
-                        return { ...r, stream: teeStream(r.stream, (text) => o.session.add({ role: "assistant", content: text })) };
+                    const { params, ctx } = await transform(p);
+                    const r = (await t.doStream(params));
+                    if ((o.session || ctx) && r && r.stream instanceof ReadableStream)
+                        return { ...r, stream: teeStream(r.stream, (text) => afterReply(o, ctx, text)) };
                     return r;
                 };
             return Reflect.get(t, k, recv);
@@ -126,14 +146,12 @@ function wrapVercel(model, o) {
 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 { block, ctx } = await contextFor(o, p.messages);
         const r = await create(block ? { ...p, messages: prependSystem(p.messages, block) } : p, ...rest);
-        if (o.session) {
+        if (o.session || ctx) {
             if (isAsyncIterable(r) && !get(r, ["choices"]))
-                return teeIterable(r, (text) => o.session.add({ role: "assistant", content: text })); // stream: true
-            const text = textOf(get(r, ["choices", "0", "message", "content"]));
-            if (text)
-                o.session.add({ role: "assistant", content: text });
+                return teeIterable(r, (text) => afterReply(o, ctx, text)); // stream: true
+            afterReply(o, ctx, textOf(get(r, ["choices", "0", "message", "content"])));
         }
         return r;
     };
@@ -143,19 +161,17 @@ function wrapOpenAI(client, o) {
 function wrapAnthropic(client, o) {
     const create = client.messages.create.bind(client.messages);
     const wrapped = async (p, ...rest) => {
-        const { block } = await contextFor(o, p.messages);
+        const { block, ctx } = 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) {
+        if (o.session || ctx) {
             if (isAsyncIterable(r) && !get(r, ["content"]))
-                return teeIterable(r, (text) => o.session.add({ role: "assistant", content: text })); // stream: true
-            const text = textOf(get(r, ["content"]));
-            if (text)
-                o.session.add({ role: "assistant", content: text });
+                return teeIterable(r, (text) => afterReply(o, ctx, text)); // stream: true
+            afterReply(o, ctx, textOf(get(r, ["content"])));
         }
         return r;
     };

package/dist/esm/types.d.ts

@@ -12,6 +12,10 @@ export interface ContextRequest {
         id: string;
         turn: number;
     };
+    /** end-user namespace (0.2.0): one developer key, many end users; private memories are isolated per namespace */
+    identity?: {
+        namespace?: string;
+    };
 }
 export interface MemoryItem {
     kind: "memory";
@@ -89,11 +93,20 @@ export interface OutcomeInput {
     used: boolean;
     outcome: "success" | "failure" | "neutral";
     verification?: {
-        type: "agent_reported" | "signal_verified";
+        type: "agent_reported" | "signal_verified" | "human_confirmed";
         verifierType?: string;
         evidenceHash?: string;
     };
 }
+/** receipt replies for the usage receipts between injected and outcome (2026-10-08) */
+export interface ReceiptResponse {
+    contextId: string;
+    receipts: Array<{
+        kind: "INJECTED" | "CITED" | "USED";
+        itemId: string;
+    }>;
+    note?: string;
+}
 export interface OutcomeResponse {
     contextId: string;
     itemId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cognia-sdk",
-  "version": "0.1.6",
+  "version": "0.2.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",
@@ -38,14 +38,15 @@
     "node": ">=20"
   },
   "sideEffects": false,
+  "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",
+    "prepack": "pnpm run build && node scripts/privacy-check.mjs"
+  },
   "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"
   }
-}
+}