@laserdata/laser-sdk 0.0.1-rc.21 → 0.0.1-rc.22

package/dist/memory/log-memory.js

@@ -0,0 +1,309 @@
+import { NoStreamError } from "../client/errors.js";
+import { INTERNAL_GOVERN, INTERNAL_TRANSPORT } from "../client/internals.js";
+import { ActionKind } from "../govern.js";
+import { AgentTopic } from "../provenance/agent-topic.js";
+import { decodeProvenanceHeaders, encodeProvenanceHeaders } from "../provenance/provenance.js";
+import { AgentId, ConversationId } from "../types/ids.js";
+import { MEMORY_APP, MEMORY_NAMESPACE, MEMORY_USER } from "../wire/headers.js";
+import { decodeOne } from "../wire/cbor.js";
+import { decodeMemoryRecord, encodeMemoryRecordFrame } from "../wire/memory.js";
+import { MemoryId, MemoryKind, RecallStrategy } from "./types.js";
+export class LogMemory {
+    laser;
+    namespace;
+    topic;
+    stream;
+    items = new Map();
+    forgotten = new Set();
+    named = new Map();
+    offsets = new Map();
+    sequence = 0;
+    constructor(laser, namespace, topic = AgentTopic.Audit, stream = laser.defaultStream) {
+        this.laser = laser;
+        this.namespace = namespace;
+        this.topic = topic;
+        this.stream = stream;
+    }
+    async remember(scope, payload) {
+        return this.append(scope, MemoryId.new(), MemoryKind.Fact, payload);
+    }
+    async append(scope, id, kind, payload) {
+        await this.publish(scope, id.toString(), {
+            kind: "item",
+            id: id.toString(),
+            memoryKind: kind,
+            body: payload.slice()
+        });
+        return id;
+    }
+    /** Reads the managed key-value view the deployment materializes from the
+     * memory topic, so a large topic never folds in process. Folding is the
+     * opt-in {@link LogMemory.recallFolded}, never the default, matching Rust and Python. */
+    async recall(scope, query) {
+        const { conversation } = scope;
+        if (conversation === undefined)
+            return [];
+        // One conversation's memory is bounded by the lens, so page through it and
+        // keep the most recent `limit`. Ids are time-ordered ULIDs, so the tail
+        // after sorting is the newest.
+        const entries = await this.laser
+            .kv(this.namespace)
+            .scan()
+            .conversation(conversation.toString())
+            .entries();
+        const agent = query.agent ?? scope.agent;
+        const items = entries
+            .map((entry) => itemFromEntry(conversation, entry))
+            .filter((item) => item !== undefined)
+            .filter((item) => agent === undefined || item.provenance.agent?.equals(agent) === true)
+            .sort((left, right) => (left.id.toString() < right.id.toString() ? -1 : 1));
+        const limit = query.limit ?? 50;
+        return items.length > limit ? items.slice(items.length - limit) : items;
+    }
+    /** Recall by folding the memory topic in process, the opt-in path for a small
+     * deployment with no materialized read view. */
+    async recallFolded(scope, query) {
+        await this.catchUp();
+        const agent = query.agent ?? scope.agent;
+        const matched = [...this.items.values()]
+            .filter((entry) => matchesScope(entry.scope, scope, agent))
+            .sort((left, right) => right.feedback - left.feedback || right.sequence - left.sequence)
+            .slice(0, query.limit ?? 50);
+        const strategy = query.strategy ?? RecallStrategy.Auto;
+        return matched.map((entry, rank) => ({
+            ...entry.item,
+            payload: entry.item.payload.slice(),
+            ...(entry.feedback !== 0 ? { score: entry.feedback } : {}),
+            signals: entry.feedback === 0 ? [] : [{ strategy, rank, score: entry.feedback }]
+        }));
+    }
+    async improve(scope, feedback) {
+        const id = MemoryId.new();
+        await this.publish(scope, id.toString(), {
+            kind: "feedback",
+            target: feedback.target.toString(),
+            weight: feedback.weight
+        });
+        return id;
+    }
+    async forget(scope, id) {
+        await this.publish(scope, id.toString(), { kind: "forget", target: id.toString() });
+    }
+    async set(key, payload) {
+        const id = this.namedKey(key);
+        await this.publish({}, id, {
+            kind: "item",
+            id,
+            memoryKind: MemoryKind.Fact,
+            body: payload.slice()
+        });
+        this.named.set(id, payload.slice());
+    }
+    /** Reads named point state from the managed key-value view, like {@link LogMemory.recall}.
+     * Folding the topic is the opt-in {@link LogMemory.fetchFolded}. */
+    async fetch(key) {
+        return this.laser.kv(this.namespace).get(new TextEncoder().encode(this.namedKey(key)));
+    }
+    async fetchFolded(key) {
+        await this.catchUp();
+        return this.named.get(this.namedKey(key))?.slice();
+    }
+    async update(key, patch) {
+        const current = await this.fetchFolded(key);
+        const base = current === undefined ? null : JSON.parse(new TextDecoder().decode(current));
+        const patchValue = JSON.parse(new TextDecoder().decode(patch));
+        const merged = mergePatch(base, patchValue);
+        await this.set(key, new TextEncoder().encode(JSON.stringify(merged)));
+    }
+    async remove(key) {
+        const id = this.namedKey(key);
+        await this.publish({}, id, { kind: "forget", target: id });
+        this.named.delete(id);
+    }
+    async publish(scope, idempotencyKey, record) {
+        const stream = this.requireStream();
+        const conversation = scope.conversation ?? ConversationId.derive(idempotencyKey);
+        const headers = new Map(encodeProvenanceHeaders({
+            conversationId: conversation,
+            ...(scope.agent !== undefined ? { agent: scope.agent } : {}),
+            idempotencyKey
+        }));
+        headers.set(MEMORY_NAMESPACE, stringHeader(this.namespace));
+        if (scope.user !== undefined)
+            headers.set(MEMORY_USER, stringHeader(scope.user));
+        if (scope.application !== undefined)
+            headers.set(MEMORY_APP, stringHeader(scope.application));
+        const encoded = encodeMemoryRecordFrame(record);
+        const payload = await this.laser[INTERNAL_GOVERN]({
+            kind: ActionKind.MemoryWrite,
+            stream,
+            topic: this.topic,
+            ...(scope.agent !== undefined ? { source: scope.agent.asString() } : {}),
+            conversation,
+            payload: encoded,
+            signed: false
+        });
+        await this.laser[INTERNAL_TRANSPORT]().sendMessageWithHeaders(stream, this.topic, payload, headers, conversation.toString());
+    }
+    async catchUp() {
+        const stream = this.requireStream();
+        const cursor = await this.laser.stream(stream).topic(this.topic).replay({ batchSize: 1000 });
+        const topicIds = await this.laser[INTERNAL_TRANSPORT]().resolveStreamTopicIds?.(stream, this.topic);
+        cursor.fromOffsets(this.offsets);
+        for (;;) {
+            const messages = await cursor.poll();
+            if (messages.length === 0)
+                break;
+            for (const message of messages) {
+                this.offsets.set(message.partitionId, message.offset + 1n);
+                if (headerString(message.headers, MEMORY_NAMESPACE) !== this.namespace)
+                    continue;
+                let record;
+                try {
+                    record = decodeMemoryRecord(decodeOne(message.payload, "memory record"), "memory record");
+                }
+                catch {
+                    continue;
+                }
+                this.absorb(record, message.headers, topicIds === undefined
+                    ? undefined
+                    : {
+                        kind: "message",
+                        stream: topicIds.streamId,
+                        topic: topicIds.topicId,
+                        partition: message.partitionId,
+                        offset: message.offset
+                    });
+            }
+        }
+    }
+    absorb(record, headers, source) {
+        if (record.kind === "forget") {
+            this.items.delete(record.target);
+            this.forgotten.add(record.target);
+            this.named.delete(record.target);
+            return;
+        }
+        if (record.kind === "feedback") {
+            const entry = this.items.get(record.target);
+            if (entry !== undefined)
+                entry.feedback += record.weight;
+            return;
+        }
+        if (record.id.startsWith(`${this.namespace}/`)) {
+            this.named.set(record.id, record.body.slice());
+            return;
+        }
+        if (this.forgotten.has(record.id) || this.items.has(record.id))
+            return;
+        const id = MemoryId.parse(record.id);
+        const provenance = decodeProvenanceHeaders(headers);
+        const user = headerString(headers, MEMORY_USER);
+        const application = headerString(headers, MEMORY_APP);
+        const scope = {
+            ...(user !== undefined ? { user } : {}),
+            ...(provenance.agent !== undefined ? { agent: provenance.agent } : {}),
+            conversation: provenance.conversationId,
+            ...(application !== undefined ? { application } : {}),
+            ...(this.stream !== undefined ? { stream: this.stream } : {})
+        };
+        this.items.set(record.id, {
+            item: {
+                id,
+                payload: record.body.slice(),
+                provenance,
+                kind: parseKind(record.memoryKind),
+                signals: [],
+                ...(source === undefined
+                    ? {}
+                    : {
+                        source: {
+                            ...source,
+                            ...(source.kind === "message"
+                                ? { conversation: provenance.conversationId.toString() }
+                                : {})
+                        }
+                    })
+            },
+            scope,
+            sequence: this.sequence,
+            feedback: 0
+        });
+        this.sequence += 1;
+    }
+    namedKey(key) {
+        return `${this.namespace}/${key}`;
+    }
+    requireStream() {
+        if (this.stream === undefined) {
+            throw new NoStreamError("log memory requires a default stream");
+        }
+        return this.stream;
+    }
+}
+function stringHeader(value) {
+    return { kind: "string", value };
+}
+function headerString(headers, key) {
+    const value = headers.get(key);
+    return value?.kind === "string" ? value.value : undefined;
+}
+function parseKind(word) {
+    return Object.values(MemoryKind).includes(word)
+        ? word
+        : MemoryKind.Fact;
+}
+// Rebuild a memory item from a read-view row, or `undefined` when the key is a
+// named-item key rather than a recall id, or the row carries no memory scope.
+function itemFromEntry(conversation, entry) {
+    const { scope } = entry;
+    if (scope === undefined)
+        return undefined;
+    let id;
+    try {
+        id = MemoryId.parse(new TextDecoder().decode(entry.key));
+    }
+    catch {
+        return undefined;
+    }
+    const agent = scope.agent;
+    return {
+        id,
+        payload: entry.value.slice(),
+        provenance: {
+            conversationId: conversation,
+            ...(agent === undefined ? {} : { agent: AgentId.new(agent) })
+        },
+        kind: kindFromWord(scope.kind),
+        ...(scope.source === undefined ? {} : { source: scope.source }),
+        signals: []
+    };
+}
+function kindFromWord(word) {
+    const kinds = Object.values(MemoryKind);
+    return kinds.find((kind) => kind === word) ?? MemoryKind.Fact;
+}
+function matchesScope(stored, requested, agent) {
+    return ((requested.stream === undefined || stored.stream === requested.stream) &&
+        (requested.user === undefined || stored.user === requested.user) &&
+        (agent === undefined || stored.agent?.equals(agent) === true) &&
+        (requested.conversation === undefined ||
+            stored.conversation?.equals(requested.conversation) === true) &&
+        (requested.application === undefined || stored.application === requested.application));
+}
+function mergePatch(base, patch) {
+    if (!isObject(patch))
+        return patch;
+    const output = isObject(base) ? { ...base } : {};
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === null)
+            Reflect.deleteProperty(output, key);
+        else
+            output[key] = mergePatch(output[key], value);
+    }
+    return output;
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=log-memory.js.map

