@batonfx/memory 0.4.4 → 0.6.1

package/README.md

@@ -1,5 +1,87 @@
 # `@batonfx/memory`
 
-Non-durable memory implementations for Baton agents.
+Focused composition guide for Baton's non-durable memory implementations.
 
-See the [Baton documentation](https://github.com/In-Time-Tec/batonfx#readme) for installation, examples, and API guidance.
+## Install
+
+```sh
+bun add effect @batonfx/core @batonfx/memory
+```
+
+## Imports
+
+```ts
+import { Memory } from "@batonfx/core"
+import { WorkingMemory, VectorStore } from "@batonfx/memory"
+```
+
+## Layer graph
+
+```text
+WorkingMemory.layer({ maxMessages: 4 })
+└─ provides Memory.Memory
+   ├─ remember transcript by Memory.Key
+   └─ recall bounded recent messages
+```
+
+## Runnable program
+
+Checked source: [`../../examples/package-composition-guides/src/memory.ts`](../../examples/package-composition-guides/src/memory.ts)
+
+```ts
+import { Console, Effect } from "effect"
+import { Prompt } from "effect/unstable/ai"
+import { Memory } from "@batonfx/core"
+import { WorkingMemory } from "@batonfx/memory"
+
+const key: Memory.Key = { agent: "assistant", subject: "user-42" }
+const text = (value: string) => Prompt.makePart("text", { text: value })
+const message = (role: "user" | "assistant", value: string) => Prompt.makeMessage(role, { content: [text(value)] })
+
+const program = Memory.Memory.use((memory) =>
+  Effect.gen(function* () {
+    yield* memory.remember({
+      key,
+      turn: 0,
+      terminal: true,
+      transcript: Prompt.fromMessages([message("user", "My name is Ada."), message("assistant", "Hello Ada.")]),
+    })
+    const recalled = yield* memory.recall({
+      key,
+      turn: 0,
+      prompt: Prompt.fromMessages([message("user", "What do you remember?")]),
+    })
+    yield* Console.log(`recalled ${recalled.length} messages`)
+  }),
+).pipe(Effect.provide(WorkingMemory.layer({ maxMessages: 4 })))
+
+await Effect.runPromise(program)
+```
+
+Run `bun examples/package-composition-guides/src/memory.ts`.
+
+## Errors, requirements, and resources
+
+Before provisioning, the program requires `Memory.Memory` and can fail with schema-backed `MemoryError`; `WorkingMemory.layer` discharges the requirement, while retaining that declared production error channel. It succeeds with `void`. The in-process store owns no external resource and bounds each key's recent tail to four messages. Semantic memory additionally uses schema-backed `VectorStoreError`; embedding/vector failures map to `MemoryError`.
+
+## More
+
+- Current behavior: [Memory](../../docs/features/memory.md)
+- Deeper example: [memory chat](../../examples/memory-chat/)
+- `VectorStore.memoryLayer` remains an exact deprecated alias of canonical `VectorStore.layerMemory` through the stated pre-1.0 deprecation window; `combinedLayer` is unchanged.
+
+### Working-memory summaries
+
+Provide a dedicated summary model through Effect layer composition:
+
+```ts
+import { Layer } from "effect"
+import { WorkingMemory } from "@batonfx/memory"
+
+const memoryLayer = WorkingMemory.layer({
+  maxMessages: 20,
+  summarize: {},
+}).pipe(Layer.provide(WorkingMemory.summaryModelLayer.pipe(Layer.provide(modelLayer))))
+```
+
+The summary model is acquired once in `memoryLayer`'s owning scope and reused across overflows. The former `summarize: { model: modelLayer }` option remains supported but is deprecated; migrate by composing the model through `summaryModelLayer` as shown above.

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { Layer } from "effect";
 import { EmbeddingModel } from "effect/unstable/ai";
 import { Memory } from "@batonfx/core";
 import { VectorStore } from "./vector-store.js";
+import { SummaryModel } from "./working-memory.js";
 export * as SemanticRecall from "./semantic-recall.js";
 export * as VectorStore from "./vector-store.js";
 export * as WorkingMemory from "./working-memory.js";
@@ -11,4 +12,11 @@ export interface CombinedOptions {
     readonly semantic?: import("./semantic-recall.js").Options;
 }
 /** @experimental */
-export declare const combinedLayer: (options?: CombinedOptions) => Layer.Layer<Memory.Memory, never, VectorStore | EmbeddingModel.EmbeddingModel>;
+export interface CombinedComposedOptions {
+    readonly working: import("./working-memory.js").ComposedOptions;
+    readonly semantic?: import("./semantic-recall.js").Options;
+}
+/** @experimental */
+export declare function combinedLayer(options: CombinedComposedOptions): Layer.Layer<Memory.Memory, never, VectorStore | EmbeddingModel.EmbeddingModel | SummaryModel>;
+/** @experimental */
+export declare function combinedLayer(options?: CombinedOptions): Layer.Layer<Memory.Memory, never, VectorStore | EmbeddingModel.EmbeddingModel>;

package/dist/index.js

@@ -3,13 +3,14 @@ import { EmbeddingModel } from "effect/unstable/ai";
 import { Memory } from "@batonfx/core";
 import { makeSemanticRecall } from "./semantic-recall.js";
 import { VectorStore } from "./vector-store.js";
-import { makeWorkingMemory } from "./working-memory.js";
+import { makeWorkingMemory, SummaryModel } from "./working-memory.js";
 export * as SemanticRecall from "./semantic-recall.js";
 export * as VectorStore from "./vector-store.js";
 export * as WorkingMemory from "./working-memory.js";
-/** @experimental */
-export const combinedLayer = (options = {}) => 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));
-}));
+export function combinedLayer(options = {}) {
+    return Layer.effect(Memory.Memory, Effect.gen(function* () {
+        const working = options.working === undefined ? yield* makeWorkingMemory() : yield* makeWorkingMemory(options.working);
+        const semantic = yield* makeSemanticRecall(options.semantic);
+        return Memory.Memory.of(Memory.merge(working, semantic));
+    }));
+}

