feat(agent-memory): Phase 1 — remember() write path

packages/agent-memory/src/MemoryStore.ts

@@ -1 +1,43 @@
-export class MemoryStore {}
+import { randomUUID } from 'node:crypto';
+import { buildMemoryRecord } from './buildMemoryRecord';
+import type { EmbedFn, MemoryStoreClient, RememberOptions } from './types';
+
+export interface MemoryStoreOptions {
+  client: MemoryStoreClient;
+  name: string;
+  embedFn: EmbedFn;
+}
+
+export class MemoryStore {
+  private readonly client: MemoryStoreClient;
+  private readonly name: string;
+  private readonly embedFn: EmbedFn;
+  private dims?: number;
+
+  constructor(options: MemoryStoreOptions) {
+    this.client = options.client;
+    this.name = options.name;
+    this.embedFn = options.embedFn;
+  }
+
+  async remember(content: string, options: RememberOptions = {}): Promise<string> {
+    const vector = await this.embed(content);
+    const id = randomUUID();
+    const now = Date.now();
+    const record = buildMemoryRecord(this.name, id, content, vector, options, now);
+    await this.client.call('HSET', record.key, ...record.fields);
+    return id;
+  }
+
+  private async embed(content: string): Promise<number[]> {
+    const vector = await this.embedFn(content);
+    if (this.dims === undefined) {
+      this.dims = vector.length;
+    } else if (vector.length !== this.dims) {
+      throw new Error(
+        `Embedding dimension mismatch: expected ${this.dims}, embedFn returned ${vector.length}`,
+      );
+    }
+    return vector;
+  }
+}

packages/agent-memory/src/__tests__/MemoryStore.remember.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect, vi } from 'vitest';
+import { encodeFloat32 } from '@betterdb/valkey-search-kit';
+import { MemoryStore } from '../MemoryStore';
+import { fakeEmbed } from './helpers/fakeEmbed';
+import { mockClient } from './helpers/mockClient';
+
+function hsetFields(call: unknown[]): Record<string, string | Buffer> {
+  const fields = call.slice(2);
+  const out: Record<string, string | Buffer> = {};
+  for (let i = 0; i < fields.length; i += 2) {
+    out[String(fields[i])] = fields[i + 1] as string | Buffer;
+  }
+  return out;
+}
+
+describe('MemoryStore.remember', () => {
+  it('embeds content once, HSETs the memory hash, and returns an id', async () => {
+    const embedFn = vi.fn(fakeEmbed(8));
+    const client = mockClient();
+    const store = new MemoryStore({ client, name: 'mem', embedFn });
+
+    const id = await store.remember('the user prefers dark mode', {
+      threadId: 't1',
+      agentId: 'a1',
+      namespace: 'user:1',
+      tags: ['pref', 'ui'],
+      source: 'user',
+    });
+
+    expect(typeof id).toBe('string');
+    expect(id.length).toBeGreaterThan(0);
+    expect(embedFn).toHaveBeenCalledTimes(1);
+    expect(embedFn).toHaveBeenCalledWith('the user prefers dark mode');
+
+    const hset = client.call.mock.calls.find((args) => args[0] === 'HSET');
+    expect(hset?.[1]).toBe(`mem:mem:${id}`);
+
+    const fields = hsetFields(hset as unknown[]);
+    expect(fields.content).toBe('the user prefers dark mode');
+    expect(fields.threadId).toBe('t1');
+    expect(fields.agentId).toBe('a1');
+    expect(fields.namespace).toBe('user:1');
+    expect(fields.tags).toBe('pref,ui');
+    expect(fields.source).toBe('user');
+    expect(fields.importance).toBe('0.5');
+    expect(fields.access_count).toBe('0');
+    expect(fields.vector).toEqual(encodeFloat32(await fakeEmbed(8)('the user prefers dark mode')));
+    expect(typeof fields.created_at).toBe('string');
+    expect(fields.last_accessed_at).toBe(fields.created_at);
+  });
+
+  it('honors a provided importance and omits absent optional fields', async () => {
+    const client = mockClient();
+    const store = new MemoryStore({ client, name: 'mem', embedFn: fakeEmbed(8) });
+
+    await store.remember('a bare fact', { importance: 0.9 });
+
+    const hset = client.call.mock.calls.find((args) => args[0] === 'HSET');
+    const fields = hsetFields(hset as unknown[]);
+    expect(fields.importance).toBe('0.9');
+    expect('tags' in fields).toBe(false);
+    expect('threadId' in fields).toBe(false);
+    expect('source' in fields).toBe(false);
+  });
+
+  it('throws when a later embedding has a mismatched dimension', async () => {
+    let dims = 8;
+    const embedFn = vi.fn(async () => new Array(dims).fill(0.1));
+    const store = new MemoryStore({ client: mockClient(), name: 'mem', embedFn });
+
+    await store.remember('first');
+    dims = 4;
+
+    await expect(store.remember('second')).rejects.toThrow(/dimension/i);
+  });
+});

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