package/dist/memory/log-memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-memory.js","sourceRoot":"","sources":["../../src/memory/log-memory.ts"],"names":[],"mappings":"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"}

package/dist/memory/topic.d.ts

@@ -0,0 +1,22 @@
+import type { Laser } from "../client/laser.js";
+import { MemoryHandle } from "./handle.js";
+/** Configures and opens a durable memory topic. */
+export declare class MemoryTopicBuilder {
+    private readonly laser;
+    private readonly topic;
+    private streamValue;
+    private partitionsValue;
+    private ttlMs;
+    constructor(laser: Laser, topic: string);
+    /** Selects a stream instead of the client's default stream. */
+    stream(name: string): this;
+    /** Sets the partition count used to spread independent memory scopes. */
+    partitions(count: number): this;
+    /** Sets message expiry in milliseconds. */
+    ttl(milliseconds: number): this;
+    /** Keeps memory records until ordinary topic retention removes them. */
+    noExpiry(): this;
+    /** Ensures the topic and returns memory bound to it. */
+    build(): Promise<MemoryHandle>;
+}
+//# sourceMappingURL=topic.d.ts.map

package/dist/memory/topic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic.d.ts","sourceRoot":"","sources":["../../src/memory/topic.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAI1C,mDAAmD;AACnD,qBAAa,kBAAkB;IAM3B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IANxB,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,eAAe,CAAI;IAC3B,OAAO,CAAC,KAAK,CAA4C;IAEzD,YACmB,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,MAAM,EAC5B;IAEJ,+DAA+D;IAC/D,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAGzB;IAED,yEAAyE;IACzE,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAM9B;IAED,2CAA2C;IAC3C,GAAG,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAM9B;IAED,wEAAwE;IACxE,QAAQ,IAAI,IAAI,CAGf;IAED,wDAAwD;IAClD,KAAK,IAAI,OAAO,CAAC,YAAY,CAAC,CAWnC;CACF"}

