@smithers-orchestrator/memory 0.16.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 William Cory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@smithers-orchestrator/memory",
+  "version": "0.16.0",
+  "description": "Persistent and semantic memory services for Smithers",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./store": {
+      "types": "./src/index.d.ts",
+      "import": "./src/store/index.js",
+      "default": "./src/store/index.js"
+    },
+    "./*": {
+      "types": "./src/index.d.ts",
+      "import": "./src/*.js",
+      "default": "./src/*.js"
+    }
+  },
+  "files": [
+    "src/"
+  ],
+  "dependencies": {
+    "drizzle-orm": "^0.45.1",
+    "effect": "^3.21.0",
+    "zod": "^4.3.6",
+    "@smithers-orchestrator/db": "0.16.0",
+    "@smithers-orchestrator/driver": "0.16.0",
+    "@smithers-orchestrator/errors": "0.16.0",
+    "@smithers-orchestrator/observability": "0.16.0",
+    "@smithers-orchestrator/scheduler": "0.16.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "~5.9.3"
+  },
+  "scripts": {
+    "build": "tsup --dts-only",
+    "test": "bun test tests",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/MemoryFact.ts

@@ -0,0 +1,9 @@
+export type MemoryFact = {
+  namespace: string;
+  key: string;
+  valueJson: string;
+  schemaSig?: string | null;
+  createdAtMs: number;
+  updatedAtMs: number;
+  ttlMs?: number | null;
+};

package/src/MemoryLayerConfig.ts

@@ -0,0 +1,5 @@
+import type { BunSQLiteDatabase } from "drizzle-orm/bun-sqlite";
+
+export type MemoryLayerConfig = {
+  db: BunSQLiteDatabase<Record<string, unknown>>;
+};

package/src/MemoryMessage.ts

@@ -0,0 +1,9 @@
+export type MemoryMessage = {
+  id: string;
+  threadId: string;
+  role: string;
+  contentJson: string;
+  runId?: string | null;
+  nodeId?: string | null;
+  createdAtMs: number;
+};

package/src/MemoryNamespace.ts

@@ -0,0 +1,6 @@
+import type { MemoryNamespaceKind } from "./MemoryNamespaceKind";
+
+export type MemoryNamespace = {
+  kind: MemoryNamespaceKind;
+  id: string;
+};

package/src/MemoryNamespaceKind.ts

@@ -0,0 +1 @@
+export type MemoryNamespaceKind = "workflow" | "agent" | "user" | "global";

package/src/MemoryProcessor.js

@@ -0,0 +1,5 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./MemoryProcessor.ts").MemoryProcessor} MemoryProcessor */
+// @smithers-type-exports-end
+
+import { Effect } from "effect";

package/src/MemoryProcessor.ts

@@ -0,0 +1,9 @@
+import type { Effect } from "effect";
+import type { SmithersError } from "@smithers-orchestrator/errors";
+import type { MemoryStore } from "./store/MemoryStore";
+
+export type MemoryProcessor = {
+  name: string;
+  process: (store: MemoryStore) => Promise<void>;
+  processEffect: (store: MemoryStore) => Effect.Effect<void, SmithersError>;
+};

package/src/MemoryProcessorConfig.ts

@@ -0,0 +1,3 @@
+export type MemoryProcessorConfig = {
+  processors?: string[];
+};

package/src/MemoryService.js

@@ -0,0 +1,10 @@
+import { Context } from "effect";
+/** @typedef {import("./MemoryServiceApi.ts").MemoryServiceApi} MemoryServiceApi */
+
+const MemoryServiceBase =
+  /** @type {Context.TagClass<MemoryService, "MemoryService", MemoryServiceApi>} */ (
+    /** @type {unknown} */ (Context.Tag("MemoryService")())
+  );
+
+export class MemoryService extends MemoryServiceBase {
+}

package/src/MemoryServiceApi.js

@@ -0,0 +1,5 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./MemoryServiceApi.ts").MemoryServiceApi} MemoryServiceApi */
+// @smithers-type-exports-end
+
+import { Effect } from "effect";

package/src/MemoryServiceApi.ts

@@ -0,0 +1,49 @@
+import type { Effect } from "effect";
+import type { SmithersError } from "@smithers-orchestrator/errors";
+import type { MemoryNamespace } from "./MemoryNamespace";
+import type { MemoryFact } from "./MemoryFact";
+import type { MemoryThread } from "./MemoryThread";
+import type { MemoryMessage } from "./MemoryMessage";
+import type { MemoryStore } from "./store/MemoryStore";
+
+export type MemoryServiceApi = {
+  readonly getFact: (
+    ns: MemoryNamespace,
+    key: string,
+  ) => Effect.Effect<MemoryFact | undefined, SmithersError>;
+  readonly setFact: (
+    ns: MemoryNamespace,
+    key: string,
+    value: unknown,
+    ttlMs?: number,
+  ) => Effect.Effect<void, SmithersError>;
+  readonly deleteFact: (
+    ns: MemoryNamespace,
+    key: string,
+  ) => Effect.Effect<void, SmithersError>;
+  readonly listFacts: (
+    ns: MemoryNamespace,
+  ) => Effect.Effect<MemoryFact[], SmithersError>;
+  readonly createThread: (
+    ns: MemoryNamespace,
+    title?: string,
+  ) => Effect.Effect<MemoryThread, SmithersError>;
+  readonly getThread: (
+    threadId: string,
+  ) => Effect.Effect<MemoryThread | undefined, SmithersError>;
+  readonly deleteThread: (
+    threadId: string,
+  ) => Effect.Effect<void, SmithersError>;
+  readonly saveMessage: (
+    msg: Omit<MemoryMessage, "createdAtMs"> & { createdAtMs?: number },
+  ) => Effect.Effect<void, SmithersError>;
+  readonly listMessages: (
+    threadId: string,
+    limit?: number,
+  ) => Effect.Effect<MemoryMessage[], SmithersError>;
+  readonly countMessages: (
+    threadId: string,
+  ) => Effect.Effect<number, SmithersError>;
+  readonly deleteExpiredFacts: () => Effect.Effect<number, SmithersError>;
+  readonly store: MemoryStore;
+};

package/src/MemoryThread.ts

@@ -0,0 +1,8 @@
+export type MemoryThread = {
+  threadId: string;
+  namespace: string;
+  title?: string | null;
+  metadataJson?: string | null;
+  createdAtMs: number;
+  updatedAtMs: number;
+};

package/src/MessageHistoryConfig.ts

@@ -0,0 +1,4 @@
+export type MessageHistoryConfig = {
+  lastMessages?: number;
+  threadId?: string;
+};

package/src/SemanticRecallConfig.ts

@@ -0,0 +1,7 @@
+import type { MemoryNamespace } from "./MemoryNamespace";
+
+export type SemanticRecallConfig = {
+  topK?: number;
+  namespace?: MemoryNamespace;
+  similarityThreshold?: number;
+};

package/src/Summarizer.js

@@ -0,0 +1,26 @@
+import { Effect } from "effect";
+/** @typedef {import("./MemoryProcessor.ts").MemoryProcessor} MemoryProcessor */
+
+/**
+ * @param {{ run: (prompt: string) => Promise<any> }} agent
+ * @returns {MemoryProcessor}
+ */
+export function Summarizer(agent) {
+    /**
+   * @param {MemoryStore} store
+   * @returns {Effect.Effect<void, SmithersError>}
+   */
+    function processEffect(store) {
+        return Effect.gen(function* () {
+            // Summarizer operates on a specific thread's messages, compressing
+            // older messages into a summary. Without a thread context, it logs
+            // and returns. This is a structural placeholder.
+            yield* Effect.logInfo("Summarizer: configured — operates at thread level");
+        }).pipe(Effect.annotateLogs({ processor: "Summarizer" }), Effect.withLogSpan("memory:processor:summarizer"));
+    }
+    return {
+        name: "Summarizer",
+        process: (store) => Effect.runPromise(processEffect(store)),
+        processEffect,
+    };
+}

package/src/TaskMemoryConfig.ts

@@ -0,0 +1,15 @@
+import type { MemoryNamespace } from "./MemoryNamespace";
+
+export type TaskMemoryConfig = {
+  namespace?: string | MemoryNamespace;
+  recall?: {
+    namespace?: MemoryNamespace;
+    query?: string;
+    topK?: number;
+  };
+  remember?: {
+    namespace?: MemoryNamespace;
+    key?: string;
+  };
+  threadId?: string;
+};

package/src/TokenLimiter.js

@@ -0,0 +1,29 @@
+import { Effect } from "effect";
+/** @typedef {import("./MemoryProcessor.ts").MemoryProcessor} MemoryProcessor */
+
+/**
+ * @param {number} maxTokens
+ * @returns {MemoryProcessor}
+ */
+export function TokenLimiter(maxTokens) {
+    // Rough approximation: 1 token ~= 4 characters
+    const charBudget = maxTokens * 4;
+    /**
+   * @param {MemoryStore} store
+   * @returns {Effect.Effect<void, SmithersError>}
+   */
+    function processEffect(store) {
+        return Effect.gen(function* () {
+            // Token limiter operates at the thread level; without a specific thread
+            // context it logs and returns. In practice, this processor is invoked
+            // with a store that wraps a specific thread. For now, this is a no-op
+            // placeholder that documents the intended behaviour.
+            yield* Effect.logInfo(`TokenLimiter: configured for ${maxTokens} tokens (${charBudget} chars) — operates at thread level`);
+        }).pipe(Effect.annotateLogs({ processor: "TokenLimiter", maxTokens }), Effect.withLogSpan("memory:processor:token-limiter"));
+    }
+    return {
+        name: "TokenLimiter",
+        process: (store) => Effect.runPromise(processEffect(store)),
+        processEffect,
+    };
+}

package/src/TtlGarbageCollector.js

@@ -0,0 +1,23 @@
+import { Effect } from "effect";
+/** @typedef {import("./MemoryProcessor.ts").MemoryProcessor} MemoryProcessor */
+
+/**
+ * @returns {MemoryProcessor}
+ */
+export function TtlGarbageCollector() {
+    /**
+   * @param {MemoryStore} store
+   * @returns {Effect.Effect<void, SmithersError>}
+   */
+    function processEffect(store) {
+        return Effect.gen(function* () {
+            const deleted = yield* store.deleteExpiredFactsEffect();
+            yield* Effect.logInfo(`TtlGarbageCollector: deleted ${deleted} expired facts`);
+        }).pipe(Effect.annotateLogs({ processor: "TtlGarbageCollector" }), Effect.withLogSpan("memory:processor:ttl-gc"));
+    }
+    return {
+        name: "TtlGarbageCollector",
+        process: (store) => Effect.runPromise(processEffect(store)),
+        processEffect,
+    };
+}

package/src/WorkingMemoryConfig.ts

@@ -0,0 +1,10 @@
+import type { z } from "zod";
+import type { MemoryNamespace } from "./MemoryNamespace";
+
+export type WorkingMemoryConfig<
+  T extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>,
+> = {
+  schema?: T;
+  namespace: MemoryNamespace;
+  ttlMs?: number;
+};

package/src/createMemoryLayer.js

@@ -0,0 +1,30 @@
+import { Effect, Layer } from "effect";
+import { createMemoryStoreLayer } from "./store/createMemoryStoreLayer.js";
+import { MemoryStoreService } from "./store/MemoryStoreService.js";
+import { MemoryService } from "./MemoryService.js";
+/** @typedef {import("./MemoryLayerConfig.ts").MemoryLayerConfig} MemoryLayerConfig */
+
+/**
+ * @param {MemoryLayerConfig} config
+ * @returns {Layer.Layer<MemoryService, never, never>}
+ */
+export function createMemoryLayer(config) {
+    return Layer.effect(MemoryService, Effect.map(MemoryStoreService, (store) => ({
+        // Working memory
+        getFact: (ns, key) => store.getFactEffect(ns, key),
+        setFact: (ns, key, value, ttlMs) => store.setFactEffect(ns, key, value, ttlMs),
+        deleteFact: (ns, key) => store.deleteFactEffect(ns, key),
+        listFacts: (ns) => store.listFactsEffect(ns),
+        // Threads & messages
+        createThread: (ns, title) => store.createThreadEffect(ns, title),
+        getThread: (threadId) => store.getThreadEffect(threadId),
+        deleteThread: (threadId) => store.deleteThreadEffect(threadId),
+        saveMessage: (msg) => store.saveMessageEffect(msg),
+        listMessages: (threadId, limit) => store.listMessagesEffect(threadId, limit),
+        countMessages: (threadId) => store.countMessagesEffect(threadId),
+        // Maintenance
+        deleteExpiredFacts: () => store.deleteExpiredFactsEffect(),
+        // Access underlying store
+        store,
+    }))).pipe(Layer.provide(createMemoryStoreLayer(config.db)));
+}