@@ -0,0 +1,77 @@
+import { describe, it, expect } from 'vitest';
+import { encodeFloat32 } from '@betterdb/valkey-search-kit';
+import { buildMemoryRecord } from '../buildMemoryRecord';
+
+function toObject(fields: (string | Buffer)[]): Record<string, string | Buffer> {
+  const out: Record<string, string | Buffer> = {};
+  for (let i = 0; i < fields.length; i += 2) {
+    out[String(fields[i])] = fields[i + 1];
+  }
+  return out;
+}
+
+describe('buildMemoryRecord', () => {
+  it('builds the {name}:mem:{id} key and a deterministic field list', () => {
+    const vector = [0.1, 0.2, 0.3, 0.4];
+    const record = buildMemoryRecord(
+      'mem',
+      'id1',
+      'hello world',
+      vector,
+      {
+        threadId: 't',
+        agentId: 'a',
+        namespace: 'n',
+        tags: ['x', 'y'],
+        importance: 0.7,
+        source: 'user',
+      },
+      1000,
+    );
+
+    expect(record.key).toBe('mem:mem:id1');
+    const f = toObject(record.fields);
+    expect(f.content).toBe('hello world');
+    expect(f.importance).toBe('0.7');
+    expect(f.tags).toBe('x,y');
+    expect(f.threadId).toBe('t');
+    expect(f.agentId).toBe('a');
+    expect(f.namespace).toBe('n');
+    expect(f.source).toBe('user');
+    expect(f.created_at).toBe('1000');
+    expect(f.last_accessed_at).toBe('1000');
+    expect(f.access_count).toBe('0');
+    expect(f.vector).toEqual(encodeFloat32(vector));
+  });
+
+  it('defaults importance to 0.5 and omits absent optional fields including empty tags', () => {
+    const record = buildMemoryRecord('mem', 'id2', 'x', [0, 0], {}, 5);
+
+    const f = toObject(record.fields);
+    expect(f.importance).toBe('0.5');
+    expect('tags' in f).toBe(false);
+    expect('threadId' in f).toBe(false);
+    expect('source' in f).toBe(false);
+  });
+
+  it('throws when a tag contains a comma (would break TAG tokenization)', () => {
+    expect(() =>
+      buildMemoryRecord('mem', 'id3', 'x', [0, 0], { tags: ['tool:web,search'] }, 5),
+    ).toThrow(/comma/i);
+  });
+
+  it('rejects an importance outside [0, 1] or non-finite, so a bad value cannot poison ranking', () => {
+    for (const bad of [NaN, Infinity, -Infinity, -0.1, 1.5, 42]) {
+      expect(() =>
+        buildMemoryRecord('mem', 'idx', 'x', [0, 0], { importance: bad }, 5),
+      ).toThrow(/importance/i);
+    }
+  });
+
+  it('accepts the inclusive [0, 1] bounds', () => {
+    for (const ok of [0, 0.5, 1]) {
+      const record = buildMemoryRecord('mem', 'idx', 'x', [0, 0], { importance: ok }, 5);
+      expect(toObject(record.fields).importance).toBe(String(ok));
+    }
+  });
+});

packages/agent-memory/src/buildMemoryRecord.ts

@@ -0,0 +1,65 @@
+import { encodeFloat32 } from '@betterdb/valkey-search-kit';
+import type { RememberOptions } from './types';
+
+export interface MemoryWrite {
+  key: string;
+  fields: (string | Buffer)[];
+}
+
+const DEFAULT_IMPORTANCE = 0.5;
+
+export function buildMemoryRecord(
+  name: string,
+  id: string,
+  content: string,
+  vector: number[],
+  options: RememberOptions,
+  now: number,
+): MemoryWrite {
+  const importance = options.importance ?? DEFAULT_IMPORTANCE;
+  if (!Number.isFinite(importance) || importance < 0 || importance > 1) {
+    throw new Error(
+      `importance must be a finite number in [0, 1], got: ${String(options.importance)}`,
+    );
+  }
+
+  const fields: (string | Buffer)[] = [
+    'content',
+    content,
+    'vector',
+    encodeFloat32(vector),
+    'importance',
+    String(importance),
+    'created_at',
+    String(now),
+    'last_accessed_at',
+    String(now),
+    'access_count',
+    '0',
+  ];
+
+  const tags = options.tags ?? [];
+  for (const tag of tags) {
+    if (tag.includes(',')) {
+      throw new Error(`Tag '${tag}' must not contain a comma; tags are stored comma-separated`);
+    }
+  }
+  if (tags.length > 0) {
+    fields.push('tags', tags.join(','));
+  }
+
+  if (options.threadId !== undefined) {
+    fields.push('threadId', options.threadId);
+  }
+  if (options.agentId !== undefined) {
+    fields.push('agentId', options.agentId);
+  }
+  if (options.namespace !== undefined) {
+    fields.push('namespace', options.namespace);
+  }
+  if (options.source !== undefined) {
+    fields.push('source', options.source);
+  }
+
+  return { key: `${name}:mem:${id}`, fields };
+}

packages/agent-memory/src/index.ts

@@ -1,3 +1,5 @@
 export * from '@betterdb/agent-cache';
 export { MemoryStore } from './MemoryStore';
+export type { MemoryStoreOptions } from './MemoryStore';
 export { AgentMemory } from './AgentMemory';
+export type { EmbedFn, MemoryStoreClient, MemoryScope, RememberOptions } from './types';

packages/agent-memory/src/types.ts

@@ -0,0 +1,17 @@
+export type EmbedFn = (text: string) => Promise<number[]>;
+
+export interface MemoryStoreClient {
+  call(command: string, ...args: (string | Buffer | number)[]): Promise<unknown>;
+}
+
+export interface MemoryScope {
+  threadId?: string;
+  agentId?: string;
+  namespace?: string;
+}
+
+export interface RememberOptions extends MemoryScope {
+  importance?: number;
+  tags?: string[];
+  source?: string;
+}