@batonfx/memory 0.3.7 → 0.4.1

package/dist/semantic-recall.d.ts

@@ -0,0 +1,15 @@
+import { Effect, Layer } from "effect";
+import { EmbeddingModel } from "effect/unstable/ai";
+import { Memory } from "@batonfx/core";
+import { VectorStore } from "./vector-store.js";
+/** @experimental */
+export interface Options {
+    readonly limit?: number;
+    readonly minScore?: number;
+}
+/** @experimental */
+export declare const make: (options?: Options) => Effect.Effect<Memory.Interface, never, VectorStore | EmbeddingModel.EmbeddingModel>;
+/** @experimental */
+export declare const makeSemanticRecall: (options?: Options) => Effect.Effect<Memory.Interface, never, VectorStore | EmbeddingModel.EmbeddingModel>;
+/** @experimental */
+export declare const layer: (options?: Options) => Layer.Layer<Memory.Memory, never, VectorStore | EmbeddingModel.EmbeddingModel>;

package/dist/semantic-recall.js

@@ -0,0 +1,90 @@
+import { Effect, Layer, Ref } from "effect";
+import { EmbeddingModel, Prompt } from "effect/unstable/ai";
+import { Memory } from "@batonfx/core";
+import { VectorStore } from "./vector-store.js";
+const errorMessage = (error) => (error instanceof Error ? `${error.name}: ${error.message}` : String(error));
+const memoryError = (error) => new Memory.MemoryError({ message: errorMessage(error) });
+const textPart = (text) => Prompt.makePart("text", { text });
+const textFromParts = (parts) => parts
+    .filter((part) => part.type === "text")
+    .map((part) => part.text)
+    .join("");
+const userText = (prompt) => prompt.content
+    .filter((message) => message.role === "user")
+    .map((message) => textFromParts(message.content))
+    .filter((text) => text.length > 0)
+    .join("\n\n");
+const finalExchangeText = (prompt) => {
+    let assistant;
+    let assistantIndex = -1;
+    for (let index = prompt.content.length - 1; index >= 0; index -= 1) {
+        const message = prompt.content[index];
+        if (message?.role !== "assistant")
+            continue;
+        const text = textFromParts(message.content).trim();
+        if (text.length === 0)
+            continue;
+        assistant = text;
+        assistantIndex = index;
+        break;
+    }
+    if (assistant === undefined)
+        return undefined;
+    for (let index = assistantIndex - 1; index >= 0; index -= 1) {
+        const message = prompt.content[index];
+        if (message?.role !== "user")
+            continue;
+        const text = textFromParts(message.content).trim();
+        if (text.length === 0)
+            continue;
+        return `User: ${text}\nAssistant: ${assistant}`;
+    }
+    return undefined;
+};
+const itemFromMatch = (match) => ({
+    id: match.document.id,
+    parts: [textPart(match.document.text)],
+    metadata: { ...match.document.metadata, score: match.score },
+});
+/** @experimental */
+export const make = (options = {}) => Effect.gen(function* () {
+    const store = yield* VectorStore;
+    const embeddingModel = yield* EmbeddingModel.EmbeddingModel;
+    const counter = yield* Ref.make(0);
+    const limit = options.limit ?? 5;
+    return {
+        recall: (input) => {
+            const text = userText(input.prompt);
+            if (text.length === 0)
+                return Effect.succeed([]);
+            return embeddingModel.embed(text).pipe(Effect.mapError(memoryError), Effect.flatMap((embedding) => store
+                .query({
+                key: input.key,
+                embedding: embedding.vector,
+                limit,
+                ...(options.minScore === undefined ? {} : { minScore: options.minScore }),
+            })
+                .pipe(Effect.mapError(memoryError))), Effect.map((matches) => matches.map(itemFromMatch)));
+        },
+        remember: (input) => {
+            if (!input.terminal)
+                return Effect.void;
+            const text = finalExchangeText(input.transcript);
+            if (text === undefined)
+                return Effect.void;
+            return embeddingModel.embed(text).pipe(Effect.mapError(memoryError), Effect.flatMap((embedding) => Ref.modify(counter, (current) => [`semantic-${current + 1}`, current + 1]).pipe(Effect.flatMap((id) => store.upsert([
+                {
+                    id,
+                    key: input.key,
+                    text,
+                    embedding: embedding.vector,
+                },
+            ])))), Effect.mapError(memoryError));
+        },
+        forget: (input) => store.delete(input).pipe(Effect.mapError(memoryError)),
+    };
+});
+/** @experimental */
+export const makeSemanticRecall = make;
+/** @experimental */
+export const layer = (options = {}) => Layer.effect(Memory.Memory, make(options).pipe(Effect.map(Memory.Memory.of)));