package/dist/memory/topic.js

@@ -0,0 +1,56 @@
+import { InvalidError, NoStreamError } from "../client/errors.js";
+import { MemoryHandle } from "./handle.js";
+const DEFAULT_MEMORY_TTL_MS = 30 * 24 * 60 * 60 * 1_000;
+/** Configures and opens a durable memory topic. */
+export class MemoryTopicBuilder {
+    laser;
+    topic;
+    streamValue;
+    partitionsValue = 1;
+    ttlMs = DEFAULT_MEMORY_TTL_MS;
+    constructor(laser, topic) {
+        this.laser = laser;
+        this.topic = topic;
+    }
+    /** Selects a stream instead of the client's default stream. */
+    stream(name) {
+        this.streamValue = name;
+        return this;
+    }
+    /** Sets the partition count used to spread independent memory scopes. */
+    partitions(count) {
+        if (!Number.isSafeInteger(count) || count < 1) {
+            throw new InvalidError("memory topic partitions must be a positive safe integer");
+        }
+        this.partitionsValue = count;
+        return this;
+    }
+    /** Sets message expiry in milliseconds. */
+    ttl(milliseconds) {
+        if (!Number.isSafeInteger(milliseconds) || milliseconds < 1) {
+            throw new InvalidError("memory topic TTL must be a positive whole number of milliseconds");
+        }
+        this.ttlMs = milliseconds;
+        return this;
+    }
+    /** Keeps memory records until ordinary topic retention removes them. */
+    noExpiry() {
+        this.ttlMs = undefined;
+        return this;
+    }
+    /** Ensures the topic and returns memory bound to it. */
+    async build() {
+        const stream = this.streamValue ?? this.laser.defaultStream;
+        if (stream === undefined)
+            throw new NoStreamError("memory topic requires a stream");
+        await this.laser.stream(stream).ensure();
+        await this.laser
+            .stream(stream)
+            .topic(this.topic)
+            .ensure(this.partitionsValue, {
+            messageExpiryMicros: this.ttlMs === undefined ? 0n : BigInt(this.ttlMs) * 1000n
+        });
+        return MemoryHandle.logTopic(this.laser, this.topic, stream);
+    }
+}
+//# sourceMappingURL=topic.js.map

