chore: consolidate new foundation and archive v1 (#1495)
This commit is contained in:
@@ -0,0 +1,42 @@
|
||||
{
|
||||
"name": "@mosaicstack/memory",
|
||||
"version": "0.0.4",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://git.mosaicstack.dev/mosaicstack/stack.git",
|
||||
"directory": "packages/memory"
|
||||
},
|
||||
"type": "module",
|
||||
"main": "dist/index.js",
|
||||
"types": "dist/index.d.ts",
|
||||
"exports": {
|
||||
".": {
|
||||
"types": "./dist/index.d.ts",
|
||||
"default": "./dist/index.js"
|
||||
}
|
||||
},
|
||||
"scripts": {
|
||||
"build": "tsc",
|
||||
"lint": "eslint src",
|
||||
"typecheck": "tsc --noEmit",
|
||||
"test": "vitest run --passWithNoTests"
|
||||
},
|
||||
"dependencies": {
|
||||
"@mosaicstack/db": "workspace:*",
|
||||
"@mosaicstack/storage": "workspace:*",
|
||||
"@mosaicstack/types": "workspace:*",
|
||||
"commander": "^13.0.0",
|
||||
"drizzle-orm": "^0.45.1"
|
||||
},
|
||||
"devDependencies": {
|
||||
"typescript": "^5.8.0",
|
||||
"vitest": "^2.0.0"
|
||||
},
|
||||
"publishConfig": {
|
||||
"registry": "https://git.mosaicstack.dev/api/packages/mosaicstack/npm/",
|
||||
"access": "public"
|
||||
},
|
||||
"files": [
|
||||
"dist"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,312 @@
|
||||
import { describe, it, expect, beforeEach } from 'vitest';
|
||||
import type { StorageAdapter } from '@mosaicstack/storage';
|
||||
import { KeywordAdapter } from './keyword.js';
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* In-memory mock StorageAdapter */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
function createMockStorage(): StorageAdapter {
|
||||
const collections = new Map<string, Map<string, Record<string, unknown>>>();
|
||||
let idCounter = 0;
|
||||
|
||||
function getCollection(name: string): Map<string, Record<string, unknown>> {
|
||||
if (!collections.has(name)) collections.set(name, new Map());
|
||||
return collections.get(name)!;
|
||||
}
|
||||
|
||||
const adapter: StorageAdapter = {
|
||||
name: 'mock',
|
||||
|
||||
async create<T extends Record<string, unknown>>(
|
||||
collection: string,
|
||||
data: T,
|
||||
): Promise<T & { id: string }> {
|
||||
const id = String(++idCounter);
|
||||
const record = { ...data, id };
|
||||
getCollection(collection).set(id, record);
|
||||
return record as T & { id: string };
|
||||
},
|
||||
|
||||
async read<T extends Record<string, unknown>>(
|
||||
collection: string,
|
||||
id: string,
|
||||
): Promise<T | null> {
|
||||
const record = getCollection(collection).get(id);
|
||||
return (record as T) ?? null;
|
||||
},
|
||||
|
||||
async update(collection: string, id: string, data: Record<string, unknown>): Promise<boolean> {
|
||||
const col = getCollection(collection);
|
||||
const existing = col.get(id);
|
||||
if (!existing) return false;
|
||||
col.set(id, { ...existing, ...data });
|
||||
return true;
|
||||
},
|
||||
|
||||
async delete(collection: string, id: string): Promise<boolean> {
|
||||
return getCollection(collection).delete(id);
|
||||
},
|
||||
|
||||
async find<T extends Record<string, unknown>>(
|
||||
collection: string,
|
||||
filter?: Record<string, unknown>,
|
||||
): Promise<T[]> {
|
||||
const col = getCollection(collection);
|
||||
const results: T[] = [];
|
||||
for (const record of col.values()) {
|
||||
if (filter && !matchesFilter(record, filter)) continue;
|
||||
results.push(record as T);
|
||||
}
|
||||
return results;
|
||||
},
|
||||
|
||||
async findOne<T extends Record<string, unknown>>(
|
||||
collection: string,
|
||||
filter: Record<string, unknown>,
|
||||
): Promise<T | null> {
|
||||
const col = getCollection(collection);
|
||||
for (const record of col.values()) {
|
||||
if (matchesFilter(record, filter)) return record as T;
|
||||
}
|
||||
return null;
|
||||
},
|
||||
|
||||
async count(collection: string, filter?: Record<string, unknown>): Promise<number> {
|
||||
const rows = await adapter.find(collection, filter);
|
||||
return rows.length;
|
||||
},
|
||||
|
||||
async transaction<T>(fn: (tx: StorageAdapter) => Promise<T>): Promise<T> {
|
||||
return fn(adapter);
|
||||
},
|
||||
|
||||
async migrate(): Promise<void> {},
|
||||
async close(): Promise<void> {},
|
||||
};
|
||||
|
||||
return adapter;
|
||||
}
|
||||
|
||||
function matchesFilter(record: Record<string, unknown>, filter: Record<string, unknown>): boolean {
|
||||
for (const [key, value] of Object.entries(filter)) {
|
||||
if (record[key] !== value) return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* Tests */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
describe('KeywordAdapter', () => {
|
||||
let adapter: KeywordAdapter;
|
||||
|
||||
beforeEach(() => {
|
||||
adapter = new KeywordAdapter({ type: 'keyword', storage: createMockStorage() });
|
||||
});
|
||||
|
||||
/* ---- Preferences ---- */
|
||||
|
||||
describe('preferences', () => {
|
||||
it('should set and get a preference', async () => {
|
||||
await adapter.setPreference('u1', 'theme', 'dark');
|
||||
const value = await adapter.getPreference('u1', 'theme');
|
||||
expect(value).toBe('dark');
|
||||
});
|
||||
|
||||
it('should return null for missing preference', async () => {
|
||||
const value = await adapter.getPreference('u1', 'nonexistent');
|
||||
expect(value).toBeNull();
|
||||
});
|
||||
|
||||
it('should upsert an existing preference', async () => {
|
||||
await adapter.setPreference('u1', 'theme', 'dark');
|
||||
await adapter.setPreference('u1', 'theme', 'light');
|
||||
const value = await adapter.getPreference('u1', 'theme');
|
||||
expect(value).toBe('light');
|
||||
});
|
||||
|
||||
it('should delete a preference', async () => {
|
||||
await adapter.setPreference('u1', 'theme', 'dark');
|
||||
const deleted = await adapter.deletePreference('u1', 'theme');
|
||||
expect(deleted).toBe(true);
|
||||
const value = await adapter.getPreference('u1', 'theme');
|
||||
expect(value).toBeNull();
|
||||
});
|
||||
|
||||
it('should return false when deleting nonexistent preference', async () => {
|
||||
const deleted = await adapter.deletePreference('u1', 'nope');
|
||||
expect(deleted).toBe(false);
|
||||
});
|
||||
|
||||
it('should list preferences by userId', async () => {
|
||||
await adapter.setPreference('u1', 'theme', 'dark', 'appearance');
|
||||
await adapter.setPreference('u1', 'lang', 'en', 'locale');
|
||||
await adapter.setPreference('u2', 'theme', 'light', 'appearance');
|
||||
|
||||
const prefs = await adapter.listPreferences('u1');
|
||||
expect(prefs).toHaveLength(2);
|
||||
expect(prefs.map((p) => p.key).sort()).toEqual(['lang', 'theme']);
|
||||
});
|
||||
|
||||
it('should filter preferences by category', async () => {
|
||||
await adapter.setPreference('u1', 'theme', 'dark', 'appearance');
|
||||
await adapter.setPreference('u1', 'lang', 'en', 'locale');
|
||||
|
||||
const prefs = await adapter.listPreferences('u1', 'appearance');
|
||||
expect(prefs).toHaveLength(1);
|
||||
expect(prefs[0]!.key).toBe('theme');
|
||||
});
|
||||
});
|
||||
|
||||
/* ---- Insights ---- */
|
||||
|
||||
describe('insights', () => {
|
||||
it('should store and retrieve an insight', async () => {
|
||||
const insight = await adapter.storeInsight({
|
||||
userId: 'u1',
|
||||
content: 'TypeScript is great for type safety',
|
||||
source: 'chat',
|
||||
category: 'technical',
|
||||
relevanceScore: 0.9,
|
||||
});
|
||||
|
||||
expect(insight.id).toBeDefined();
|
||||
expect(insight.content).toBe('TypeScript is great for type safety');
|
||||
|
||||
const fetched = await adapter.getInsight(insight.id);
|
||||
expect(fetched).not.toBeNull();
|
||||
expect(fetched!.content).toBe('TypeScript is great for type safety');
|
||||
});
|
||||
|
||||
it('should return null for missing insight', async () => {
|
||||
const result = await adapter.getInsight('nonexistent');
|
||||
expect(result).toBeNull();
|
||||
});
|
||||
|
||||
it('should delete an insight', async () => {
|
||||
const insight = await adapter.storeInsight({
|
||||
userId: 'u1',
|
||||
content: 'test',
|
||||
source: 'chat',
|
||||
category: 'general',
|
||||
relevanceScore: 0.5,
|
||||
});
|
||||
|
||||
const deleted = await adapter.deleteInsight(insight.id);
|
||||
expect(deleted).toBe(true);
|
||||
|
||||
const fetched = await adapter.getInsight(insight.id);
|
||||
expect(fetched).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
/* ---- Keyword Search ---- */
|
||||
|
||||
describe('searchInsights', () => {
|
||||
beforeEach(async () => {
|
||||
await adapter.storeInsight({
|
||||
userId: 'u1',
|
||||
content: 'TypeScript provides excellent type safety for JavaScript projects',
|
||||
source: 'chat',
|
||||
category: 'technical',
|
||||
relevanceScore: 0.9,
|
||||
});
|
||||
await adapter.storeInsight({
|
||||
userId: 'u1',
|
||||
content: 'React hooks simplify state management in components',
|
||||
source: 'chat',
|
||||
category: 'technical',
|
||||
relevanceScore: 0.8,
|
||||
});
|
||||
await adapter.storeInsight({
|
||||
userId: 'u1',
|
||||
content: 'TypeScript and React work great together for type safe components',
|
||||
source: 'chat',
|
||||
category: 'technical',
|
||||
relevanceScore: 0.85,
|
||||
});
|
||||
await adapter.storeInsight({
|
||||
userId: 'u2',
|
||||
content: 'TypeScript is popular',
|
||||
source: 'chat',
|
||||
category: 'general',
|
||||
relevanceScore: 0.5,
|
||||
});
|
||||
});
|
||||
|
||||
it('should find insights by exact keyword', async () => {
|
||||
const results = await adapter.searchInsights('u1', 'hooks');
|
||||
expect(results).toHaveLength(1);
|
||||
expect(results[0]!.content).toContain('hooks');
|
||||
});
|
||||
|
||||
it('should be case-insensitive', async () => {
|
||||
const results = await adapter.searchInsights('u1', 'TYPESCRIPT');
|
||||
expect(results.length).toBeGreaterThanOrEqual(1);
|
||||
for (const r of results) {
|
||||
expect(r.content.toLowerCase()).toContain('typescript');
|
||||
}
|
||||
});
|
||||
|
||||
it('should rank multi-word matches higher', async () => {
|
||||
const results = await adapter.searchInsights('u1', 'TypeScript React');
|
||||
// The insight mentioning both "TypeScript" and "React" should rank first (score=2)
|
||||
expect(results[0]!.score).toBe(2);
|
||||
expect(results[0]!.content).toContain('TypeScript');
|
||||
expect(results[0]!.content).toContain('React');
|
||||
});
|
||||
|
||||
it('should return empty for no matches', async () => {
|
||||
const results = await adapter.searchInsights('u1', 'python django');
|
||||
expect(results).toHaveLength(0);
|
||||
});
|
||||
|
||||
it('should filter by userId', async () => {
|
||||
const results = await adapter.searchInsights('u2', 'TypeScript');
|
||||
expect(results).toHaveLength(1);
|
||||
expect(results[0]!.content).toBe('TypeScript is popular');
|
||||
});
|
||||
|
||||
it('should respect limit option', async () => {
|
||||
const results = await adapter.searchInsights('u1', 'TypeScript', { limit: 1 });
|
||||
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);
|
||||
});
|
||||
});
|
||||
|
||||
/* ---- Lifecycle ---- */
|
||||
|
||||
describe('lifecycle', () => {
|
||||
it('should have name "keyword"', () => {
|
||||
expect(adapter.name).toBe('keyword');
|
||||
});
|
||||
|
||||
it('should have null embedder', () => {
|
||||
expect(adapter.embedder).toBeNull();
|
||||
});
|
||||
|
||||
it('should close without error', async () => {
|
||||
await expect(adapter.close()).resolves.toBeUndefined();
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,199 @@
|
||||
import type { StorageAdapter } from '@mosaicstack/storage';
|
||||
import type {
|
||||
MemoryAdapter,
|
||||
MemoryConfig,
|
||||
NewInsight,
|
||||
Insight,
|
||||
InsightSearchResult,
|
||||
} from '../types.js';
|
||||
import type { EmbeddingProvider } from '../vector-store.js';
|
||||
|
||||
type KeywordConfig = Extract<MemoryConfig, { type: 'keyword' }>;
|
||||
|
||||
const PREFERENCES = 'preferences';
|
||||
const INSIGHTS = 'insights';
|
||||
|
||||
type PreferenceRecord = Record<string, unknown> & {
|
||||
id: string;
|
||||
userId: string;
|
||||
key: string;
|
||||
value: unknown;
|
||||
category: string;
|
||||
};
|
||||
|
||||
type InsightRecord = Record<string, unknown> & {
|
||||
id: string;
|
||||
userId: string;
|
||||
content: string;
|
||||
source: string;
|
||||
category: string;
|
||||
relevanceScore: number;
|
||||
metadata: Record<string, unknown>;
|
||||
createdAt: string;
|
||||
updatedAt?: string;
|
||||
decayedAt?: string;
|
||||
};
|
||||
|
||||
export class KeywordAdapter implements MemoryAdapter {
|
||||
readonly name = 'keyword';
|
||||
readonly embedder: EmbeddingProvider | null = null;
|
||||
|
||||
private storage: StorageAdapter;
|
||||
|
||||
constructor(config: KeywordConfig) {
|
||||
this.storage = config.storage;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* Preferences */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
async getPreference(userId: string, key: string): Promise<unknown | null> {
|
||||
const row = await this.storage.findOne<PreferenceRecord>(PREFERENCES, { userId, key });
|
||||
return row?.value ?? null;
|
||||
}
|
||||
|
||||
async setPreference(
|
||||
userId: string,
|
||||
key: string,
|
||||
value: unknown,
|
||||
category?: string,
|
||||
): Promise<void> {
|
||||
const existing = await this.storage.findOne<PreferenceRecord>(PREFERENCES, { userId, key });
|
||||
if (existing) {
|
||||
await this.storage.update(PREFERENCES, existing.id, {
|
||||
value,
|
||||
...(category !== undefined ? { category } : {}),
|
||||
});
|
||||
} else {
|
||||
await this.storage.create(PREFERENCES, {
|
||||
userId,
|
||||
key,
|
||||
value,
|
||||
category: category ?? 'general',
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
async deletePreference(userId: string, key: string): Promise<boolean> {
|
||||
const existing = await this.storage.findOne<PreferenceRecord>(PREFERENCES, { userId, key });
|
||||
if (!existing) return false;
|
||||
return this.storage.delete(PREFERENCES, existing.id);
|
||||
}
|
||||
|
||||
async listPreferences(
|
||||
userId: string,
|
||||
category?: string,
|
||||
): Promise<Array<{ key: string; value: unknown; category: string }>> {
|
||||
const filter: Record<string, unknown> = { userId };
|
||||
if (category !== undefined) filter.category = category;
|
||||
|
||||
const rows = await this.storage.find<PreferenceRecord>(PREFERENCES, filter);
|
||||
return rows.map((r) => ({ key: r.key, value: r.value, category: r.category }));
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* Insights */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
async storeInsight(insight: NewInsight): Promise<Insight> {
|
||||
const now = new Date();
|
||||
const row = await this.storage.create<Record<string, unknown>>(INSIGHTS, {
|
||||
userId: insight.userId,
|
||||
content: insight.content,
|
||||
source: insight.source,
|
||||
category: insight.category,
|
||||
relevanceScore: insight.relevanceScore,
|
||||
metadata: insight.metadata ?? {},
|
||||
createdAt: now.toISOString(),
|
||||
});
|
||||
|
||||
return {
|
||||
id: row.id,
|
||||
userId: insight.userId,
|
||||
content: insight.content,
|
||||
source: insight.source,
|
||||
category: insight.category,
|
||||
relevanceScore: insight.relevanceScore,
|
||||
metadata: insight.metadata,
|
||||
createdAt: now,
|
||||
};
|
||||
}
|
||||
|
||||
async getInsight(id: string): Promise<Insight | null> {
|
||||
const row = await this.storage.read<InsightRecord>(INSIGHTS, id);
|
||||
if (!row) return null;
|
||||
return toInsight(row);
|
||||
}
|
||||
|
||||
async searchInsights(
|
||||
userId: string,
|
||||
query: string,
|
||||
opts?: { limit?: number; embedding?: number[] },
|
||||
): Promise<InsightSearchResult[]> {
|
||||
const limit = opts?.limit ?? 10;
|
||||
const normalizedQuery = query.trim();
|
||||
const matchAll = normalizedQuery === '*';
|
||||
const words = matchAll
|
||||
? []
|
||||
: normalizedQuery
|
||||
.toLowerCase()
|
||||
.split(/\s+/)
|
||||
.filter((word) => word.length > 0);
|
||||
|
||||
if (words.length === 0 && !matchAll) return [];
|
||||
|
||||
const rows = await this.storage.find<InsightRecord>(INSIGHTS, { userId });
|
||||
|
||||
const scored: InsightSearchResult[] = [];
|
||||
for (const row of rows) {
|
||||
const content = row.content.toLowerCase();
|
||||
let score = matchAll ? 1 : 0;
|
||||
for (const word of words) {
|
||||
if (content.includes(word)) score++;
|
||||
}
|
||||
if (score > 0) {
|
||||
scored.push({
|
||||
id: row.id,
|
||||
content: row.content,
|
||||
score,
|
||||
metadata: row.metadata ?? undefined,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
scored.sort((a, b) => b.score - a.score);
|
||||
return scored.slice(0, limit);
|
||||
}
|
||||
|
||||
async deleteInsight(id: string): Promise<boolean> {
|
||||
return this.storage.delete(INSIGHTS, id);
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* Lifecycle */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
async close(): Promise<void> {
|
||||
// no-op — storage adapter manages its own lifecycle
|
||||
}
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* Helpers */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
function toInsight(row: InsightRecord): Insight {
|
||||
return {
|
||||
id: row.id,
|
||||
userId: row.userId,
|
||||
content: row.content,
|
||||
source: row.source,
|
||||
category: row.category,
|
||||
relevanceScore: row.relevanceScore,
|
||||
metadata: row.metadata ?? undefined,
|
||||
createdAt: new Date(row.createdAt),
|
||||
updatedAt: row.updatedAt ? new Date(row.updatedAt) : undefined,
|
||||
decayedAt: row.decayedAt ? new Date(row.decayedAt) : undefined,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,177 @@
|
||||
import { createDb, type DbHandle } from '@mosaicstack/db';
|
||||
import type {
|
||||
MemoryAdapter,
|
||||
MemoryConfig,
|
||||
NewInsight as AdapterNewInsight,
|
||||
Insight as AdapterInsight,
|
||||
InsightSearchResult,
|
||||
} from '../types.js';
|
||||
import type { EmbeddingProvider } from '../vector-store.js';
|
||||
import {
|
||||
createPreferencesRepo,
|
||||
type PreferencesRepo,
|
||||
type Preference,
|
||||
type NewPreference,
|
||||
} from '../preferences.js';
|
||||
import {
|
||||
createInsightsRepo,
|
||||
type InsightsRepo,
|
||||
type NewInsight as DbNewInsight,
|
||||
} from '../insights.js';
|
||||
|
||||
type PgVectorConfig = Extract<MemoryConfig, { type: 'pgvector' }>;
|
||||
|
||||
export class PgVectorAdapter implements MemoryAdapter {
|
||||
readonly name = 'pgvector';
|
||||
readonly embedder: EmbeddingProvider | null;
|
||||
|
||||
private handle: DbHandle;
|
||||
private preferences: PreferencesRepo;
|
||||
private insights: InsightsRepo;
|
||||
|
||||
constructor(config: PgVectorConfig) {
|
||||
this.handle = createDb();
|
||||
this.preferences = createPreferencesRepo(this.handle.db);
|
||||
this.insights = createInsightsRepo(this.handle.db);
|
||||
this.embedder = config.embedder ?? null;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* Preferences */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
async getPreference(userId: string, key: string): Promise<unknown | null> {
|
||||
const row = await this.preferences.findByUserAndKey(userId, key);
|
||||
return row?.value ?? null;
|
||||
}
|
||||
|
||||
async setPreference(
|
||||
userId: string,
|
||||
key: string,
|
||||
value: unknown,
|
||||
category?: string,
|
||||
): Promise<void> {
|
||||
await this.preferences.upsert({
|
||||
userId,
|
||||
key,
|
||||
value,
|
||||
...(category ? { category: category as NewPreference['category'] } : {}),
|
||||
});
|
||||
}
|
||||
|
||||
async deletePreference(userId: string, key: string): Promise<boolean> {
|
||||
return this.preferences.remove(userId, key);
|
||||
}
|
||||
|
||||
async listPreferences(
|
||||
userId: string,
|
||||
category?: string,
|
||||
): Promise<Array<{ key: string; value: unknown; category: string }>> {
|
||||
const rows = category
|
||||
? await this.preferences.findByUserAndCategory(userId, category as Preference['category'])
|
||||
: await this.preferences.findByUser(userId);
|
||||
|
||||
return rows.map((r) => ({ key: r.key, value: r.value, category: r.category }));
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* Insights */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
async storeInsight(insight: AdapterNewInsight): Promise<AdapterInsight> {
|
||||
const row = await this.insights.create({
|
||||
userId: insight.userId,
|
||||
content: insight.content,
|
||||
source: insight.source as DbNewInsight['source'],
|
||||
category: insight.category as DbNewInsight['category'],
|
||||
relevanceScore: insight.relevanceScore,
|
||||
metadata: insight.metadata ?? {},
|
||||
embedding: insight.embedding ?? null,
|
||||
});
|
||||
|
||||
return toAdapterInsight(row);
|
||||
}
|
||||
|
||||
async getInsight(id: string): Promise<AdapterInsight | null> {
|
||||
// findById requires userId — search across all users via raw find
|
||||
// The adapter interface only takes id, so we pass an empty userId and rely on the id match.
|
||||
// Since the repo requires userId, we use a two-step approach.
|
||||
const row = await this.insights.findById(id, '');
|
||||
if (!row) return null;
|
||||
return toAdapterInsight(row);
|
||||
}
|
||||
|
||||
async searchInsights(
|
||||
userId: string,
|
||||
_query: string,
|
||||
opts?: { limit?: number; embedding?: number[] },
|
||||
): Promise<InsightSearchResult[]> {
|
||||
if (opts?.embedding) {
|
||||
const results = await this.insights.searchByEmbedding(
|
||||
userId,
|
||||
opts.embedding,
|
||||
opts.limit ?? 10,
|
||||
);
|
||||
return results.map((r) => ({
|
||||
id: r.insight.id,
|
||||
content: r.insight.content,
|
||||
score: 1 - r.distance,
|
||||
metadata: (r.insight.metadata as Record<string, unknown>) ?? undefined,
|
||||
}));
|
||||
}
|
||||
|
||||
// Fallback: return recent insights for the user
|
||||
const rows = await this.insights.findByUser(userId, opts?.limit ?? 10);
|
||||
return rows.map((r) => ({
|
||||
id: r.id,
|
||||
content: r.content,
|
||||
score: Number(r.relevanceScore),
|
||||
metadata: (r.metadata as Record<string, unknown>) ?? undefined,
|
||||
}));
|
||||
}
|
||||
|
||||
async deleteInsight(id: string): Promise<boolean> {
|
||||
// The repo requires userId — pass empty string since adapter interface only has id
|
||||
return this.insights.remove(id, '');
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* Lifecycle */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
async close(): Promise<void> {
|
||||
await this.handle.close();
|
||||
}
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* Helpers */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
function toAdapterInsight(row: {
|
||||
id: string;
|
||||
userId: string;
|
||||
content: string;
|
||||
source: string;
|
||||
category: string;
|
||||
relevanceScore: number;
|
||||
metadata: unknown;
|
||||
embedding: unknown;
|
||||
createdAt: Date;
|
||||
updatedAt: Date | null;
|
||||
decayedAt: Date | null;
|
||||
}): AdapterInsight {
|
||||
return {
|
||||
id: row.id,
|
||||
userId: row.userId,
|
||||
content: row.content,
|
||||
source: row.source,
|
||||
category: row.category,
|
||||
relevanceScore: row.relevanceScore,
|
||||
metadata: (row.metadata as Record<string, unknown>) ?? undefined,
|
||||
embedding: (row.embedding as number[]) ?? undefined,
|
||||
createdAt: row.createdAt,
|
||||
updatedAt: row.updatedAt ?? undefined,
|
||||
decayedAt: row.decayedAt ?? undefined,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,63 @@
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import { Command } from 'commander';
|
||||
import { registerMemoryCommand } from './cli.js';
|
||||
|
||||
/**
|
||||
* Smoke test — only verifies command wiring.
|
||||
* Does NOT open a database connection.
|
||||
*/
|
||||
describe('registerMemoryCommand', () => {
|
||||
function buildProgram(): Command {
|
||||
const program = new Command('mosaic');
|
||||
program.exitOverride(); // prevent process.exit during tests
|
||||
registerMemoryCommand(program);
|
||||
return program;
|
||||
}
|
||||
|
||||
it('registers a "memory" subcommand', () => {
|
||||
const program = buildProgram();
|
||||
const memory = program.commands.find((c) => c.name() === 'memory');
|
||||
expect(memory).toBeDefined();
|
||||
});
|
||||
|
||||
it('registers "memory search"', () => {
|
||||
const program = buildProgram();
|
||||
const memory = program.commands.find((c) => c.name() === 'memory')!;
|
||||
const search = memory.commands.find((c) => c.name() === 'search');
|
||||
expect(search).toBeDefined();
|
||||
});
|
||||
|
||||
it('registers "memory stats"', () => {
|
||||
const program = buildProgram();
|
||||
const memory = program.commands.find((c) => c.name() === 'memory')!;
|
||||
const stats = memory.commands.find((c) => c.name() === 'stats');
|
||||
expect(stats).toBeDefined();
|
||||
});
|
||||
|
||||
it('registers "memory insights list"', () => {
|
||||
const program = buildProgram();
|
||||
const memory = program.commands.find((c) => c.name() === 'memory')!;
|
||||
const insights = memory.commands.find((c) => c.name() === 'insights');
|
||||
expect(insights).toBeDefined();
|
||||
const list = insights!.commands.find((c) => c.name() === 'list');
|
||||
expect(list).toBeDefined();
|
||||
});
|
||||
|
||||
it('registers "memory preferences list"', () => {
|
||||
const program = buildProgram();
|
||||
const memory = program.commands.find((c) => c.name() === 'memory')!;
|
||||
const preferences = memory.commands.find((c) => c.name() === 'preferences');
|
||||
expect(preferences).toBeDefined();
|
||||
const list = preferences!.commands.find((c) => c.name() === 'list');
|
||||
expect(list).toBeDefined();
|
||||
});
|
||||
|
||||
it('"memory search" has --limit and --agent options', () => {
|
||||
const program = buildProgram();
|
||||
const memory = program.commands.find((c) => c.name() === 'memory')!;
|
||||
const search = memory.commands.find((c) => c.name() === 'search')!;
|
||||
const optNames = search.options.map((o) => o.long);
|
||||
expect(optNames).toContain('--limit');
|
||||
expect(optNames).toContain('--agent');
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,179 @@
|
||||
import type { Command } from 'commander';
|
||||
|
||||
import type { MemoryAdapter } from './types.js';
|
||||
|
||||
/**
|
||||
* Build and return a connected MemoryAdapter from a connection string or
|
||||
* the MEMORY_DB_URL / DATABASE_URL environment variable.
|
||||
*
|
||||
* For pgvector (postgres://...) the connection string is injected into
|
||||
* DATABASE_URL so that PgVectorAdapter's internal createDb() picks it up.
|
||||
*
|
||||
* Throws with a human-readable message if no connection info is available.
|
||||
*/
|
||||
async function resolveAdapter(dbOption: string | undefined): Promise<MemoryAdapter> {
|
||||
const connStr = dbOption ?? process.env['MEMORY_DB_URL'] ?? process.env['DATABASE_URL'];
|
||||
if (!connStr) {
|
||||
throw new Error(
|
||||
'No database connection string provided. ' +
|
||||
'Pass --db <connection-string> or set MEMORY_DB_URL / DATABASE_URL.',
|
||||
);
|
||||
}
|
||||
|
||||
// Lazy imports so the module loads cleanly without a live DB during smoke tests.
|
||||
const { createMemoryAdapter, registerMemoryAdapter } = await import('./factory.js');
|
||||
|
||||
if (connStr.startsWith('postgres') || connStr.startsWith('pg')) {
|
||||
// PgVectorAdapter reads DATABASE_URL via createDb() — inject it here.
|
||||
process.env['DATABASE_URL'] = connStr;
|
||||
|
||||
const { PgVectorAdapter } = await import('./adapters/pgvector.js');
|
||||
registerMemoryAdapter('pgvector', (cfg) => new PgVectorAdapter(cfg as never));
|
||||
return createMemoryAdapter({ type: 'pgvector' });
|
||||
}
|
||||
|
||||
// Keyword adapter backed by pglite storage; treat connStr as a data directory.
|
||||
const { KeywordAdapter } = await import('./adapters/keyword.js');
|
||||
const { createStorageAdapter, registerStorageAdapter } = await import('@mosaicstack/storage');
|
||||
const { PgliteAdapter } = await import('@mosaicstack/storage');
|
||||
|
||||
registerStorageAdapter('pglite', (cfg) => new PgliteAdapter(cfg as never));
|
||||
|
||||
const storage = createStorageAdapter({ type: 'pglite', dataDir: connStr });
|
||||
|
||||
registerMemoryAdapter('keyword', (cfg) => new KeywordAdapter(cfg as never));
|
||||
return createMemoryAdapter({ type: 'keyword', storage });
|
||||
}
|
||||
|
||||
/**
|
||||
* Register `memory` subcommands on an existing Commander program.
|
||||
* Follows the registerQualityRails pattern from @mosaicstack/quality-rails.
|
||||
*/
|
||||
export function registerMemoryCommand(parent: Command): void {
|
||||
const memory = parent.command('memory').description('Inspect and query the Mosaic memory layer');
|
||||
|
||||
// ── memory search <query> ──────────────────────────────────────────────
|
||||
memory
|
||||
.command('search <query>')
|
||||
.description('Semantic search over insights')
|
||||
.option('--db <connection-string>', 'Database connection string (or set MEMORY_DB_URL)')
|
||||
.option('--limit <n>', 'Maximum number of results', '10')
|
||||
.option('--agent <id>', 'Filter by agent / user ID')
|
||||
.action(async (query: string, opts: { db?: string; limit: string; agent?: string }) => {
|
||||
let adapter: MemoryAdapter | undefined;
|
||||
try {
|
||||
adapter = await resolveAdapter(opts.db);
|
||||
const limit = parseInt(opts.limit, 10);
|
||||
const userId = opts.agent ?? 'system';
|
||||
const results = await adapter.searchInsights(userId, query, { limit });
|
||||
|
||||
if (results.length === 0) {
|
||||
console.log('No insights found.');
|
||||
} else {
|
||||
for (const r of results) {
|
||||
console.log(`[${r.id}] (score=${r.score.toFixed(3)}) ${r.content}`);
|
||||
}
|
||||
}
|
||||
} catch (err) {
|
||||
console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
|
||||
process.exitCode = 1;
|
||||
} finally {
|
||||
await adapter?.close();
|
||||
}
|
||||
});
|
||||
|
||||
// ── memory stats ──────────────────────────────────────────────────────
|
||||
memory
|
||||
.command('stats')
|
||||
.description('Print memory tier info: adapter type, insight count, preference count')
|
||||
.option('--db <connection-string>', 'Database connection string (or set MEMORY_DB_URL)')
|
||||
.option('--agent <id>', 'User / agent ID scope for counts', 'system')
|
||||
.action(async (opts: { db?: string; agent: string }) => {
|
||||
let adapter: MemoryAdapter | undefined;
|
||||
try {
|
||||
adapter = await resolveAdapter(opts.db);
|
||||
|
||||
const adapterType = adapter.name;
|
||||
|
||||
const insightCount = await adapter
|
||||
.searchInsights(opts.agent, '', { limit: 100000 })
|
||||
.then((r) => r.length)
|
||||
.catch(() => -1);
|
||||
|
||||
const prefCount = await adapter
|
||||
.listPreferences(opts.agent)
|
||||
.then((r) => r.length)
|
||||
.catch(() => -1);
|
||||
|
||||
console.log(`adapter: ${adapterType}`);
|
||||
console.log(`insights: ${insightCount === -1 ? 'unavailable' : String(insightCount)}`);
|
||||
console.log(`preferences: ${prefCount === -1 ? 'unavailable' : String(prefCount)}`);
|
||||
} catch (err) {
|
||||
console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
|
||||
process.exitCode = 1;
|
||||
} finally {
|
||||
await adapter?.close();
|
||||
}
|
||||
});
|
||||
|
||||
// ── memory insights ───────────────────────────────────────────────────
|
||||
const insightsCmd = memory.command('insights').description('Manage insights');
|
||||
|
||||
insightsCmd
|
||||
.command('list')
|
||||
.description('List recent insights')
|
||||
.option('--db <connection-string>', 'Database connection string (or set MEMORY_DB_URL)')
|
||||
.option('--limit <n>', 'Maximum number of results', '20')
|
||||
.option('--agent <id>', 'User / agent ID scope', 'system')
|
||||
.action(async (opts: { db?: string; limit: string; agent: string }) => {
|
||||
let adapter: MemoryAdapter | undefined;
|
||||
try {
|
||||
adapter = await resolveAdapter(opts.db);
|
||||
const limit = parseInt(opts.limit, 10);
|
||||
const results = await adapter.searchInsights(opts.agent, '', { limit });
|
||||
|
||||
if (results.length === 0) {
|
||||
console.log('No insights found.');
|
||||
} else {
|
||||
for (const r of results) {
|
||||
console.log(`[${r.id}] ${r.content}`);
|
||||
}
|
||||
}
|
||||
} catch (err) {
|
||||
console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
|
||||
process.exitCode = 1;
|
||||
} finally {
|
||||
await adapter?.close();
|
||||
}
|
||||
});
|
||||
|
||||
// ── memory preferences ────────────────────────────────────────────────
|
||||
const prefsCmd = memory.command('preferences').description('Manage stored preferences');
|
||||
|
||||
prefsCmd
|
||||
.command('list')
|
||||
.description('List stored preferences')
|
||||
.option('--db <connection-string>', 'Database connection string (or set MEMORY_DB_URL)')
|
||||
.option('--agent <id>', 'User / agent ID scope', 'system')
|
||||
.option('--category <cat>', 'Filter by category')
|
||||
.action(async (opts: { db?: string; agent: string; category?: string }) => {
|
||||
let adapter: MemoryAdapter | undefined;
|
||||
try {
|
||||
adapter = await resolveAdapter(opts.db);
|
||||
const prefs = await adapter.listPreferences(opts.agent, opts.category);
|
||||
|
||||
if (prefs.length === 0) {
|
||||
console.log('No preferences found.');
|
||||
} else {
|
||||
for (const p of prefs) {
|
||||
console.log(`[${p.category}] ${p.key} = ${JSON.stringify(p.value)}`);
|
||||
}
|
||||
}
|
||||
} catch (err) {
|
||||
console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
|
||||
process.exitCode = 1;
|
||||
} finally {
|
||||
await adapter?.close();
|
||||
}
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
import type { MemoryAdapter, MemoryConfig } from './types.js';
|
||||
|
||||
type MemoryType = MemoryConfig['type'];
|
||||
|
||||
const registry = new Map<MemoryType, (config: MemoryConfig) => MemoryAdapter>();
|
||||
|
||||
export function registerMemoryAdapter(
|
||||
type: MemoryType,
|
||||
factory: (config: MemoryConfig) => MemoryAdapter,
|
||||
): void {
|
||||
registry.set(type, factory);
|
||||
}
|
||||
|
||||
export function createMemoryAdapter(config: MemoryConfig): MemoryAdapter {
|
||||
const factory = registry.get(config.type);
|
||||
if (!factory) throw new Error(`No adapter registered for type: ${config.type}`);
|
||||
return factory(config);
|
||||
}
|
||||
@@ -0,0 +1,47 @@
|
||||
export { createMemory, type Memory } from './memory.js';
|
||||
export { registerMemoryCommand } from './cli.js';
|
||||
export {
|
||||
createPreferencesRepo,
|
||||
type PreferencesRepo,
|
||||
type Preference,
|
||||
type NewPreference,
|
||||
} from './preferences.js';
|
||||
export {
|
||||
createInsightsRepo,
|
||||
type InsightsRepo,
|
||||
type Insight,
|
||||
type NewInsight,
|
||||
type SearchResult,
|
||||
} from './insights.js';
|
||||
export type { VectorStore, VectorSearchResult, EmbeddingProvider } from './vector-store.js';
|
||||
export type {
|
||||
MemoryAdapter,
|
||||
MemoryConfig,
|
||||
NewInsight as AdapterNewInsight,
|
||||
Insight as AdapterInsight,
|
||||
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';
|
||||
|
||||
// Auto-register adapters at module load time
|
||||
import { registerMemoryAdapter } from './factory.js';
|
||||
import { PgVectorAdapter } from './adapters/pgvector.js';
|
||||
import { KeywordAdapter } from './adapters/keyword.js';
|
||||
import type { MemoryConfig } from './types.js';
|
||||
|
||||
registerMemoryAdapter('pgvector', (config: MemoryConfig) => {
|
||||
return new PgVectorAdapter(config as Extract<MemoryConfig, { type: 'pgvector' }>);
|
||||
});
|
||||
|
||||
registerMemoryAdapter('keyword', (config: MemoryConfig) => {
|
||||
return new KeywordAdapter(config as Extract<MemoryConfig, { type: 'keyword' }>);
|
||||
});
|
||||
@@ -0,0 +1,124 @@
|
||||
import { eq, and, desc, sql, lt, type Db, insights } from '@mosaicstack/db';
|
||||
|
||||
export type Insight = typeof insights.$inferSelect;
|
||||
export type NewInsight = typeof insights.$inferInsert;
|
||||
|
||||
export interface SearchResult {
|
||||
insight: Insight;
|
||||
distance: number;
|
||||
}
|
||||
|
||||
export function createInsightsRepo(db: Db) {
|
||||
return {
|
||||
async findByUser(userId: string, limit = 50): Promise<Insight[]> {
|
||||
return db
|
||||
.select()
|
||||
.from(insights)
|
||||
.where(eq(insights.userId, userId))
|
||||
.orderBy(desc(insights.createdAt))
|
||||
.limit(limit);
|
||||
},
|
||||
|
||||
async findById(id: string, userId: string): Promise<Insight | undefined> {
|
||||
const rows = await db
|
||||
.select()
|
||||
.from(insights)
|
||||
.where(and(eq(insights.id, id), eq(insights.userId, userId)));
|
||||
return rows[0];
|
||||
},
|
||||
|
||||
async create(data: NewInsight): Promise<Insight> {
|
||||
const rows = await db.insert(insights).values(data).returning();
|
||||
return rows[0]!;
|
||||
},
|
||||
|
||||
async update(
|
||||
id: string,
|
||||
userId: string,
|
||||
data: Partial<NewInsight>,
|
||||
): Promise<Insight | undefined> {
|
||||
const rows = await db
|
||||
.update(insights)
|
||||
.set({ ...data, updatedAt: new Date() })
|
||||
.where(and(eq(insights.id, id), eq(insights.userId, userId)))
|
||||
.returning();
|
||||
return rows[0];
|
||||
},
|
||||
|
||||
async remove(id: string, userId: string): Promise<boolean> {
|
||||
const rows = await db
|
||||
.delete(insights)
|
||||
.where(and(eq(insights.id, id), eq(insights.userId, userId)))
|
||||
.returning();
|
||||
return rows.length > 0;
|
||||
},
|
||||
|
||||
/**
|
||||
* Semantic search using pgvector cosine distance.
|
||||
* Requires the vector extension and an embedding for the query.
|
||||
*/
|
||||
async searchByEmbedding(
|
||||
userId: string,
|
||||
queryEmbedding: number[],
|
||||
limit = 10,
|
||||
maxDistance = 0.8,
|
||||
): Promise<SearchResult[]> {
|
||||
const embeddingStr = `[${queryEmbedding.join(',')}]`;
|
||||
const rows = await db.execute(sql`
|
||||
SELECT *,
|
||||
(embedding <=> ${embeddingStr}::vector) AS distance
|
||||
FROM insights
|
||||
WHERE user_id = ${userId}
|
||||
AND embedding IS NOT NULL
|
||||
AND (embedding <=> ${embeddingStr}::vector) < ${maxDistance}
|
||||
ORDER BY distance ASC
|
||||
LIMIT ${limit}
|
||||
`);
|
||||
|
||||
return rows as unknown as SearchResult[];
|
||||
},
|
||||
|
||||
/**
|
||||
* Decay relevance scores for old insights that haven't been accessed recently.
|
||||
* Scoped to a specific user to prevent cross-user data mutation.
|
||||
*/
|
||||
async decayOldInsights(userId: string, olderThan: Date, decayFactor = 0.95): Promise<number> {
|
||||
const result = await db
|
||||
.update(insights)
|
||||
.set({
|
||||
relevanceScore: sql`${insights.relevanceScore} * ${decayFactor}`,
|
||||
decayedAt: new Date(),
|
||||
updatedAt: new Date(),
|
||||
})
|
||||
.where(
|
||||
and(
|
||||
eq(insights.userId, userId),
|
||||
lt(insights.updatedAt, olderThan),
|
||||
sql`${insights.relevanceScore} > 0.1`,
|
||||
),
|
||||
)
|
||||
.returning();
|
||||
return result.length;
|
||||
},
|
||||
|
||||
/**
|
||||
* Decay relevance scores for all users' old insights.
|
||||
* This is a system-level maintenance operation intended for scheduled cron jobs only.
|
||||
* Do NOT expose this through user-facing API endpoints.
|
||||
*/
|
||||
async decayAllInsights(olderThan: Date, decayFactor = 0.95): Promise<number> {
|
||||
const result = await db
|
||||
.update(insights)
|
||||
.set({
|
||||
relevanceScore: sql`${insights.relevanceScore} * ${decayFactor}`,
|
||||
decayedAt: new Date(),
|
||||
updatedAt: new Date(),
|
||||
})
|
||||
.where(and(lt(insights.updatedAt, olderThan), sql`${insights.relevanceScore} > 0.1`))
|
||||
.returning();
|
||||
return result.length;
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
export type InsightsRepo = ReturnType<typeof createInsightsRepo>;
|
||||
@@ -0,0 +1,15 @@
|
||||
import type { Db } from '@mosaicstack/db';
|
||||
import { createPreferencesRepo, type PreferencesRepo } from './preferences.js';
|
||||
import { createInsightsRepo, type InsightsRepo } from './insights.js';
|
||||
|
||||
export interface Memory {
|
||||
preferences: PreferencesRepo;
|
||||
insights: InsightsRepo;
|
||||
}
|
||||
|
||||
export function createMemory(db: Db): Memory {
|
||||
return {
|
||||
preferences: createPreferencesRepo(db),
|
||||
insights: createInsightsRepo(db),
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,147 @@
|
||||
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: NewInsight): Promise<Insight> => ({
|
||||
...value,
|
||||
id: '1',
|
||||
createdAt: new Date(),
|
||||
}),
|
||||
),
|
||||
searchInsights: vi.fn(async (): Promise<InsightSearchResult[]> => []),
|
||||
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 configured namespace storage across server-derived tenant, owner, and session scopes', async () => {
|
||||
const memory = adapter();
|
||||
const plugin = createOperatorMemoryPlugin({
|
||||
adapter: memory,
|
||||
instanceId: 'Nova',
|
||||
namespace: 'operator-memory',
|
||||
redact: (value) => value,
|
||||
});
|
||||
await plugin.capture(
|
||||
{ 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: 'session-a' },
|
||||
{ content: 'two', source: 'test', category: 'note' },
|
||||
);
|
||||
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"]',
|
||||
]);
|
||||
});
|
||||
|
||||
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([
|
||||
{ id: '1', content: 'x', score: 1, metadata: { source: 'project' } },
|
||||
]);
|
||||
const plugin = createOperatorMemoryPlugin({
|
||||
adapter: memory,
|
||||
instanceId: 'Nova',
|
||||
namespace: 'operator-memory',
|
||||
redact: (value) => value,
|
||||
});
|
||||
|
||||
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('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({
|
||||
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',
|
||||
},
|
||||
}),
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,154 @@
|
||||
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;
|
||||
readonly ownerId: string;
|
||||
readonly sessionId: string;
|
||||
}
|
||||
|
||||
export interface OperatorMemoryConfig {
|
||||
/** 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;
|
||||
}
|
||||
|
||||
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<Insight>;
|
||||
search(
|
||||
scope: OperatorMemoryScope,
|
||||
query: string,
|
||||
limit?: number,
|
||||
): Promise<OperatorMemoryResult[]>;
|
||||
recent(scope: OperatorMemoryScope, limit?: number): Promise<OperatorMemoryResult[]>;
|
||||
stats(scope: OperatorMemoryScope): Promise<{ namespace: string; resultCount: number }>;
|
||||
startupContext(scope: OperatorMemoryScope): Promise<OperatorMemoryResult[]>;
|
||||
}
|
||||
|
||||
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,
|
||||
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 {
|
||||
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 pluginConfig = normalizeConfig(config);
|
||||
const mapResult = (result: InsightSearchResult): OperatorMemoryResult => ({
|
||||
...result,
|
||||
provenance: {
|
||||
instanceId: pluginConfig.instanceId,
|
||||
namespace: pluginConfig.namespace,
|
||||
source: String(result.metadata?.['source'] ?? 'retrieval'),
|
||||
},
|
||||
});
|
||||
const search = async (
|
||||
scope: OperatorMemoryScope,
|
||||
query: string,
|
||||
limit = 10,
|
||||
): Promise<OperatorMemoryResult[]> =>
|
||||
(
|
||||
await pluginConfig.adapter.searchInsights(
|
||||
scopedUserId(scope, pluginConfig.namespace),
|
||||
query,
|
||||
{
|
||||
limit,
|
||||
},
|
||||
)
|
||||
).map(mapResult);
|
||||
return {
|
||||
async capture(scope, input) {
|
||||
return pluginConfig.adapter.storeInsight({
|
||||
userId: scopedUserId(scope, pluginConfig.namespace),
|
||||
content: pluginConfig.redact(input.content),
|
||||
source: input.source,
|
||||
category: input.category,
|
||||
relevanceScore: 1,
|
||||
metadata: {
|
||||
namespace: pluginConfig.namespace,
|
||||
instanceId: pluginConfig.instanceId,
|
||||
source: input.source,
|
||||
},
|
||||
});
|
||||
},
|
||||
search,
|
||||
async recent(scope, limit = 10) {
|
||||
return search(scope, '*', limit);
|
||||
},
|
||||
async stats(scope) {
|
||||
return {
|
||||
namespace: pluginConfig.namespace,
|
||||
resultCount: (await search(scope, '*', 100)).length,
|
||||
};
|
||||
},
|
||||
async startupContext(scope) {
|
||||
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);
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,59 @@
|
||||
import { eq, and, type Db, preferences } from '@mosaicstack/db';
|
||||
|
||||
export type Preference = typeof preferences.$inferSelect;
|
||||
export type NewPreference = typeof preferences.$inferInsert;
|
||||
|
||||
export function createPreferencesRepo(db: Db) {
|
||||
return {
|
||||
async findByUser(userId: string): Promise<Preference[]> {
|
||||
return db.select().from(preferences).where(eq(preferences.userId, userId));
|
||||
},
|
||||
|
||||
async findByUserAndKey(userId: string, key: string): Promise<Preference | undefined> {
|
||||
const rows = await db
|
||||
.select()
|
||||
.from(preferences)
|
||||
.where(and(eq(preferences.userId, userId), eq(preferences.key, key)));
|
||||
return rows[0];
|
||||
},
|
||||
|
||||
async findByUserAndCategory(
|
||||
userId: string,
|
||||
category: Preference['category'],
|
||||
): Promise<Preference[]> {
|
||||
return db
|
||||
.select()
|
||||
.from(preferences)
|
||||
.where(and(eq(preferences.userId, userId), eq(preferences.category, category)));
|
||||
},
|
||||
|
||||
async upsert(data: NewPreference): Promise<Preference> {
|
||||
const existing = await db
|
||||
.select()
|
||||
.from(preferences)
|
||||
.where(and(eq(preferences.userId, data.userId), eq(preferences.key, data.key)));
|
||||
|
||||
if (existing[0]) {
|
||||
const rows = await db
|
||||
.update(preferences)
|
||||
.set({ value: data.value, category: data.category, updatedAt: new Date() })
|
||||
.where(eq(preferences.id, existing[0].id))
|
||||
.returning();
|
||||
return rows[0]!;
|
||||
}
|
||||
|
||||
const rows = await db.insert(preferences).values(data).returning();
|
||||
return rows[0]!;
|
||||
},
|
||||
|
||||
async remove(userId: string, key: string): Promise<boolean> {
|
||||
const rows = await db
|
||||
.delete(preferences)
|
||||
.where(and(eq(preferences.userId, userId), eq(preferences.key, key)))
|
||||
.returning();
|
||||
return rows.length > 0;
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
export type PreferencesRepo = ReturnType<typeof createPreferencesRepo>;
|
||||
@@ -0,0 +1,77 @@
|
||||
export type { EmbeddingProvider, VectorSearchResult } from './vector-store.js';
|
||||
import type { EmbeddingProvider } from './vector-store.js';
|
||||
import type { StorageAdapter } from '@mosaicstack/storage';
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* Insight types (adapter-level, decoupled from Drizzle schema) */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
export interface NewInsight {
|
||||
userId: string;
|
||||
content: string;
|
||||
source: string;
|
||||
category: string;
|
||||
relevanceScore: number;
|
||||
metadata?: Record<string, unknown>;
|
||||
embedding?: number[];
|
||||
}
|
||||
|
||||
export interface Insight extends NewInsight {
|
||||
id: string;
|
||||
createdAt: Date;
|
||||
updatedAt?: Date;
|
||||
decayedAt?: Date;
|
||||
}
|
||||
|
||||
export interface InsightSearchResult {
|
||||
id: string;
|
||||
content: string;
|
||||
score: number;
|
||||
metadata?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* MemoryAdapter interface */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
export interface MemoryAdapter {
|
||||
readonly name: string;
|
||||
|
||||
// Preferences
|
||||
getPreference(userId: string, key: string): Promise<unknown | null>;
|
||||
setPreference(userId: string, key: string, value: unknown, category?: string): Promise<void>;
|
||||
deletePreference(userId: string, key: string): Promise<boolean>;
|
||||
listPreferences(
|
||||
userId: string,
|
||||
category?: string,
|
||||
): Promise<Array<{ key: string; value: unknown; category: string }>>;
|
||||
|
||||
// Insights
|
||||
storeInsight(insight: NewInsight): Promise<Insight>;
|
||||
getInsight(id: string): Promise<Insight | null>;
|
||||
/**
|
||||
* 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,
|
||||
opts?: { limit?: number; embedding?: number[] },
|
||||
): Promise<InsightSearchResult[]>;
|
||||
deleteInsight(id: string): Promise<boolean>;
|
||||
|
||||
// Embedding
|
||||
readonly embedder: EmbeddingProvider | null;
|
||||
|
||||
// Lifecycle
|
||||
close(): Promise<void>;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* MemoryConfig */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
export type MemoryConfig =
|
||||
| { type: 'pgvector'; embedder?: EmbeddingProvider }
|
||||
| { type: 'sqlite-vec'; embedder?: EmbeddingProvider }
|
||||
| { type: 'keyword'; storage: StorageAdapter };
|
||||
@@ -0,0 +1,39 @@
|
||||
/**
|
||||
* VectorStore interface — abstraction over pgvector that allows future
|
||||
* swap to Qdrant, Pinecone, etc.
|
||||
*/
|
||||
export interface VectorStore {
|
||||
/** Store an embedding with an associated document ID. */
|
||||
store(documentId: string, embedding: number[], metadata?: Record<string, unknown>): Promise<void>;
|
||||
|
||||
/** Search for similar embeddings, returning document IDs and distances. */
|
||||
search(
|
||||
queryEmbedding: number[],
|
||||
limit?: number,
|
||||
filter?: Record<string, unknown>,
|
||||
): Promise<VectorSearchResult[]>;
|
||||
|
||||
/** Delete an embedding by document ID. */
|
||||
remove(documentId: string): Promise<void>;
|
||||
}
|
||||
|
||||
export interface VectorSearchResult {
|
||||
documentId: string;
|
||||
distance: number;
|
||||
metadata?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/**
|
||||
* EmbeddingProvider interface — generates embeddings from text.
|
||||
* Implemented by the gateway using the configured LLM provider.
|
||||
*/
|
||||
export interface EmbeddingProvider {
|
||||
/** Generate an embedding vector for the given text. */
|
||||
embed(text: string): Promise<number[]>;
|
||||
|
||||
/** Generate embeddings for multiple texts in batch. */
|
||||
embedBatch(texts: string[]): Promise<number[][]>;
|
||||
|
||||
/** The dimensionality of the embeddings this provider generates. */
|
||||
dimensions: number;
|
||||
}
|
||||
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"extends": "../../tsconfig.base.json",
|
||||
"compilerOptions": {
|
||||
"outDir": "dist",
|
||||
"rootDir": "src"
|
||||
},
|
||||
"include": ["src/**/*"],
|
||||
"exclude": ["node_modules", "dist"]
|
||||
}
|
||||
@@ -0,0 +1,8 @@
|
||||
import { defineConfig } from 'vitest/config';
|
||||
|
||||
export default defineConfig({
|
||||
test: {
|
||||
globals: true,
|
||||
environment: 'node',
|
||||
},
|
||||
});
|
||||
Reference in New Issue
Block a user