package/dist/semantic-recall.js

@@ -43,7 +43,7 @@ const finalExchangeText = (prompt) => {
 };
 const itemFromMatch = (match) => ({
     id: match.document.id,
-    parts: [textPart(match.document.text)],
+    content: [textPart(match.document.text)],
     metadata: { ...match.document.metadata, score: match.score },
 });
 /** @experimental */

package/dist/vector-store.d.ts

@@ -44,8 +44,13 @@ declare const VectorStore_base: Context.ServiceClass<VectorStore, "@batonfx/memo
 /** @experimental */
 export declare class VectorStore extends VectorStore_base {
 }
-/** @experimental */
-export declare const memoryLayer: Layer.Layer<VectorStore>;
+/** @experimental Ref-backed non-durable vector store. */
+export declare const layerMemory: Layer.Layer<VectorStore>;
+/**
+ * @experimental
+ * @deprecated Use {@link layerMemory}. This alias will not be removed before 1.0.0 and only in a separately planned major release.
+ */
+export declare const memoryLayer: typeof layerMemory;
 /** @experimental */
 export declare const testLayer: (implementation: Interface) => Layer.Layer<VectorStore>;
 export {};

package/dist/vector-store.js

@@ -71,7 +71,12 @@ const make = Ref.make(HashMap.empty()).pipe(Effect.map((documents) => ({
         return input.id === undefined ? false : document.id !== input.id;
     })),
 })));
-/** @experimental */
-export const memoryLayer = Layer.effect(VectorStore, make.pipe(Effect.map(VectorStore.of)));
+/** @experimental Ref-backed non-durable vector store. */
+export const layerMemory = Layer.effect(VectorStore, make.pipe(Effect.map(VectorStore.of)));
+/**
+ * @experimental
+ * @deprecated Use {@link layerMemory}. This alias will not be removed before 1.0.0 and only in a separately planned major release.
+ */
+export const memoryLayer = layerMemory;
 /** @experimental */
 export const testLayer = (implementation) => Layer.succeed(VectorStore, VectorStore.of(implementation));

package/dist/working-memory.d.ts

@@ -1,8 +1,9 @@
-import { Effect, Layer } from "effect";
+import { Context, Effect, Layer, Scope } from "effect";
 import { LanguageModel } from "effect/unstable/ai";
 import { Memory } from "@batonfx/core";
 /** @experimental */
 export interface SummarizeOptions {
+    /** @deprecated Provide `SummaryModel` through Effect composition instead. */
     readonly model: Layer.Layer<LanguageModel.LanguageModel>;
     readonly prompt?: string;
 }
@@ -12,8 +13,34 @@ export interface Options {
     readonly summarize?: SummarizeOptions;
 }
 /** @experimental */
-export declare const make: (options?: Options) => Effect.Effect<Memory.Interface>;
+export interface ComposedOptions {
+    readonly maxMessages?: number;
+    readonly summarize: {
+        readonly model?: never;
+        readonly prompt?: string;
+    };
+}
+declare const SummaryModel_base: Context.ServiceClass<SummaryModel, "@batonfx/memory/working-memory/SummaryModel", LanguageModel.Service>;
+/** @experimental */
+export declare class SummaryModel extends SummaryModel_base {
+}
+/** @experimental */
+export declare const summaryModelLayer: Layer.Layer<SummaryModel, never, LanguageModel.LanguageModel>;
+type WithoutSummaryOptions = Options & {
+    readonly summarize?: undefined;
+};
+/** @experimental */
+export declare function make(options: ComposedOptions): Effect.Effect<Memory.Interface, never, SummaryModel>;
+/** @experimental */
+export declare function make(options?: WithoutSummaryOptions): Effect.Effect<Memory.Interface>;
+/** @experimental */
+export declare function make(options: Options): Effect.Effect<Memory.Interface, never, Scope.Scope>;
+/** @experimental */
+export declare function make(options: Options | ComposedOptions): Effect.Effect<Memory.Interface, never, SummaryModel | Scope.Scope>;
 /** @experimental */
 export declare const makeWorkingMemory: typeof make;
 /** @experimental */