package/dist/memory/topic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic.js","sourceRoot":"","sources":["../../src/memory/topic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAEjE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE1C,MAAM,qBAAqB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,CAAA;AAEvD,mDAAmD;AACnD,MAAM,OAAO,kBAAkB;IAMV,KAAK;IACL,KAAK;IANhB,WAAW,CAAoB;IAC/B,eAAe,GAAG,CAAC,CAAA;IACnB,KAAK,GAAuB,qBAAqB,CAAA;IAEzD,YACmB,KAAY,EACZ,KAAa;qBADb,KAAK;qBACL,KAAK;IACrB,CAAC;IAEJ,+DAA+D;IAC/D,MAAM,CAAC,IAAY;QACjB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAA;QACvB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,yEAAyE;IACzE,UAAU,CAAC,KAAa;QACtB,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YAC9C,MAAM,IAAI,YAAY,CAAC,yDAAyD,CAAC,CAAA;QACnF,CAAC;QACD,IAAI,CAAC,eAAe,GAAG,KAAK,CAAA;QAC5B,OAAO,IAAI,CAAA;IACb,CAAC;IAED,2CAA2C;IAC3C,GAAG,CAAC,YAAoB;QACtB,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,YAAY,CAAC,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;YAC5D,MAAM,IAAI,YAAY,CAAC,kEAAkE,CAAC,CAAA;QAC5F,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,YAAY,CAAA;QACzB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,wEAAwE;IACxE,QAAQ;QACN,IAAI,CAAC,KAAK,GAAG,SAAS,CAAA;QACtB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,wDAAwD;IACxD,KAAK,CAAC,KAAK;QACT,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,KAAK,CAAC,aAAa,CAAA;QAC3D,IAAI,MAAM,KAAK,SAAS;YAAE,MAAM,IAAI,aAAa,CAAC,gCAAgC,CAAC,CAAA;QACnF,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,CAAA;QACxC,MAAM,IAAI,CAAC,KAAK;aACb,MAAM,CAAC,MAAM,CAAC;aACd,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;aACjB,MAAM,CAAC,IAAI,CAAC,eAAe,EAAE;YAC5B,mBAAmB,EAAE,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,KAAM;SACjF,CAAC,CAAA;QACJ,OAAO,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IAC9D,CAAC;CACF"}

