@crewhaus/tool-memory 0.1.0

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@crewhaus/tool-memory",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "M4.2 — Remember and Recall tools wrapping @crewhaus/memory-store for cross-session persistent memory.",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/memory-store": "0.0.0",
+    "@crewhaus/tool-builder": "0.0.0",
+    "@crewhaus/tool-catalog": "0.0.0",
+    "zod": "^3.23.8"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/tool-memory"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/tool-memory#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,96 @@
+/**
+ * Tests for the Remember + Recall tools. The underlying memory-store
+ * is tested in @crewhaus/memory-store; here we focus on the tool
+ * surface (schemas, execute outputs, flags).
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createMemoryTools } from "./index";
+
+let tmp: string;
+
+beforeEach(() => {
+  tmp = mkdtempSync(join(tmpdir(), "tool-memory-"));
+});
+
+afterEach(() => {
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+describe("createMemoryTools — Remember", () => {
+  test("returns a destructive tool named 'Remember'", () => {
+    const { remember } = createMemoryTools({ specName: "s", rootDir: tmp });
+    expect(remember.name).toBe("Remember");
+    expect(remember.destructive).toBe(true);
+    expect(remember.readOnly).toBe(false);
+  });
+
+  test("execute persists the memory and returns confirmation", async () => {
+    const { remember, store } = createMemoryTools({ specName: "s", rootDir: tmp });
+    const result = await remember.execute({
+      text: "the user's birthday is March 15",
+    });
+    expect(result).toContain("remembered (mem_");
+    expect(result).toContain("the user's birthday is March 15");
+    expect(await store.size()).toBe(1);
+  });
+
+  test("execute renders tags as a suffix in the confirmation", async () => {
+    const { remember } = createMemoryTools({ specName: "s", rootDir: tmp });
+    const result = await remember.execute({
+      text: "anniversary on June 1",
+      tags: ["personal", "important"],
+    });
+    expect(result).toContain("[personal, important]");
+  });
+
+  test("schema validates text presence (zod rejects empty)", () => {
+    const { remember } = createMemoryTools({ specName: "s", rootDir: tmp });
+    expect(() => remember.inputSchema.parse({ text: "" })).toThrow();
+  });
+});
+
+describe("createMemoryTools — Recall", () => {
+  test("returns a read-only tool named 'Recall'", () => {
+    const { recall } = createMemoryTools({ specName: "s", rootDir: tmp });
+    expect(recall.name).toBe("Recall");
+    expect(recall.readOnly).toBe(true);
+    expect(recall.destructive).toBe(false);
+  });
+
+  test("recall returns 'no memories' message when empty", async () => {
+    const { recall } = createMemoryTools({ specName: "s", rootDir: tmp });
+    const out = await recall.execute({ query: "anything" });
+    expect(out).toContain("no memories matched");
+    expect(out).toContain("store size: 0");
+  });
+
+  test("recall lists matches ordered by score", async () => {
+    const { remember, recall } = createMemoryTools({ specName: "s", rootDir: tmp });
+    await remember.execute({ text: "the user prefers TypeScript" });
+    await remember.execute({ text: "we discussed Python yesterday" });
+    await remember.execute({ text: "TypeScript is the user's daily driver" });
+    const out = await recall.execute({ query: "TypeScript" });
+    expect(out).toContain("memory match(es)");
+    expect(out).toContain("TypeScript");
+    expect(out).not.toContain("Python");
+  });
+
+  test("k parameter caps the listed matches", async () => {
+    const { remember, recall } = createMemoryTools({ specName: "s", rootDir: tmp });
+    for (let i = 0; i < 5; i++) {
+      await remember.execute({ text: `note ${i} about coffee` });
+    }
+    const out = await recall.execute({ query: "coffee", k: 2 });
+    expect((out.match(/•/g) ?? []).length).toBe(2);
+  });
+
+  test("recall schema validates k bounds", () => {
+    const { recall } = createMemoryTools({ specName: "s", rootDir: tmp });
+    expect(() => recall.inputSchema.parse({ query: "q", k: 0 })).toThrow();
+    expect(() => recall.inputSchema.parse({ query: "q", k: 51 })).toThrow();
+    expect(() => recall.inputSchema.parse({ query: "q", k: 5 })).not.toThrow();
+  });
+});

package/src/index.ts

@@ -0,0 +1,103 @@
+/**
+ * Catalog R3 — tool-memory. Exposes `Remember` and `Recall` tools that
+ * wrap @crewhaus/memory-store for cross-session persistent memory
+ * (M4.2 of the heavy-hitter plan).
+ *
+ * Each tool is bound to a specific spec name at construction time so
+ * one process can run multiple specs without their memories cross-
+ * contaminating. The spec name is what `runChatLoop` passes as
+ * `sessionName`; tool-catalog can supply it via factory functions
+ * (`createMemoryTools(specName)`) or downstream consumers can wire
+ * it through their own catalog initialization.
+ *
+ * Pillar 3: memory writes carry `origin: "user"` semantics (the user
+ * is the one who decided what to remember). The runtime's session-
+ * start hook reads recalled memories with the same origin so cached
+ * verdicts apply correctly. No cross-origin lateral movement: a
+ * memory written by one user cannot influence another user's session.
+ */
+import { type MemoryStore, createMemoryStore } from "@crewhaus/memory-store";
+import { buildTool } from "@crewhaus/tool-builder";
+import type { RegisteredTool } from "@crewhaus/tool-catalog";
+import { z } from "zod";
+
+export type CreateMemoryToolsOptions = {
+  readonly specName: string;
+  readonly rootDir?: string;
+  /** Inject a custom store implementation for tests. */
+  readonly store?: MemoryStore;
+};
+
+export type MemoryToolBundle = {
+  readonly remember: RegisteredTool;
+  readonly recall: RegisteredTool;
+  /** Exposed for direct inspection (tests, /clear-style ops). */
+  readonly store: MemoryStore;
+};
+
+const rememberSchema = z.object({
+  text: z.string().min(1).describe("The fact to remember. One short, self-contained sentence."),
+  tags: z
+    .array(z.string().min(1))
+    .max(8)
+    .optional()
+    .describe("Optional tags for grouping (e.g. 'family', 'work', 'preference')."),
+});
+
+const recallSchema = z.object({
+  query: z
+    .string()
+    .min(1)
+    .describe("Text to search for. Returns the top-K matching memories ranked by relevance."),
+  k: z.number().int().min(1).max(50).optional().describe("Max results to return. Default 5."),
+});
+
+/**
+ * Construct the Remember + Recall tool pair bound to a spec's memory
+ * store. The caller is expected to add the returned tools to the
+ * runtime's tool catalog (e.g. `defaultCatalog.register(bundle.remember)`).
+ */
+export function createMemoryTools(opts: CreateMemoryToolsOptions): MemoryToolBundle {
+  const store: MemoryStore =
+    opts.store ??
+    createMemoryStore({
+      specName: opts.specName,
+      ...(opts.rootDir !== undefined ? { rootDir: opts.rootDir } : {}),
+    });
+
+  const remember: RegisteredTool = buildTool({
+    name: "Remember",
+    description:
+      "Store a fact for future sessions. Use sparingly — once a user mentions something they want you to remember (preferences, important dates, contact details, opinions), call this. The memory persists in `.crewhaus/memories/<spec>.jsonl` and is searchable via Recall.",
+    inputSchema: rememberSchema,
+    destructive: true, // writes to disk — gate behind permissions
+    execute: async (input) => {
+      const entry = await store.remember(input.text, input.tags ?? []);
+      const tagSuffix = entry.tags.length > 0 ? ` [${entry.tags.join(", ")}]` : "";
+      return `remembered (${entry.id})${tagSuffix}: ${entry.text}`;
+    },
+  });
+
+  const recall: RegisteredTool = buildTool({
+    name: "Recall",
+    description:
+      "Search prior memories for relevance to a query. Use at the start of a session, or whenever the user references something you might have stored. Returns up to K results ranked by BM25 relevance score, ordered most-relevant first.",
+    inputSchema: recallSchema,
+    readOnly: true,
+    execute: async (input) => {
+      const k = input.k ?? 5;
+      const results = await store.recall(input.query, k);
+      if (results.length === 0) {
+        return `no memories matched "${input.query}" (store size: ${await store.size()})`;
+      }
+      const lines = [`${results.length} memory match(es) for "${input.query}":`];
+      for (const r of results) {
+        const tagSuffix = r.entry.tags.length > 0 ? ` [${r.entry.tags.join(", ")}]` : "";
+        lines.push(`  • (${r.score.toFixed(2)}) ${r.entry.text}${tagSuffix}`);
+      }
+      return lines.join("\n");
+    },
+  });
+
+  return { remember, recall, store };
+}