-export declare const layer: (options?: Options) => Layer.Layer<Memory.Memory>;
+export declare function layer(options: ComposedOptions): Layer.Layer<Memory.Memory, never, SummaryModel>;
+/** @experimental */
+export declare function layer(options?: Options): Layer.Layer<Memory.Memory>;
+export {};

package/dist/working-memory.js

@@ -1,6 +1,11 @@
-import { Effect, HashMap, Layer, Ref } from "effect";
+import { Context, Effect, HashMap, Layer, Scope, SynchronizedRef } from "effect";
 import { LanguageModel, Prompt, Toolkit } from "effect/unstable/ai";
 import { Memory } from "@batonfx/core";
+/** @experimental */
+export class SummaryModel extends Context.Service()("@batonfx/memory/working-memory/SummaryModel") {
+}
+/** @experimental */
+export const summaryModelLayer = Layer.effect(SummaryModel, LanguageModel.LanguageModel);
 const emptyState = {
     recent: [],
     counter: 0,
@@ -59,85 +64,93 @@ const renderSummaryPrompt = (prompt, summary, overflow) => [
     `New messages:\n${overflow.map(formatItem).join("\n")}`,
     "Return only the updated summary.",
 ].join("\n\n");
-const summarizeOverflow = (options, summary, overflow) => Effect.scoped(Layer.build(options.model).pipe(Effect.flatMap((context) => 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 summarizeOverflow = (model, prompt, summary, overflow) => model
+    .generateText({
+    prompt: renderSummaryPrompt(prompt ?? defaultSummaryPrompt, summary, overflow),
+    toolkit: Toolkit.empty,
+    toolChoice: "none",
+})
+    .pipe(Effect.map((response) => {
     const text = response.text.trim();
     return text.length === 0 ? summary : text;
-}).pipe(Effect.provide(context))), Effect.mapError(memoryError)));
+}), Effect.mapError(memoryError));
+const resolveSummaryModel = (options) => options.summarize === undefined
+    ? Effect.void
+    : "model" in options.summarize
+        ? Layer.build(options.summarize.model).pipe(Effect.map((context) => Context.get(context, LanguageModel.LanguageModel)))
+        : SummaryModel;
 const recallItems = (state) => [
     ...(state.summary === undefined
         ? []
         : [
             {
                 id: "working-summary",
-                parts: [textPart(`<working-memory-summary>\n${state.summary}\n</working-memory-summary>`)],
+                content: [textPart(`<working-memory-summary>\n${state.summary}\n</working-memory-summary>`)],
             },
         ]),
-    ...state.recent.map((item) => ({ id: item.id, parts: [textPart(formatItem(item))] })),
+    ...state.recent.map((item) => ({ id: item.id, content: [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
+export function make(options = {}) {
+    return Effect.gen(function* () {
+        const summaryModel = yield* resolveSummaryModel(options);
+        const states = yield* SynchronizedRef.make(HashMap.empty());
+        const maxMessages = Math.max(0, Math.floor(options.maxMessages ?? 20));
+        return {
+            recall: (input) => SynchronizedRef.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 SynchronizedRef.updateEffect(states, (current) => Effect.gen(function* () {
+                    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 current;
+                    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
-                        : yield* summarizeOverflow(options.summarize, existing.summary, trimmed.overflow);
+                        : summaryModel === undefined
+                            ? existing.summary
+                            : yield* summarizeOverflow(summaryModel, options.summarize?.prompt, existing.summary, trimmed.overflow);
+                    const nextState = {
+                        recent: trimmed.recent,
+                        counter,
+                        ...(summary === undefined ? {} : { summary }),
+                    };
+                    return HashMap.set(current, id, nextState);
+                }));
+            },
+            forget: (input) => SynchronizedRef.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: trimmed.recent,
-                    counter,
+                    recent,
+                    counter: existing.value.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);
-        }),
-    };
-}));
+                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)));
+export function layer(options = {}) {
+    return Layer.effect(Memory.Memory, make(options).pipe(Effect.map(Memory.Memory.of)));
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@batonfx/memory",
-  "version": "0.4.4",
+  "version": "0.6.1",
   "private": false,
   "type": "module",
   "exports": {
@@ -17,11 +17,11 @@
     "typecheck": "bun tsc --noEmit"
   },
   "dependencies": {
-    "@batonfx/core": "0.4.4",
-    "effect": "4.0.0-beta.93"
+    "@batonfx/core": "0.6.1",
+    "effect": "4.0.0-beta.98"
   },
   "devDependencies": {
-    "@effect/vitest": "4.0.0-beta.93",
+    "@effect/vitest": "4.0.0-beta.98",
     "@types/bun": "1.3.13",
     "typescript": "7.0.2",
     "vitest": "4.0.16"