package/dist/memory/types.d.ts

@@ -0,0 +1,108 @@
+import { type UlidSource } from "../runtime/ulid.js";
+import { ConversationId } from "../types/ids.js";
+import type { AgentId } from "../types/ids.js";
+import type { SourceRef } from "../wire/graph.js";
+export declare const MemoryKind: {
+    readonly Fact: "fact";
+    readonly Message: "message";
+    readonly Summary: "summary";
+    readonly Entity: "entity";
+    readonly Feedback: "feedback";
+    readonly Procedure: "procedure";
+};
+export type MemoryKind = (typeof MemoryKind)[keyof typeof MemoryKind];
+export declare const MemoryClass: {
+    readonly Episodic: "episodic";
+    readonly Semantic: "semantic";
+    readonly Procedural: "procedural";
+};
+export type MemoryClass = (typeof MemoryClass)[keyof typeof MemoryClass];
+export declare const Lifetime: {
+    readonly Session: "session";
+    readonly Durable: "durable";
+};
+export type Lifetime = (typeof Lifetime)[keyof typeof Lifetime];
+export declare const RecallStrategy: {
+    readonly Auto: "auto";
+    readonly Recent: "recent";
+    readonly Semantic: "semantic";
+    readonly Keyword: "keyword";
+    readonly Graph: "graph";
+    readonly Temporal: "temporal";
+    readonly Hybrid: "hybrid";
+};
+export type RecallStrategy = (typeof RecallStrategy)[keyof typeof RecallStrategy];
+export declare function memoryClass(kind: MemoryKind): MemoryClass;
+export declare class MemoryId {
+    private readonly value;
+    private constructor();
+    static new(source?: UlidSource): MemoryId;
+    static fromU128(value: bigint): MemoryId;
+    static parse(text: string): MemoryId;
+    static content(owner: MemoryScope, kind: MemoryKind, body: Uint8Array): MemoryId;
+    asU128(): bigint;
+    equals(other: MemoryId): boolean;
+    toString(): string;
+}
+export interface MemoryScope {
+    readonly stream?: string;
+    readonly user?: string;
+    readonly agent?: AgentId;
+    readonly conversation?: ConversationId;
+    readonly application?: string;
+    readonly lifetime?: Lifetime;
+}
+export interface RecallSignal {
+    readonly strategy: RecallStrategy;
+    readonly rank: number;
+    readonly score?: number;
+}
+export interface MemoryItem {
+    readonly id: MemoryId;
+    readonly payload: Uint8Array;
+    readonly provenance: {
+        readonly conversationId: ConversationId;
+        readonly agent?: AgentId;
+        readonly idempotencyKey?: string;
+    };
+    readonly kind: MemoryKind;
+    readonly score?: number;
+    readonly signals: readonly RecallSignal[];
+    readonly source?: SourceRef;
+}
+export interface MemoryQuery {
+    readonly limit?: number;
+    readonly tokenBudget?: number;
+    readonly agent?: AgentId;
+    readonly semantic?: string;
+    readonly strategy?: RecallStrategy;
+}
+export interface Feedback {
+    readonly target: MemoryId;
+    readonly weight: number;
+    readonly note?: string;
+}
+export interface Memory {
+    remember(scope: MemoryScope, payload: Uint8Array): Promise<MemoryId>;
+    recall(scope: MemoryScope, query: MemoryQuery): Promise<readonly MemoryItem[]>;
+    improve(scope: MemoryScope, feedback: Feedback): Promise<MemoryId>;
+    forget(scope: MemoryScope, id: MemoryId): Promise<void>;
+}
+export interface Embedder {
+    embed(text: string): Promise<readonly number[]>;
+}
+export interface Reranker {
+    rerank(query: string, items: readonly MemoryItem[]): Promise<readonly MemoryItem[]>;
+}
+export interface ConsolidationReport {
+    readonly scanned: number;
+    readonly kept: number;
+    readonly forgotten: number;
+}
+export interface Consolidator {
+    consolidate(memory: Memory, scope: MemoryScope): Promise<ConsolidationReport>;
+}
+export declare function toContextBlock(items: readonly MemoryItem[], tokenBudget?: number): string;
+export declare function fuseReciprocalRank(signals: readonly (readonly MemoryItem[])[], limit: number): readonly MemoryItem[];
+export declare const ZERO_CONVERSATION: ConversationId;
+//# sourceMappingURL=types.d.ts.map