package/dist/vector-store.d.ts

@@ -0,0 +1,51 @@
+import { Context, Effect, Layer, Schema } from "effect";
+import { Memory } from "@batonfx/core";
+/** @experimental */
+export interface Document {
+    readonly id: string;
+    readonly key: Memory.Key;
+    readonly text: string;
+    readonly metadata?: Memory.Metadata;
+}
+/** @experimental */
+export interface Embedded extends Document {
+    readonly embedding: ReadonlyArray<number>;
+}
+/** @experimental */
+export interface Match {
+    readonly document: Embedded;
+    readonly score: number;
+}
+/** @experimental */
+export interface Query {
+    readonly key: Memory.Key;
+    readonly embedding: ReadonlyArray<number>;
+    readonly limit: number;
+    readonly minScore?: number;
+}
+/** @experimental */
+export interface DeleteInput {
+    readonly key: Memory.Key;
+    readonly id?: string | undefined;
+}
+declare const VectorStoreError_base: Schema.Class<VectorStoreError, Schema.TaggedStruct<"@batonfx/memory/VectorStoreError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** @experimental */
+export declare class VectorStoreError extends VectorStoreError_base {
+}
+/** @experimental */
+export interface Interface {
+    readonly upsert: (documents: ReadonlyArray<Embedded>) => Effect.Effect<void, VectorStoreError>;
+    readonly query: (query: Query) => Effect.Effect<ReadonlyArray<Match>, VectorStoreError>;
+    readonly delete: (input: DeleteInput) => Effect.Effect<void, VectorStoreError>;
+}
+declare const VectorStore_base: Context.ServiceClass<VectorStore, "@batonfx/memory/VectorStore", Interface>;
+/** @experimental */
+export declare class VectorStore extends VectorStore_base {
+}
+/** @experimental */
+export declare const memoryLayer: Layer.Layer<VectorStore>;
+/** @experimental */
+export declare const testLayer: (implementation: Interface) => Layer.Layer<VectorStore>;
+export {};

package/dist/vector-store.js

