feat(agent-memory): Phase 0 — scaffold @betterdb/agent-memory

packages/agent-memory/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@betterdb/agent-memory",
+  "version": "0.1.0",
+  "description": "Standalone agent memory: agent-cache short-term tiers plus a semantic long-term MemoryStore over valkey-search",
+  "keywords": [
+    "valkey",
+    "redis",
+    "valkey-search",
+    "agent",
+    "memory",
+    "llm"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BetterDB-inc/monitor",
+    "directory": "packages/agent-memory"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@betterdb/agent-cache": "workspace:*",
+    "@betterdb/valkey-search-kit": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.15",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.1"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

packages/agent-memory/src/AgentMemory.ts

@@ -0,0 +1 @@
+export class AgentMemory {}

packages/agent-memory/src/MemoryStore.ts

@@ -0,0 +1 @@
+export class MemoryStore {}

packages/agent-memory/src/__tests__/helpers/fakeEmbed.ts

@@ -0,0 +1,18 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * Deterministic, dimension-configurable embedding for hermetic unit tests:
+ * the same text always maps to the same normalized vector, so similarity is
+ * predictable without a real embedding provider.
+ */
+export function fakeEmbed(dims: number): (text: string) => Promise<number[]> {
+  return async (text: string) => {
+    const hash = createHash('sha256').update(text).digest('hex');
+    const vec = Array.from({ length: dims }, (_, i) => {
+      const offset = (i % 32) * 2;
+      return parseInt(hash.slice(offset, offset + 2), 16) / 255;
+    });
+    const norm = Math.sqrt(vec.reduce((sum, v) => sum + v * v, 0)) || 1;
+    return vec.map((v) => v / norm);
+  };
+}

packages/agent-memory/src/__tests__/helpers/mockClient.ts

@@ -0,0 +1,21 @@
+import { vi } from 'vitest';
+
+export type CommandHandler = (command: string, ...args: (string | Buffer | number)[]) => unknown;
+
+export interface MockClient {
+  call: ReturnType<typeof vi.fn>;
+}
+
+/**
+ * Minimal iovalkey-style mock: a `call` spy backed by a command handler.
+ * Mirrors the FT.* mocking pattern used in semantic-cache's unit tests.
+ */
+export function mockClient(handler?: CommandHandler): MockClient {
+  const defaultHandler: CommandHandler = () => 'OK';
+  const impl = handler ?? defaultHandler;
+  return {
+    call: vi.fn(async (command: string, ...args: (string | Buffer | number)[]) =>
+      impl(command, ...args),
+    ),
+  };
+}

packages/agent-memory/src/__tests__/index.test.ts

@@ -0,0 +1,16 @@
+import { describe, it, expect } from 'vitest';
+import { AgentCache, MemoryStore, AgentMemory } from '../index';
+
+describe('@betterdb/agent-memory exports', () => {
+  it('re-exports AgentCache from @betterdb/agent-cache', () => {
+    expect(typeof AgentCache).toBe('function');
+  });
+
+  it('exports the MemoryStore tier', () => {
+    expect(typeof MemoryStore).toBe('function');
+  });
+
+  it('exports the AgentMemory facade', () => {
+    expect(typeof AgentMemory).toBe('function');
+  });
+});

packages/agent-memory/src/index.ts

@@ -0,0 +1,3 @@
+export * from '@betterdb/agent-cache';
+export { MemoryStore } from './MemoryStore';
+export { AgentMemory } from './AgentMemory';

packages/agent-memory/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "CommonJS",
+    "lib": ["ES2022"],
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node",
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "src/__tests__"]
+}