package/dist/memory/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/memory/types.ts"],"names":[],"mappings":"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"}

package/dist/memory/types.js

@@ -0,0 +1,127 @@
+import { InvalidError } from "../client/errors.js";
+import { mintUlidValue } from "../runtime/ulid.js";
+import { ConversationId } from "../types/ids.js";
+import { contentId } from "../wire/hashing.js";
+import { crockfordDecode, crockfordEncode } from "../wire/ids.js";
+export const MemoryKind = {
+    Fact: "fact",
+    Message: "message",
+    Summary: "summary",
+    Entity: "entity",
+    Feedback: "feedback",
+    Procedure: "procedure"
+};
+export const MemoryClass = {
+    Episodic: "episodic",
+    Semantic: "semantic",
+    Procedural: "procedural"
+};
+export const Lifetime = { Session: "session", Durable: "durable" };
+export const RecallStrategy = {
+    Auto: "auto",
+    Recent: "recent",
+    Semantic: "semantic",
+    Keyword: "keyword",
+    Graph: "graph",
+    Temporal: "temporal",
+    Hybrid: "hybrid"
+};
+const KIND_CODES = {
+    [MemoryKind.Fact]: 1,
+    [MemoryKind.Message]: 2,
+    [MemoryKind.Summary]: 3,
+    [MemoryKind.Entity]: 4,
+    [MemoryKind.Feedback]: 5,
+    [MemoryKind.Procedure]: 6
+};
+export function memoryClass(kind) {
+    if (kind === MemoryKind.Message)
+        return MemoryClass.Episodic;
+    if (kind === MemoryKind.Procedure)
+        return MemoryClass.Procedural;
+    return MemoryClass.Semantic;
+}
+export class MemoryId {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+    static new(source) {
+        return new MemoryId(mintUlidValue(source));
+    }
+    static fromU128(value) {
+        if (value < 0n || value >= 1n << 128n) {
+            throw new InvalidError("memory id must fit in 128 bits", { value: value.toString() });
+        }
+        return new MemoryId(value);
+    }
+    static parse(text) {
+        return MemoryId.fromU128(crockfordDecode(text));
+    }
+    static content(owner, kind, body) {
+        const encoder = new TextEncoder();
+        const segments = [
+            encoder.encode(owner.stream ?? ""),
+            Uint8Array.of(0),
+            encoder.encode(owner.agent?.asString() ?? ""),
+            Uint8Array.of(0),
+            Uint8Array.of(KIND_CODES[kind]),
+            body
+        ];
+        return MemoryId.fromU128(contentId(segments));
+    }
+    asU128() {
+        return this.value;
+    }
+    equals(other) {
+        return this.value === other.value;
+    }
+    toString() {
+        return crockfordEncode(this.value);
+    }
+}
+export function toContextBlock(items, tokenBudget) {
+    let spent = 0;
+    let rendered = 0;
+    const blocks = [];
+    for (const item of items) {
+        const text = new TextDecoder().decode(item.payload);
+        const cost = Math.max(1, Math.ceil(new TextEncoder().encode(text).byteLength / 4));
+        if (tokenBudget !== undefined && rendered > 0 && spent + cost > tokenBudget)
+            break;
+        blocks.push(text);
+        spent += cost;
+        rendered += 1;
+    }
+    const omitted = items.length - rendered;
+    if (omitted > 0)
+        blocks.push(`[... ${String(omitted)} more recalled item(s) omitted ...]`);
+    return blocks.join("\n\n");
+}
+export function fuseReciprocalRank(signals, limit) {
+    const byId = new Map();
+    for (const ranked of signals) {
+        ranked.forEach((candidate, rank) => {
+            const key = candidate.id.toString();
+            const contribution = 1 / (60 + rank);
+            const held = byId.get(key);
+            const signal = {
+                strategy: candidate.signals[0]?.strategy ?? RecallStrategy.Auto,
+                rank,
+                ...(candidate.score !== undefined ? { score: candidate.score } : {})
+            };
+            byId.set(key, held === undefined
+                ? { ...candidate, score: contribution, signals: [signal] }
+                : {
+                    ...held,
+                    score: (held.score ?? 0) + contribution,
+                    signals: [...held.signals, signal]
+                });
+        });
+    }
+    return [...byId.values()]
+        .sort((left, right) => (right.score ?? 0) - (left.score ?? 0))
+        .slice(0, limit);
+}
+export const ZERO_CONVERSATION = ConversationId.parse("00000000000000000000000000");
+//# sourceMappingURL=types.js.map