@@ -0,0 +1,77 @@
+import { Context, Effect, HashMap, Layer, Ref, Schema } from "effect";
+import { Memory } from "@batonfx/core";
+/** @experimental */
+export class VectorStoreError extends Schema.TaggedErrorClass()("@batonfx/memory/VectorStoreError", {
+    message: Schema.String,
+}) {
+}
+/** @experimental */
+export class VectorStore extends Context.Service()("@batonfx/memory/VectorStore") {
+}
+const storageKey = (key, id) => JSON.stringify([key.agent, key.subject, id]);
+const sameKey = (left, right) => left.agent === right.agent && left.subject === right.subject;
+const validateVector = (label, vector) => {
+    const invalid = vector.find((value) => !Number.isFinite(value));
+    return invalid === undefined
+        ? Effect.void
+        : Effect.fail(new VectorStoreError({ message: `${label} contains a non-finite value` }));
+};
+const cosine = (left, right) => {
+    let dot = 0;
+    let leftMagnitude = 0;
+    let rightMagnitude = 0;
+    for (let index = 0; index < left.length; index += 1) {
+        const leftValue = left[index] ?? 0;
+        const rightValue = right[index] ?? 0;
+        dot += leftValue * rightValue;
+        leftMagnitude += leftValue * leftValue;
+        rightMagnitude += rightValue * rightValue;
+    }
+    if (leftMagnitude === 0 || rightMagnitude === 0)
+        return 0;
+    return dot / (Math.sqrt(leftMagnitude) * Math.sqrt(rightMagnitude));
+};
+const make = Ref.make(HashMap.empty()).pipe(Effect.map((documents) => ({
+    upsert: (nextDocuments) => Effect.gen(function* () {
+        for (const document of nextDocuments) {
+            yield* validateVector(`document ${document.id} embedding`, document.embedding);
+        }
+        yield* Ref.update(documents, (current) => {
+            let next = current;
+            for (const document of nextDocuments) {
+                next = HashMap.set(next, storageKey(document.key, document.id), document);
+            }
+            return next;
+        });
+    }),
+    query: (input) => Effect.gen(function* () {
+        if (input.limit <= 0)
+            return [];
+        yield* validateVector("query embedding", input.embedding);
+        const current = yield* Ref.get(documents);
+        const matches = [];
+        for (const [, document] of current) {
+            if (!sameKey(document.key, input.key))
+                continue;
+            if (document.embedding.length !== input.embedding.length) {
+                return yield* Effect.fail(new VectorStoreError({
+                    message: `document ${document.id} embedding dimension ${document.embedding.length} does not match query dimension ${input.embedding.length}`,
+                }));
+            }
+            const score = cosine(document.embedding, input.embedding);
+            if (input.minScore !== undefined && score < input.minScore)
+                continue;
+            matches.push({ document, score });
+        }
+        return matches.toSorted((left, right) => right.score - left.score).slice(0, input.limit);
+    }),
+    delete: (input) => Ref.update(documents, (current) => HashMap.filter(current, (document) => {
+        if (!sameKey(document.key, input.key))
+            return true;
+        return input.id === undefined ? false : document.id !== input.id;
+    })),
+})));
+/** @experimental */
+export const memoryLayer = Layer.effect(VectorStore, make.pipe(Effect.map(VectorStore.of)));
+/** @experimental */
+export const testLayer = (implementation) => Layer.succeed(VectorStore, VectorStore.of(implementation));

package/dist/working-memory.d.ts

@@ -0,0 +1,19 @@
+import { Effect, Layer } from "effect";
+import { LanguageModel } from "effect/unstable/ai";
+import { Memory } from "@batonfx/core";
+/** @experimental */
+export interface SummarizeOptions {
+    readonly model: Layer.Layer<LanguageModel.LanguageModel>;
+    readonly prompt?: string;
+}
+/** @experimental */
+export interface Options {
+    readonly maxMessages?: number;
+    readonly summarize?: SummarizeOptions;
+}
+/** @experimental */
+export declare const make: (options?: Options) => Effect.Effect<Memory.Interface>;
+/** @experimental */
+export declare const makeWorkingMemory: (options?: Options) => Effect.Effect<Memory.Interface>;
+/** @experimental */
+export declare const layer: (options?: Options) => Layer.Layer<Memory.Memory>;

package/dist/working-memory.js

