From 5b99c821933f7feb5f7d4c03b2ccd01dc2dbe0bf Mon Sep 17 00:00:00 2001 From: Jarvis Date: Mon, 13 Jul 2026 07:15:52 -0500 Subject: [PATCH 1/3] wip(m4-003): memory/retrieval slice handoff from coder4 --- docs/tess/M4-003-OPERATOR-PLUGIN-SKETCH.md | 17 ++++ packages/memory/src/index.ts | 7 ++ .../memory/src/operator-memory-plugin.test.ts | 58 +++++++++++++ packages/memory/src/operator-memory-plugin.ts | 84 +++++++++++++++++++ 4 files changed, 166 insertions(+) create mode 100644 docs/tess/M4-003-OPERATOR-PLUGIN-SKETCH.md create mode 100644 packages/memory/src/operator-memory-plugin.test.ts create mode 100644 packages/memory/src/operator-memory-plugin.ts diff --git a/docs/tess/M4-003-OPERATOR-PLUGIN-SKETCH.md b/docs/tess/M4-003-OPERATOR-PLUGIN-SKETCH.md new file mode 100644 index 0000000..e019cb8 --- /dev/null +++ b/docs/tess/M4-003-OPERATOR-PLUGIN-SKETCH.md @@ -0,0 +1,17 @@ +# TESS-M4-003 Operator Plugin Sketch + +## Memory/retrieval slice — TESS-MEM-001 + +Introduce a transport-neutral `OperatorMemoryPlugin` in `packages/memory`. The plugin receives a server-derived `{tenantId, ownerId, sessionId}` scope and delegates to a registered `MemoryAdapter`; callers cannot select an adapter or namespace. Its operations are `capture`, `search`, `recent`, `stats`, and `startupContext`. Results carry provenance and namespace metadata. Capture/redaction occurs before adapter persistence; startup context is bounded and ordered so project/flat-file truth can take precedence over retrieved material. + +Registration remains replaceable-adapter based: `registerOperatorMemoryAdapter(kind, factory)` and `createOperatorMemoryPlugin(config)` resolve a configured adapter. Identity and namespace are configuration/scope data; no interaction-agent name is embedded in keys or defaults. + +## Remaining plugin foundations — TESS-PLG-001 + +- `packages/agent`: capability descriptors for runtime bootstrap, durable inbox/state hooks, and read-only fleet diagnostics. Each capability advertises supported operations and fails closed when absent. +- `packages/mosaic`: a catalog/registration surface for GitOps, fleet diagnostics, runtime bootstrap, Discord, and MCP/skill discovery. Catalog entries describe authority, input schema, and safe/read-only status; they do not invoke provider transports directly. +- Gateway/channel adapters consume these contracts through server-derived actor/tenant context and durable session state, preserving the replaceable-adapter boundary. + +## First implementation boundary + +The first PR slice should add the operator-memory plugin contract, config-driven factory registration, scope isolation, provenance-bearing retrieval, and tests for namespace isolation plus a differently named configured instance. Durable inbox/outbox remains owned by the existing `DurableSessionCoordinator`; this plugin only supplies bounded context/capture at lifecycle boundaries. diff --git a/packages/memory/src/index.ts b/packages/memory/src/index.ts index 97f734d..243a027 100644 --- a/packages/memory/src/index.ts +++ b/packages/memory/src/index.ts @@ -22,6 +22,13 @@ export type { InsightSearchResult, } from './types.js'; export { createMemoryAdapter, registerMemoryAdapter } from './factory.js'; +export { + createOperatorMemoryPlugin, + type OperatorMemoryPlugin, + type OperatorMemoryScope, + type OperatorMemoryConfig, + type OperatorMemoryResult, +} from './operator-memory-plugin.js'; export { PgVectorAdapter } from './adapters/pgvector.js'; export { KeywordAdapter } from './adapters/keyword.js'; diff --git a/packages/memory/src/operator-memory-plugin.test.ts b/packages/memory/src/operator-memory-plugin.test.ts new file mode 100644 index 0000000..d9d2b55 --- /dev/null +++ b/packages/memory/src/operator-memory-plugin.test.ts @@ -0,0 +1,58 @@ +import { describe, expect, it, vi } from 'vitest'; +import { createOperatorMemoryPlugin } from './operator-memory-plugin.js'; + +function adapter() { + return { + name: 'test', + embedder: null, + storeInsight: vi.fn(async (value) => ({ ...value, id: '1', createdAt: new Date() })), + searchInsights: vi.fn(async () => []), + getInsight: vi.fn(), + deleteInsight: vi.fn(), + getPreference: vi.fn(), + setPreference: vi.fn(), + deletePreference: vi.fn(), + listPreferences: vi.fn(), + close: vi.fn(), + }; +} + +describe('OperatorMemoryPlugin', () => { + it('isolates adapter identity by server-derived tenant, owner, and namespace', async () => { + const memory = adapter(); + const plugin = createOperatorMemoryPlugin({ + adapter: memory, + instanceId: 'Nova', + redact: (v) => v, + }); + await plugin.capture( + { tenantId: 'tenant-a', ownerId: 'owner-a', sessionId: 's', namespace: 'private' }, + { content: 'one', source: 'test', category: 'note' }, + ); + await plugin.capture( + { tenantId: 'tenant-b', ownerId: 'owner-a', sessionId: 's', namespace: 'private' }, + { content: 'two', source: 'test', category: 'note' }, + ); + expect(memory.storeInsight.mock.calls.map((call: unknown[]) => call[0].userId)).toEqual([ + 'tenant-a:owner-a:private', + 'tenant-b:owner-a:private', + ]); + }); + + it('uses a differently named configured instance in retrieval provenance', async () => { + const memory = adapter(); + memory.searchInsights.mockResolvedValue([ + { id: '1', content: 'x', score: 1, metadata: { source: 'project' } }, + ]); + const plugin = createOperatorMemoryPlugin({ + adapter: memory, + instanceId: 'Nova', + redact: (v) => v, + }); + const results = await plugin.search( + { tenantId: 't', ownerId: 'o', sessionId: 's', namespace: 'n' }, + 'x', + ); + expect(results[0]?.provenance.instanceId).toBe('Nova'); + }); +}); diff --git a/packages/memory/src/operator-memory-plugin.ts b/packages/memory/src/operator-memory-plugin.ts new file mode 100644 index 0000000..64b9821 --- /dev/null +++ b/packages/memory/src/operator-memory-plugin.ts @@ -0,0 +1,84 @@ +import type { Insight, InsightSearchResult, MemoryAdapter } from './types.js'; + +/** Immutable server-derived boundary; callers never choose an adapter namespace. */ +export interface OperatorMemoryScope { + tenantId: string; + ownerId: string; + sessionId: string; + namespace: string; +} + +export interface OperatorMemoryConfig { + adapter: MemoryAdapter; + instanceId: string; + maxStartupContext?: number; + redact(content: string): string; +} + +export interface OperatorMemoryResult extends InsightSearchResult { + provenance: { instanceId: string; namespace: string; source: string }; +} + +export interface OperatorMemoryPlugin { + capture( + scope: OperatorMemoryScope, + input: { content: string; source: string; category: string }, + ): Promise; + search( + scope: OperatorMemoryScope, + query: string, + limit?: number, + ): Promise; + recent(scope: OperatorMemoryScope, limit?: number): Promise; + stats(scope: OperatorMemoryScope): Promise<{ namespace: string; resultCount: number }>; + startupContext(scope: OperatorMemoryScope): Promise; +} + +function scopedUserId(scope: OperatorMemoryScope): string { + return `${scope.tenantId}:${scope.ownerId}:${scope.namespace}`; +} + +/** Creates a leaf-package, replaceable memory adapter facade. */ +export function createOperatorMemoryPlugin(config: OperatorMemoryConfig): OperatorMemoryPlugin { + const mapResult = ( + scope: OperatorMemoryScope, + result: InsightSearchResult, + ): OperatorMemoryResult => ({ + ...result, + provenance: { + instanceId: config.instanceId, + namespace: scope.namespace, + source: String(result.metadata?.['source'] ?? 'retrieval'), + }, + }); + const search = async ( + scope: OperatorMemoryScope, + query: string, + limit = 10, + ): Promise => + (await config.adapter.searchInsights(scopedUserId(scope), query, { limit })).map((result) => + mapResult(scope, result), + ); + return { + async capture(scope, input) { + return config.adapter.storeInsight({ + userId: scopedUserId(scope), + content: config.redact(input.content), + source: input.source, + category: input.category, + relevanceScore: 1, + metadata: { namespace: scope.namespace, instanceId: config.instanceId }, + }); + }, + search, + async recent(scope, limit = 10) { + return search(scope, '*', limit); + }, + async stats(scope) { + return { namespace: scope.namespace, resultCount: (await search(scope, '*', 100)).length }; + }, + async startupContext(scope) { + return search(scope, '*', config.maxStartupContext ?? 8); + }, + }; +} -- 2.49.1 From c27f0dea60bb1212c7a14a398ef7852f17682417 Mon Sep 17 00:00:00 2001 From: Jarvis Date: Mon, 13 Jul 2026 07:19:09 -0500 Subject: [PATCH 2/3] fix(memory): scope operator plugin retrieval --- docs/tess/M4-003-OPERATOR-PLUGIN-SKETCH.md | 2 +- .../memory/src/operator-memory-plugin.test.ts | 74 +++++++++++++++---- packages/memory/src/operator-memory-plugin.ts | 74 +++++++++++++------ 3 files changed, 112 insertions(+), 38 deletions(-) diff --git a/docs/tess/M4-003-OPERATOR-PLUGIN-SKETCH.md b/docs/tess/M4-003-OPERATOR-PLUGIN-SKETCH.md index e019cb8..0baf49e 100644 --- a/docs/tess/M4-003-OPERATOR-PLUGIN-SKETCH.md +++ b/docs/tess/M4-003-OPERATOR-PLUGIN-SKETCH.md @@ -2,7 +2,7 @@ ## Memory/retrieval slice — TESS-MEM-001 -Introduce a transport-neutral `OperatorMemoryPlugin` in `packages/memory`. The plugin receives a server-derived `{tenantId, ownerId, sessionId}` scope and delegates to a registered `MemoryAdapter`; callers cannot select an adapter or namespace. Its operations are `capture`, `search`, `recent`, `stats`, and `startupContext`. Results carry provenance and namespace metadata. Capture/redaction occurs before adapter persistence; startup context is bounded and ordered so project/flat-file truth can take precedence over retrieved material. +Introduce a transport-neutral `OperatorMemoryPlugin` in `packages/memory`. The plugin receives a server-derived `{tenantId, ownerId, sessionId}` scope and delegates to a registered `MemoryAdapter`; adapter and namespace are injected configuration, never caller input. Its operations are `capture`, `search`, `recent`, `stats`, and `startupContext`. Results carry configured instance, provenance, and namespace metadata. Capture/redaction occurs before adapter persistence; startup context is bounded and ordered so project/flat-file truth can take precedence over retrieved material. Registration remains replaceable-adapter based: `registerOperatorMemoryAdapter(kind, factory)` and `createOperatorMemoryPlugin(config)` resolve a configured adapter. Identity and namespace are configuration/scope data; no interaction-agent name is embedded in keys or defaults. diff --git a/packages/memory/src/operator-memory-plugin.test.ts b/packages/memory/src/operator-memory-plugin.test.ts index d9d2b55..adfd2a3 100644 --- a/packages/memory/src/operator-memory-plugin.test.ts +++ b/packages/memory/src/operator-memory-plugin.test.ts @@ -1,12 +1,19 @@ import { describe, expect, it, vi } from 'vitest'; import { createOperatorMemoryPlugin } from './operator-memory-plugin.js'; +import type { Insight, InsightSearchResult, NewInsight } from './types.js'; function adapter() { return { name: 'test', embedder: null, - storeInsight: vi.fn(async (value) => ({ ...value, id: '1', createdAt: new Date() })), - searchInsights: vi.fn(async () => []), + storeInsight: vi.fn( + async (value: NewInsight): Promise => ({ + ...value, + id: '1', + createdAt: new Date(), + }), + ), + searchInsights: vi.fn(async (): Promise => []), getInsight: vi.fn(), deleteInsight: vi.fn(), getPreference: vi.fn(), @@ -18,24 +25,33 @@ function adapter() { } describe('OperatorMemoryPlugin', () => { - it('isolates adapter identity by server-derived tenant, owner, and namespace', async () => { + it('isolates configured namespace storage across server-derived tenant, owner, and session scopes', async () => { const memory = adapter(); const plugin = createOperatorMemoryPlugin({ adapter: memory, instanceId: 'Nova', - redact: (v) => v, + namespace: 'operator-memory', + redact: (value) => value, }); await plugin.capture( - { tenantId: 'tenant-a', ownerId: 'owner-a', sessionId: 's', namespace: 'private' }, + { tenantId: 'tenant-a', ownerId: 'owner-a', sessionId: 'session-a' }, { content: 'one', source: 'test', category: 'note' }, ); await plugin.capture( - { tenantId: 'tenant-b', ownerId: 'owner-a', sessionId: 's', namespace: 'private' }, + { tenantId: 'tenant-b', ownerId: 'owner-a', sessionId: 'session-a' }, { content: 'two', source: 'test', category: 'note' }, ); - expect(memory.storeInsight.mock.calls.map((call: unknown[]) => call[0].userId)).toEqual([ - 'tenant-a:owner-a:private', - 'tenant-b:owner-a:private', + await plugin.capture( + { tenantId: 'tenant-a', ownerId: 'owner-a', sessionId: 'session-b' }, + { content: 'three', source: 'test', category: 'note' }, + ); + + expect( + memory.storeInsight.mock.calls.map((call: unknown[]) => (call[0] as NewInsight).userId), + ).toEqual([ + '["operator-memory","tenant-a","owner-a","session-a"]', + '["operator-memory","tenant-b","owner-a","session-a"]', + '["operator-memory","tenant-a","owner-a","session-b"]', ]); }); @@ -47,12 +63,42 @@ describe('OperatorMemoryPlugin', () => { const plugin = createOperatorMemoryPlugin({ adapter: memory, instanceId: 'Nova', - redact: (v) => v, + namespace: 'operator-memory', + redact: (value) => value, }); - const results = await plugin.search( - { tenantId: 't', ownerId: 'o', sessionId: 's', namespace: 'n' }, - 'x', + + const results = await plugin.search({ tenantId: 't', ownerId: 'o', sessionId: 's' }, 'x'); + + expect(results[0]?.provenance).toEqual({ + instanceId: 'Nova', + namespace: 'operator-memory', + source: 'project', + }); + }); + + it('redacts content before adapter persistence and records configured provenance metadata', async () => { + const memory = adapter(); + const plugin = createOperatorMemoryPlugin({ + adapter: memory, + instanceId: 'Nova', + namespace: 'operator-memory', + redact: (value) => value.replace('secret', '[REDACTED]'), + }); + + await plugin.capture( + { tenantId: 'tenant-a', ownerId: 'owner-a', sessionId: 'session-a' }, + { content: 'secret note', source: 'project', category: 'note' }, + ); + + expect(memory.storeInsight).toHaveBeenCalledWith( + expect.objectContaining({ + content: '[REDACTED] note', + metadata: { + instanceId: 'Nova', + namespace: 'operator-memory', + source: 'project', + }, + }), ); - expect(results[0]?.provenance.instanceId).toBe('Nova'); }); }); diff --git a/packages/memory/src/operator-memory-plugin.ts b/packages/memory/src/operator-memory-plugin.ts index 64b9821..766536f 100644 --- a/packages/memory/src/operator-memory-plugin.ts +++ b/packages/memory/src/operator-memory-plugin.ts @@ -2,16 +2,19 @@ import type { Insight, InsightSearchResult, MemoryAdapter } from './types.js'; /** Immutable server-derived boundary; callers never choose an adapter namespace. */ export interface OperatorMemoryScope { - tenantId: string; - ownerId: string; - sessionId: string; - namespace: string; + readonly tenantId: string; + readonly ownerId: string; + readonly sessionId: string; } export interface OperatorMemoryConfig { - adapter: MemoryAdapter; - instanceId: string; - maxStartupContext?: number; + /** Adapter injection is deployment/lifecycle configuration, never caller input. */ + readonly adapter: MemoryAdapter; + /** Configured agent identity; it is metadata rather than a storage key default. */ + readonly instanceId: string; + /** Configured storage partition; callers cannot select a namespace. */ + readonly namespace: string; + readonly maxStartupContext?: number; redact(content: string): string; } @@ -34,20 +37,32 @@ export interface OperatorMemoryPlugin { startupContext(scope: OperatorMemoryScope): Promise; } -function scopedUserId(scope: OperatorMemoryScope): string { - return `${scope.tenantId}:${scope.ownerId}:${scope.namespace}`; +function scopedUserId(scope: OperatorMemoryScope, namespace: string): string { + // JSON tuple encoding avoids delimiter collisions between independently scoped IDs. + return JSON.stringify([namespace, scope.tenantId, scope.ownerId, scope.sessionId]); +} + +function normalizeConfig(config: OperatorMemoryConfig): OperatorMemoryConfig { + const instanceId = config.instanceId.trim(); + const namespace = config.namespace.trim(); + const maxStartupContext = config.maxStartupContext ?? 8; + if (instanceId.length === 0 || namespace.length === 0) { + throw new Error('Operator memory instance ID and namespace must be configured'); + } + if (!Number.isSafeInteger(maxStartupContext) || maxStartupContext < 1) { + throw new Error('Operator memory startup context limit must be a positive integer'); + } + return Object.freeze({ ...config, instanceId, namespace, maxStartupContext }); } /** Creates a leaf-package, replaceable memory adapter facade. */ export function createOperatorMemoryPlugin(config: OperatorMemoryConfig): OperatorMemoryPlugin { - const mapResult = ( - scope: OperatorMemoryScope, - result: InsightSearchResult, - ): OperatorMemoryResult => ({ + const pluginConfig = normalizeConfig(config); + const mapResult = (result: InsightSearchResult): OperatorMemoryResult => ({ ...result, provenance: { - instanceId: config.instanceId, - namespace: scope.namespace, + instanceId: pluginConfig.instanceId, + namespace: pluginConfig.namespace, source: String(result.metadata?.['source'] ?? 'retrieval'), }, }); @@ -56,18 +71,28 @@ export function createOperatorMemoryPlugin(config: OperatorMemoryConfig): Operat query: string, limit = 10, ): Promise => - (await config.adapter.searchInsights(scopedUserId(scope), query, { limit })).map((result) => - mapResult(scope, result), - ); + ( + await pluginConfig.adapter.searchInsights( + scopedUserId(scope, pluginConfig.namespace), + query, + { + limit, + }, + ) + ).map(mapResult); return { async capture(scope, input) { return config.adapter.storeInsight({ - userId: scopedUserId(scope), - content: config.redact(input.content), + userId: scopedUserId(scope, pluginConfig.namespace), + content: pluginConfig.redact(input.content), source: input.source, category: input.category, relevanceScore: 1, - metadata: { namespace: scope.namespace, instanceId: config.instanceId }, + metadata: { + namespace: pluginConfig.namespace, + instanceId: pluginConfig.instanceId, + source: input.source, + }, }); }, search, @@ -75,10 +100,13 @@ export function createOperatorMemoryPlugin(config: OperatorMemoryConfig): Operat return search(scope, '*', limit); }, async stats(scope) { - return { namespace: scope.namespace, resultCount: (await search(scope, '*', 100)).length }; + return { + namespace: pluginConfig.namespace, + resultCount: (await search(scope, '*', 100)).length, + }; }, async startupContext(scope) { - return search(scope, '*', config.maxStartupContext ?? 8); + return search(scope, '*', pluginConfig.maxStartupContext); }, }; } -- 2.49.1 From a1d63ca8ed07610828e9c51a213fffe9123b3de4 Mon Sep 17 00:00:00 2001 From: Jarvis Date: Mon, 13 Jul 2026 07:29:02 -0500 Subject: [PATCH 3/3] feat(memory): add operator retrieval plugin --- .../tess-m4-003-operator-plugins.md | 27 +++++++++++ docs/tess/M4-003-OPERATOR-PLUGIN-SKETCH.md | 6 +-- packages/memory/src/adapters/keyword.test.ts | 14 ++++++ packages/memory/src/adapters/keyword.ts | 16 ++++--- .../memory/src/operator-memory-plugin.test.ts | 43 +++++++++++++++++ packages/memory/src/operator-memory-plugin.ts | 48 +++++++++++++++++-- packages/memory/src/types.ts | 4 ++ 7 files changed, 146 insertions(+), 12 deletions(-) create mode 100644 docs/scratchpads/tess-m4-003-operator-plugins.md diff --git a/docs/scratchpads/tess-m4-003-operator-plugins.md b/docs/scratchpads/tess-m4-003-operator-plugins.md new file mode 100644 index 0000000..90c690d --- /dev/null +++ b/docs/scratchpads/tess-m4-003-operator-plugins.md @@ -0,0 +1,27 @@ +# TESS-M4-003 — Operator Plugin Foundations + +- **Task:** TESS-M4-003 / TESS-MEM-001 +- **Branch/base:** `feat/tess-operator-plugins` rebased on `origin/main` `76325ca3` +- **Scope:** first leaf-package memory/retrieval slice only; no durable inbox ownership, gateway integration, or Mosaic catalog implementation. + +## Handoff + +Coder4's uncommitted implementation was preserved first in commit `5b99c821` before review. The completion pass corrected the contract so namespace is injected configuration rather than caller-selected scope data, storage keys include tenant/owner/session via collision-safe tuple encoding, and malformed runtime scope values fail closed. + +## Delivered boundary + +- `OperatorMemoryPlugin` exposes `capture`, `search`, `recent`, `stats`, and `startupContext` through `MemoryAdapter` only. +- Scope is server-derived `{tenantId, ownerId, sessionId}`; adapter and namespace are configuration, not operation input. +- Capture redacts before persistence and records configured instance/namespace/source provenance. +- Wildcard retrieval is documented at the `MemoryAdapter` boundary and implemented by the keyword adapter. +- Startup context uses a bounded 64-result candidate window, then prioritizes project and flat-file provenance before slicing the configured output limit. +- No `Tess` identity is hardcoded in storage keys or defaults; tests use configured `Nova`. + +## Verification + +- `pnpm --filter @mosaicstack/memory test` — PASS (32 tests) +- `pnpm --filter @mosaicstack/memory typecheck` — PASS +- `pnpm --filter @mosaicstack/memory lint` — PASS +- `pnpm --filter @mosaicstack/memory build` — PASS +- Codex code review — APPROVE after remediation +- Codex security review — no findings after runtime scope-validation remediation diff --git a/docs/tess/M4-003-OPERATOR-PLUGIN-SKETCH.md b/docs/tess/M4-003-OPERATOR-PLUGIN-SKETCH.md index 0baf49e..5bacf6a 100644 --- a/docs/tess/M4-003-OPERATOR-PLUGIN-SKETCH.md +++ b/docs/tess/M4-003-OPERATOR-PLUGIN-SKETCH.md @@ -2,9 +2,9 @@ ## Memory/retrieval slice — TESS-MEM-001 -Introduce a transport-neutral `OperatorMemoryPlugin` in `packages/memory`. The plugin receives a server-derived `{tenantId, ownerId, sessionId}` scope and delegates to a registered `MemoryAdapter`; adapter and namespace are injected configuration, never caller input. Its operations are `capture`, `search`, `recent`, `stats`, and `startupContext`. Results carry configured instance, provenance, and namespace metadata. Capture/redaction occurs before adapter persistence; startup context is bounded and ordered so project/flat-file truth can take precedence over retrieved material. +Introduce a transport-neutral `OperatorMemoryPlugin` in `packages/memory`. The plugin receives a server-derived `{tenantId, ownerId, sessionId}` scope and delegates to a registered `MemoryAdapter`; adapter and namespace are injected configuration, never caller input. Its operations are `capture`, `search`, `recent`, `stats`, and `startupContext`. Results carry configured instance, provenance, and namespace metadata. Capture/redaction occurs before adapter persistence; startup context uses a bounded candidate window ordered so project/flat-file truth takes precedence within returned material. -Registration remains replaceable-adapter based: `registerOperatorMemoryAdapter(kind, factory)` and `createOperatorMemoryPlugin(config)` resolve a configured adapter. Identity and namespace are configuration/scope data; no interaction-agent name is embedded in keys or defaults. +Registration remains replaceable-adapter based: the existing `registerMemoryAdapter(kind, factory)` / `createMemoryAdapter(config)` seam supplies the injected adapter to `createOperatorMemoryPlugin(config)`. Identity and namespace are configuration data; no interaction-agent name is embedded in keys or defaults. ## Remaining plugin foundations — TESS-PLG-001 @@ -14,4 +14,4 @@ Registration remains replaceable-adapter based: `registerOperatorMemoryAdapter(k ## First implementation boundary -The first PR slice should add the operator-memory plugin contract, config-driven factory registration, scope isolation, provenance-bearing retrieval, and tests for namespace isolation plus a differently named configured instance. Durable inbox/outbox remains owned by the existing `DurableSessionCoordinator`; this plugin only supplies bounded context/capture at lifecycle boundaries. +The first PR slice should add the operator-memory plugin contract, configuration-injected adapter seam, scope isolation, provenance-bearing retrieval, and tests for namespace isolation plus a differently named configured instance. Durable inbox/outbox remains owned by the existing `DurableSessionCoordinator`; this plugin only supplies bounded context/capture at lifecycle boundaries. diff --git a/packages/memory/src/adapters/keyword.test.ts b/packages/memory/src/adapters/keyword.test.ts index 2a0ac85..a56b800 100644 --- a/packages/memory/src/adapters/keyword.test.ts +++ b/packages/memory/src/adapters/keyword.test.ts @@ -274,6 +274,20 @@ describe('KeywordAdapter', () => { expect(results).toHaveLength(1); }); + it('should return all scoped insights for the explicit wildcard query', async () => { + await adapter.storeInsight({ + userId: 'u1', + content: 'A literal * marker is still ordinary content', + source: 'chat', + category: 'technical', + relevanceScore: 0.7, + }); + + const results = await adapter.searchInsights('u1', '*'); + expect(results).toHaveLength(4); + expect(results.every((result) => result.score === 1)).toBe(true); + }); + it('should return empty for empty query', async () => { const results = await adapter.searchInsights('u1', ' '); expect(results).toHaveLength(0); diff --git a/packages/memory/src/adapters/keyword.ts b/packages/memory/src/adapters/keyword.ts index 7575076..ea188e7 100644 --- a/packages/memory/src/adapters/keyword.ts +++ b/packages/memory/src/adapters/keyword.ts @@ -132,19 +132,23 @@ export class KeywordAdapter implements MemoryAdapter { opts?: { limit?: number; embedding?: number[] }, ): Promise { const limit = opts?.limit ?? 10; - const words = query - .toLowerCase() - .split(/\s+/) - .filter((w) => w.length > 0); + const normalizedQuery = query.trim(); + const matchAll = normalizedQuery === '*'; + const words = matchAll + ? [] + : normalizedQuery + .toLowerCase() + .split(/\s+/) + .filter((word) => word.length > 0); - if (words.length === 0) return []; + if (words.length === 0 && !matchAll) return []; const rows = await this.storage.find(INSIGHTS, { userId }); const scored: InsightSearchResult[] = []; for (const row of rows) { const content = row.content.toLowerCase(); - let score = 0; + let score = matchAll ? 1 : 0; for (const word of words) { if (content.includes(word)) score++; } diff --git a/packages/memory/src/operator-memory-plugin.test.ts b/packages/memory/src/operator-memory-plugin.test.ts index adfd2a3..26649db 100644 --- a/packages/memory/src/operator-memory-plugin.test.ts +++ b/packages/memory/src/operator-memory-plugin.test.ts @@ -55,6 +55,24 @@ describe('OperatorMemoryPlugin', () => { ]); }); + it('rejects an incomplete runtime scope before it can produce a shared storage key', async () => { + const memory = adapter(); + const plugin = createOperatorMemoryPlugin({ + adapter: memory, + instanceId: 'Nova', + namespace: 'operator-memory', + redact: (value) => value, + }); + + await expect( + plugin.capture( + { tenantId: 'tenant-a', ownerId: 'owner-a', sessionId: ' ' }, + { content: 'note', source: 'test', category: 'note' }, + ), + ).rejects.toThrow('Operator memory session ID is required'); + expect(memory.storeInsight).not.toHaveBeenCalled(); + }); + it('uses a differently named configured instance in retrieval provenance', async () => { const memory = adapter(); memory.searchInsights.mockResolvedValue([ @@ -76,6 +94,31 @@ describe('OperatorMemoryPlugin', () => { }); }); + it('orders startup context with project and flat-file truth before retrieved material', async () => { + const memory = adapter(); + memory.searchInsights.mockResolvedValue([ + { id: 'retrieval', content: 'retrieval', score: 1 }, + { id: 'flat-file', content: 'flat-file', score: 1, metadata: { source: 'flat-file' } }, + { id: 'project', content: 'project', score: 1, metadata: { source: 'project' } }, + ]); + const plugin = createOperatorMemoryPlugin({ + adapter: memory, + instanceId: 'Nova', + namespace: 'operator-memory', + maxStartupContext: 2, + redact: (value) => value, + }); + + const context = await plugin.startupContext({ + tenantId: 'tenant-a', + ownerId: 'owner-a', + sessionId: 'session-a', + }); + + expect(context.map((result) => result.id)).toEqual(['project', 'flat-file']); + expect(memory.searchInsights).toHaveBeenCalledWith(expect.any(String), '*', { limit: 64 }); + }); + it('redacts content before adapter persistence and records configured provenance metadata', async () => { const memory = adapter(); const plugin = createOperatorMemoryPlugin({ diff --git a/packages/memory/src/operator-memory-plugin.ts b/packages/memory/src/operator-memory-plugin.ts index 766536f..698d904 100644 --- a/packages/memory/src/operator-memory-plugin.ts +++ b/packages/memory/src/operator-memory-plugin.ts @@ -1,5 +1,7 @@ import type { Insight, InsightSearchResult, MemoryAdapter } from './types.js'; +const STARTUP_CONTEXT_CANDIDATE_LIMIT = 64; + /** Immutable server-derived boundary; callers never choose an adapter namespace. */ export interface OperatorMemoryScope { readonly tenantId: string; @@ -38,8 +40,44 @@ export interface OperatorMemoryPlugin { } function scopedUserId(scope: OperatorMemoryScope, namespace: string): string { + const normalizedScope = normalizeScope(scope); // JSON tuple encoding avoids delimiter collisions between independently scoped IDs. - return JSON.stringify([namespace, scope.tenantId, scope.ownerId, scope.sessionId]); + return JSON.stringify([ + namespace, + normalizedScope.tenantId, + normalizedScope.ownerId, + normalizedScope.sessionId, + ]); +} + +function normalizeScope(scope: OperatorMemoryScope): OperatorMemoryScope { + if (typeof scope !== 'object' || scope === null) { + throw new Error('Operator memory scope is required'); + } + return Object.freeze({ + tenantId: requiredScopeId(scope.tenantId, 'tenant ID'), + ownerId: requiredScopeId(scope.ownerId, 'owner ID'), + sessionId: requiredScopeId(scope.sessionId, 'session ID'), + }); +} + +function requiredScopeId(value: unknown, field: string): string { + if (typeof value !== 'string' || value.trim().length === 0) { + throw new Error(`Operator memory ${field} is required`); + } + return value.trim(); +} + +function compareStartupContext(left: OperatorMemoryResult, right: OperatorMemoryResult): number { + return ( + startupSourcePriority(left.provenance.source) - startupSourcePriority(right.provenance.source) + ); +} + +function startupSourcePriority(source: string): number { + if (source === 'project') return 0; + if (source === 'flat-file') return 1; + return 2; } function normalizeConfig(config: OperatorMemoryConfig): OperatorMemoryConfig { @@ -82,7 +120,7 @@ export function createOperatorMemoryPlugin(config: OperatorMemoryConfig): Operat ).map(mapResult); return { async capture(scope, input) { - return config.adapter.storeInsight({ + return pluginConfig.adapter.storeInsight({ userId: scopedUserId(scope, pluginConfig.namespace), content: pluginConfig.redact(input.content), source: input.source, @@ -106,7 +144,11 @@ export function createOperatorMemoryPlugin(config: OperatorMemoryConfig): Operat }; }, async startupContext(scope) { - return search(scope, '*', pluginConfig.maxStartupContext); + const maxStartupContext = pluginConfig.maxStartupContext ?? 8; + // Prioritize authoritative sources within a bounded candidate window. + const candidateLimit = Math.max(maxStartupContext, STARTUP_CONTEXT_CANDIDATE_LIMIT); + const context = await search(scope, '*', candidateLimit); + return [...context].sort(compareStartupContext).slice(0, maxStartupContext); }, }; } diff --git a/packages/memory/src/types.ts b/packages/memory/src/types.ts index 47f9bf0..22aeb41 100644 --- a/packages/memory/src/types.ts +++ b/packages/memory/src/types.ts @@ -49,6 +49,10 @@ export interface MemoryAdapter { // Insights storeInsight(insight: NewInsight): Promise; getInsight(id: string): Promise; + /** + * Searches within one scoped user ID. The reserved `*` query returns scoped + * recent/all results rather than performing backend-specific wildcard parsing. + */ searchInsights( userId: string, query: string, -- 2.49.1