@@ -0,0 +1,143 @@
+import { Effect, HashMap, Layer, Ref } from "effect";
+import { LanguageModel, Prompt, Toolkit } from "effect/unstable/ai";
+import { Memory } from "@batonfx/core";
+const emptyState = {
+    recent: [],
+    counter: 0,
+};
+const defaultSummaryPrompt = "Summarize the conversation memory while preserving stable user preferences and facts.";
+const errorMessage = (error) => (error instanceof Error ? `${error.name}: ${error.message}` : String(error));
+const memoryError = (error) => new Memory.MemoryError({ message: errorMessage(error) });
+const keyId = (key) => JSON.stringify([key.agent, key.subject]);
+const textPart = (text) => Prompt.makePart("text", { text });
+const textFromParts = (parts) => parts
+    .filter((part) => part.type === "text")
+    .map((part) => part.text)
+    .join("");
+const roleLabel = (role) => (role === "user" ? "User" : "Assistant");
+const formatItem = (item) => `${roleLabel(item.role)}: ${item.text}`;
+const normalize = (prompt) => prompt.content.flatMap((message) => {
+    if (message.role !== "user" && message.role !== "assistant")
+        return [];
+    const text = textFromParts(message.content).trim();
+    return text.length === 0 ? [] : [{ role: message.role, text }];
+});
+const sameItem = (left, right) => left.role === right.role && left.text === right.text;
+const appendStart = (recent, incoming) => {
+    if (recent.length === 0)
+        return 0;
+    for (let start = Math.max(0, incoming.length - recent.length); start >= 0; start -= 1) {
+        if (start + recent.length > incoming.length)
+            continue;
+        let matches = true;
+        for (let offset = 0; offset < recent.length; offset += 1) {
+            const stored = recent[offset];
+            const next = incoming[start + offset];
+            if (stored === undefined || next === undefined || !sameItem(stored, next)) {
+                matches = false;
+                break;
+            }
+        }
+        if (matches)
+            return start + recent.length;
+    }
+    return 0;
+};
+const trimToWindow = (items, maxMessages) => {
+    if (items.length <= maxMessages)
+        return { overflow: [], recent: items };
+    if (maxMessages === 0)
+        return { overflow: items, recent: [] };
+    return {
+        overflow: items.slice(0, items.length - maxMessages),
+        recent: items.slice(-maxMessages),
+    };
+};
+const renderSummaryPrompt = (prompt, summary, overflow) => [
+    prompt,
+    ...(summary === undefined ? [] : [`Existing summary:\n${summary}`]),
+    `New messages:\n${overflow.map(formatItem).join("\n")}`,
+    "Return only the updated summary.",
+].join("\n\n");
+const summarizeOverflow = (options, summary, overflow) => Effect.gen(function* () {
+    const model = yield* LanguageModel.LanguageModel;
+    const response = yield* model.generateText({
+        prompt: renderSummaryPrompt(options.prompt ?? defaultSummaryPrompt, summary, overflow),
+        toolkit: Toolkit.empty,
+        toolChoice: "none",
+    });
+    const text = response.text.trim();
+    return text.length === 0 ? summary : text;
+}).pipe(Effect.provide(options.model), Effect.mapError(memoryError));
+const recallItems = (state) => [
+    ...(state.summary === undefined
+        ? []
+        : [
+            {
+                id: "working-summary",
+                parts: [textPart(`<working-memory-summary>\n${state.summary}\n</working-memory-summary>`)],
+            },
+        ]),
+    ...state.recent.map((item) => ({ id: item.id, parts: [textPart(formatItem(item))] })),
+];
+/** @experimental */
+export const make = (options = {}) => Ref.make(HashMap.empty()).pipe(Effect.map((states) => {
+    const maxMessages = Math.max(0, Math.floor(options.maxMessages ?? 20));
+    return {
+        recall: (input) => Ref.get(states).pipe(Effect.map((current) => HashMap.get(current, keyId(input.key))), Effect.map((state) => (state._tag === "Some" ? recallItems(state.value) : []))),
+        remember: (input) => {
+            const incoming = normalize(input.transcript);
+            if (incoming.length === 0)
+                return Effect.void;
+            return Effect.gen(function* () {
+                const current = yield* Ref.get(states);
+                const id = keyId(input.key);
+                const existing = HashMap.get(current, id).pipe((option) => option._tag === "Some" ? option.value : emptyState);
+                const start = appendStart(existing.recent, incoming);
+                const appended = incoming.slice(start);
+                if (appended.length === 0)
+                    return;
+                let counter = existing.counter;
+                const stored = appended.map((item) => {
+                    counter += 1;
+                    return { id: `working-${counter}`, role: item.role, text: item.text };
+                });
+                const combined = [...existing.recent, ...stored];
+                const trimmed = trimToWindow(combined, maxMessages);
+                const summary = trimmed.overflow.length === 0
+                    ? existing.summary
+                    : options.summarize === undefined
+                        ? existing.summary
+                        : yield* summarizeOverflow(options.summarize, existing.summary, trimmed.overflow);
+                const nextState = {
+                    recent: trimmed.recent,
+                    counter,
+                    ...(summary === undefined ? {} : { summary }),
+                };
+                yield* Ref.update(states, HashMap.set(id, nextState));
+            });
+        },
+        forget: (input) => Ref.update(states, (current) => {
+            const id = keyId(input.key);
+            if (input.id === undefined)
+                return HashMap.remove(current, id);
+            const existing = HashMap.get(current, id);
+            if (existing._tag === "None")
+                return current;
+            const summary = input.id === "working-summary" ? undefined : existing.value.summary;
+            const recent = existing.value.recent.filter((item) => item.id !== input.id);
+            if (summary === undefined && recent.length === 0)
+                return HashMap.remove(current, id);
+            const nextState = {
+                recent,
+                counter: existing.value.counter,
+                ...(summary === undefined ? {} : { summary }),
+            };
+            return HashMap.set(current, id, nextState);
+        }),
+    };
+}));
+/** @experimental */
+export const makeWorkingMemory = make;
+/** @experimental */
+export const layer = (options = {}) => Layer.effect(Memory.Memory, make(options).pipe(Effect.map(Memory.Memory.of)));

package/package.json

@@ -1,20 +1,23 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@batonfx/memory",
-  "version": "0.3.7",
+  "version": "0.4.1",
   "private": false,
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
-    "build": "bun build ./src/index.ts --outdir dist --target bun --format esm",
+    "build": "rm -rf dist && bun tsc -p tsconfig.build.json",
     "lint": "bun --cwd ../.. oxlint packages/memory/src packages/memory/test",
     "test": "bun --cwd ../.. vitest run packages/memory/test --passWithNoTests",
     "typecheck": "bun tsc --noEmit"
   },
   "dependencies": {
-    "@batonfx/core": "0.3.7",
+    "@batonfx/core": "0.4.1",
     "effect": "4.0.0-beta.93"
   },
   "devDependencies": {
@@ -22,5 +25,27 @@
     "@types/bun": "1.3.13",
     "typescript": "5.8.2",
     "vitest": "4.0.16"
+  },
+  "description": "Non-durable memory implementations for Baton agents",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22",
+    "bun": ">=1.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/In-Time-Tec/batonfx.git",
+    "directory": "packages/memory"
+  },
+  "homepage": "https://github.com/In-Time-Tec/batonfx#readme",
+  "bugs": {
+    "url": "https://github.com/In-Time-Tec/batonfx/issues"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/.turbo/turbo-build.log

@@ -1,5 +0,0 @@
-$ bun build ./src/index.ts --outdir dist --target bun --format esm
-Bundled 176 modules in 350ms
-
-  index.js  1.1 MB  (entry point)
-

package/src/index.ts

@@ -1,29 +0,0 @@
-import { Effect, Layer } from "effect"
-import { EmbeddingModel } from "effect/unstable/ai"
-import { Memory } from "@batonfx/core"
-import { makeSemanticRecall } from "./semantic-recall"
-import { VectorStore } from "./vector-store"
-import { makeWorkingMemory } from "./working-memory"
-
-export * as SemanticRecall from "./semantic-recall"
-export * as VectorStore from "./vector-store"
-export * as WorkingMemory from "./working-memory"
-
-/** @experimental */
-export interface CombinedOptions {
-  readonly working?: import("./working-memory").Options
-  readonly semantic?: import("./semantic-recall").Options
-}
-
-/** @experimental */
-export const combinedLayer = (
-  options: CombinedOptions = {},
-): Layer.Layer<Memory.Memory, never, VectorStore | EmbeddingModel.EmbeddingModel> =>
-  Layer.effect(
-    Memory.Memory,
-    Effect.gen(function* () {
-      const working = yield* makeWorkingMemory(options.working)
-      const semantic = yield* makeSemanticRecall(options.semantic)
-      return Memory.Memory.of(Memory.merge(working, semantic))
-    }),
-  )

package/src/semantic-recall.ts

@@ -1,123 +0,0 @@
-import { Effect, Layer, Ref } from "effect"
-import { EmbeddingModel, Prompt } from "effect/unstable/ai"
-import { Memory } from "@batonfx/core"
-import { VectorStore } from "./vector-store"
-import type { Match } from "./vector-store"
-/** @experimental */
-export interface Options {
-  readonly limit?: number
-  readonly minScore?: number
-}
-
-const errorMessage = (error: unknown) => (error instanceof Error ? `${error.name}: ${error.message}` : String(error))
-
-const memoryError = (error: unknown): Memory.MemoryError => new Memory.MemoryError({ message: errorMessage(error) })
-
-const textPart = (text: string) => Prompt.makePart("text", { text })
-
-const textFromParts = (parts: ReadonlyArray<Prompt.Part>): string =>
-  parts
-    .filter((part): part is Prompt.TextPart => part.type === "text")
-    .map((part) => part.text)
-    .join("")
-
-const userText = (prompt: Prompt.Prompt): string =>
-  prompt.content
-    .filter((message): message is Prompt.UserMessage => message.role === "user")
-    .map((message) => textFromParts(message.content))
-    .filter((text) => text.length > 0)
-    .join("\n\n")
-
-const finalExchangeText = (prompt: Prompt.Prompt): string | undefined => {
-  let assistant: string | undefined
-  let assistantIndex = -1
-  for (let index = prompt.content.length - 1; index >= 0; index -= 1) {
-    const message = prompt.content[index]
-    if (message?.role !== "assistant") continue
-    const text = textFromParts(message.content).trim()
-    if (text.length === 0) continue
-    assistant = text
-    assistantIndex = index
-    break
-  }
-  if (assistant === undefined) return undefined
-  for (let index = assistantIndex - 1; index >= 0; index -= 1) {
-    const message = prompt.content[index]
-    if (message?.role !== "user") continue
-    const text = textFromParts(message.content).trim()
-    if (text.length === 0) continue
-    return `User: ${text}\nAssistant: ${assistant}`
-  }
-  return undefined
-}
-
-const itemFromMatch = (match: Match): Memory.Item => ({
-  id: match.document.id,
-  parts: [textPart(match.document.text)],
-  metadata: { ...match.document.metadata, score: match.score },
-})
-
-/** @experimental */
-export const make = (
-  options: Options = {},
-): Effect.Effect<Memory.Interface, never, VectorStore | EmbeddingModel.EmbeddingModel> =>
-  Effect.gen(function* () {
-    const store = yield* VectorStore
-    const embeddingModel = yield* EmbeddingModel.EmbeddingModel
-    const counter = yield* Ref.make(0)
-    const limit = options.limit ?? 5
-
-    return {
-      recall: (input) => {
-        const text = userText(input.prompt)
-        if (text.length === 0) return Effect.succeed([])
-        return embeddingModel.embed(text).pipe(
-          Effect.mapError(memoryError),
-          Effect.flatMap((embedding) =>
-            store
-              .query({
-                key: input.key,
-                embedding: embedding.vector,
-                limit,
-                ...(options.minScore === undefined ? {} : { minScore: options.minScore }),
-              })
-              .pipe(Effect.mapError(memoryError)),
-          ),
-          Effect.map((matches) => matches.map(itemFromMatch)),
-        )
-      },
-      remember: (input) => {
-        if (!input.terminal) return Effect.void
-        const text = finalExchangeText(input.transcript)
-        if (text === undefined) return Effect.void
-        return embeddingModel.embed(text).pipe(
-          Effect.mapError(memoryError),
-          Effect.flatMap((embedding) =>
-            Ref.modify(counter, (current) => [`semantic-${current + 1}`, current + 1]).pipe(
-              Effect.flatMap((id) =>
-                store.upsert([
-                  {
-                    id,
-                    key: input.key,
-                    text,
-                    embedding: embedding.vector,
-                  },
-                ]),
-              ),
-            ),
-          ),
-          Effect.mapError(memoryError),
-        )
-      },
-      forget: (input) => store.delete(input).pipe(Effect.mapError(memoryError)),
-    }
-  })
-
-/** @experimental */
-export const makeSemanticRecall = make
-
-/** @experimental */
-export const layer = (
-  options: Options = {},
-): Layer.Layer<Memory.Memory, never, VectorStore | EmbeddingModel.EmbeddingModel> =>
-  Layer.effect(Memory.Memory, make(options).pipe(Effect.map(Memory.Memory.of)))