@moxxy/plugin-memory 0.27.0

package/dist/store.js

@@ -0,0 +1,220 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { createMutex } from '@moxxy/sdk';
+import { moxxyPath, writeFileAtomic } from '@moxxy/sdk/server';
+import { renderFrontmatter } from './parse.js';
+import { TfIdfEmbedder } from './tfidf.js';
+import { EmbeddingIndex } from './embedding-cache.js';
+import { memoryFrontmatterSchema, } from './store/types.js';
+import { isEnoent, listEntries, readEntry, safeRead, writeIndex } from './store/io.js';
+import { rankByKeywords, recallVector } from './store/search.js';
+export { memoryTypeSchema, memoryFrontmatterSchema, } from './store/types.js';
+/** Default soft cap — see {@link MemoryStoreOptions.maxMemories}. */
+export const DEFAULT_MAX_MEMORIES = 500;
+export function defaultMemoryDir() {
+    return moxxyPath('memory');
+}
+export class MemoryStore {
+    dir;
+    resolveEmbedder;
+    persistOpt;
+    // Embedder + index are resolved LAZILY on first recall (memoized), so a host
+    // that selects the embedder from a registry after plugins load can pass a
+    // resolver here without the store needing to be built after the session.
+    embedderCache;
+    indexCache;
+    // Per-instance mutex. save/update/forget/recall each read-modify-write the
+    // entry file, MEMORY.md, and the embedding index; without serialization two
+    // overlapping calls clobber MEMORY.md and race the embedding cache.
+    mutex = createMutex();
+    maxMemories;
+    // In-memory MEMORY.md rows (name → frontmatter+path), hydrated lazily from
+    // disk ONCE, then maintained incrementally on save/update/forget — so a
+    // write no longer re-reads + re-parses every memory file to rebuild the
+    // index (the old O(N)-per-write rebuild). Entries written to the dir by
+    // other processes appear after the next hydration (new store instance);
+    // within one process this store is the only writer, same assumption the
+    // mutex already makes.
+    indexRows = null;
+    constructor(opts = {}) {
+        this.dir = opts.dir ?? defaultMemoryDir();
+        this.persistOpt = opts.persistEmbeddings;
+        this.maxMemories = opts.maxMemories ?? DEFAULT_MAX_MEMORIES;
+        const e = opts.embedder;
+        if (typeof e === 'function') {
+            this.resolveEmbedder = e;
+        }
+        else if (e === null) {
+            this.resolveEmbedder = () => null;
+        }
+        else if (e !== undefined) {
+            this.resolveEmbedder = () => e;
+        }
+        else {
+            const tfidf = new TfIdfEmbedder();
+            this.resolveEmbedder = () => tfidf;
+        }
+    }
+    getEmbedder() {
+        if (this.embedderCache === undefined)
+            this.embedderCache = this.resolveEmbedder();
+        return this.embedderCache;
+    }
+    getIndex() {
+        if (this.indexCache === undefined) {
+            const emb = this.getEmbedder();
+            // TF-IDF's vocab depends on the whole corpus, so per-entry caching is
+            // useless — recompute every recall. For neural embedders, caching is
+            // a big win since each entry's vector is corpus-independent.
+            const isTfIdf = emb instanceof TfIdfEmbedder;
+            const persist = this.persistOpt ?? (emb !== null && !isTfIdf);
+            this.indexCache = persist && emb ? new EmbeddingIndex(this.dir, emb.name, emb.dim) : null;
+        }
+        return this.indexCache;
+    }
+    get embedderName() {
+        return this.getEmbedder()?.name ?? 'keyword';
+    }
+    list(filterType) {
+        return listEntries(this.dir, filterType);
+    }
+    get(name) {
+        // fileFor() throws synchronously on a traversal/separator name; surface it
+        // as a rejected promise so callers see one consistent (async) failure mode
+        // instead of an exception thrown before the promise is even constructed.
+        let file;
+        try {
+            file = this.fileFor(name);
+        }
+        catch (err) {
+            return Promise.reject(err);
+        }
+        return readEntry(file);
+    }
+    save(input) {
+        return this.mutex.run(() => this.writeEntry(input));
+    }
+    update(name, patch) {
+        // Read-modify-write under the mutex; calls the internal (unserialized)
+        // writer so it doesn't deadlock on its own chain.
+        return this.mutex.run(async () => {
+            const existing = await readEntry(this.fileFor(name));
+            if (!existing)
+                return null;
+            const mergedTags = patch.tags ?? existing.frontmatter.tags;
+            return this.writeEntry({
+                name: existing.frontmatter.name,
+                type: existing.frontmatter.type,
+                description: patch.description ?? existing.frontmatter.description,
+                ...(mergedTags ? { tags: [...mergedTags] } : {}),
+                body: patch.body ?? existing.body,
+            });
+        });
+    }
+    forget(name) {
+        return this.mutex.run(async () => {
+            const filePath = this.fileFor(name);
+            try {
+                await fs.unlink(filePath);
+                const rows = await this.rows();
+                rows.delete(name);
+                await this.writeIndexFromRows(rows);
+                return true;
+            }
+            catch (err) {
+                if (isEnoent(err))
+                    return false;
+                throw err;
+            }
+        });
+    }
+    /**
+     * Soft-cap status (see {@link MemoryStoreOptions.maxMemories}). `over` means
+     * the store holds more entries than the cap; nothing is ever evicted.
+     */
+    async capStatus() {
+        // Read the index-row cache under the mutex: writeEntry/forget mutate it
+        // while holding the same lock, so a concurrent capStatus() outside the lock
+        // could observe a half-updated map or trigger a redundant disk hydration.
+        const size = await this.mutex.run(async () => (await this.rows()).size);
+        return { count: size, max: this.maxMemories, over: size > this.maxMemories };
+    }
+    /** The actual entry write. NOT serialized — callers hold the mutex. */
+    async writeEntry(input) {
+        await fs.mkdir(this.dir, { recursive: true });
+        const filePath = this.fileFor(input.name);
+        const existing = await safeRead(filePath);
+        const now = new Date().toISOString();
+        const createdAt = existing?.frontmatter.createdAt ?? now;
+        const frontmatter = memoryFrontmatterSchema.parse({
+            name: input.name,
+            type: input.type,
+            description: input.description,
+            ...(input.tags !== undefined ? { tags: input.tags } : {}),
+            createdAt,
+            updatedAt: now,
+        });
+        const content = `${renderFrontmatter(frontmatter)}\n\n${input.body.trimEnd()}\n`;
+        await writeFileAtomic(filePath, content);
+        // Incremental index maintenance: update THIS entry's row and re-render
+        // MEMORY.md from the in-memory rows — no per-write re-read of every file.
+        const rows = await this.rows();
+        rows.set(frontmatter.name, { frontmatter, path: filePath });
+        await this.writeIndexFromRows(rows);
+        if (rows.size > this.maxMemories) {
+            // Warn-only soft cap — eviction would silently destroy saved knowledge.
+            console.warn(`[plugin-memory] memory store holds ${rows.size} entries (soft cap ${this.maxMemories}). ` +
+                `Nothing is evicted; consider consolidating or forgetting stale memories.`);
+        }
+        return { frontmatter, body: input.body.trimEnd(), path: filePath };
+    }
+    /**
+     * Search memories by a free-text query. Uses vector cosine similarity when
+     * an EmbeddingProvider is configured (the default is the built-in TF-IDF
+     * embedder); falls back to keyword scoring when `mode: 'keyword'` or when
+     * no embedder is wired.
+     */
+    async recall(query, opts = {}) {
+        const limit = opts.limit ?? 5;
+        const mode = opts.mode ?? 'auto';
+        const all = await this.list(opts.type);
+        if (all.length === 0)
+            return [];
+        const embedder = this.getEmbedder();
+        const useVector = mode === 'vector' || (mode === 'auto' && embedder !== null);
+        if (useVector && embedder) {
+            return recallVector(all, query, limit, embedder, this.getIndex(), this.mutex);
+        }
+        return rankByKeywords(all, query, limit);
+    }
+    fileFor(name) {
+        // Belt-and-suspenders containment: the tool schemas restrict `name` to a
+        // slug, but the store is a public API and the inproc isolator can't enforce
+        // the fs glob — so refuse any name that escapes the memory dir (traversal,
+        // absolute path, or embedded separators) rather than unlink/read outside it.
+        const root = path.resolve(this.dir);
+        const resolved = path.resolve(root, `${name}.md`);
+        // The resolved file must live DIRECTLY in `root` (no nested or escaped path).
+        if (path.dirname(resolved) !== root) {
+            throw new Error(`invalid memory name: ${name}`);
+        }
+        return resolved;
+    }
+    /** Hydrate the index-row cache from disk once, then serve it from memory.
+     *  Callers that mutate it hold the store mutex (writeEntry/forget). */
+    async rows() {
+        if (!this.indexRows) {
+            const entries = await listEntries(this.dir);
+            this.indexRows = new Map(entries.map((e) => [e.frontmatter.name, { frontmatter: e.frontmatter, path: e.path }]));
+        }
+        return this.indexRows;
+    }
+    /** Render MEMORY.md from the cached rows, name-sorted so the output is
+     *  deterministic (readdir order, which the old full rebuild inherited,
+     *  was platform-dependent anyway). */
+    writeIndexFromRows(rows) {
+        const sorted = [...rows.values()].sort((a, b) => a.frontmatter.name.localeCompare(b.frontmatter.name));
+        return writeIndex(this.dir, sorted);
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}

package/dist/tfidf.d.ts

@@ -0,0 +1,29 @@
+import type { EmbeddingProvider } from '@moxxy/sdk';
+/**
+ * Built-in zero-dependency TF-IDF embedder. Computes a sparse-but-stored-dense
+ * vector per text. Builds vocabulary lazily from the corpus you provide via
+ * `fit()`. Once fit, `embed()` produces vectors over that fixed vocabulary.
+ *
+ * Quality is meh by neural-embedding standards but: deterministic, runs in
+ * <1ms for hundreds of entries, no network, no model download, no API key.
+ * Real semantic embeddings can be wired by passing a different EmbeddingProvider
+ * to MemoryStore.
+ */
+export declare class TfIdfEmbedder implements EmbeddingProvider {
+    readonly name = "tfidf";
+    private vocab;
+    private vocabIndex;
+    private idf;
+    get dim(): number | 'dynamic';
+    /**
+     * Compute vocabulary + IDF weights from the corpus. Call this whenever the
+     * source corpus changes; embed() must be called only after fit().
+     */
+    fit(corpus: ReadonlyArray<string>): void;
+    embedSync(text: string): number[];
+    embed(texts: ReadonlyArray<string>): Promise<ReadonlyArray<ReadonlyArray<number>>>;
+}
+export declare function cosineSimilarity(a: ReadonlyArray<number>, b: ReadonlyArray<number>): number;
+export declare function l2Normalize(v: number[]): number[];
+export declare function tokenize(text: string): string[];
+//# sourceMappingURL=tfidf.d.ts.map

package/dist/tfidf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tfidf.d.ts","sourceRoot":"","sources":["../src/tfidf.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;;;;;;GASG;AACH,qBAAa,aAAc,YAAW,iBAAiB;IACrD,QAAQ,CAAC,IAAI,WAAW;IACxB,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,UAAU,CAA6B;IAC/C,OAAO,CAAC,GAAG,CAA6B;IAExC,IAAI,GAAG,IAAI,MAAM,GAAG,SAAS,CAE5B;IAED;;;OAGG;IACH,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,IAAI;IAwBxC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;IAiB3B,KAAK,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;CAGzF;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,MAAM,CAK3F;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAMjD;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAO/C"}

package/dist/tfidf.js

@@ -0,0 +1,103 @@
+/**
+ * Built-in zero-dependency TF-IDF embedder. Computes a sparse-but-stored-dense
+ * vector per text. Builds vocabulary lazily from the corpus you provide via
+ * `fit()`. Once fit, `embed()` produces vectors over that fixed vocabulary.
+ *
+ * Quality is meh by neural-embedding standards but: deterministic, runs in
+ * <1ms for hundreds of entries, no network, no model download, no API key.
+ * Real semantic embeddings can be wired by passing a different EmbeddingProvider
+ * to MemoryStore.
+ */
+export class TfIdfEmbedder {
+    name = 'tfidf';
+    vocab = [];
+    vocabIndex = new Map();
+    idf = [];
+    get dim() {
+        return this.vocab.length || 'dynamic';
+    }
+    /**
+     * Compute vocabulary + IDF weights from the corpus. Call this whenever the
+     * source corpus changes; embed() must be called only after fit().
+     */
+    fit(corpus) {
+        const docs = corpus.map(tokenize);
+        const df = new Map();
+        for (const doc of docs) {
+            const seen = new Set();
+            for (const t of doc) {
+                if (seen.has(t))
+                    continue;
+                seen.add(t);
+                df.set(t, (df.get(t) ?? 0) + 1);
+            }
+        }
+        // Filter: keep tokens appearing at least once and at most in 95% of docs.
+        const N = Math.max(1, docs.length);
+        const maxDf = Math.max(1, Math.ceil(N * 0.95));
+        const kept = [];
+        for (const [token, count] of df) {
+            if (count <= maxDf)
+                kept.push([token, count]);
+        }
+        kept.sort((a, b) => a[0].localeCompare(b[0]));
+        this.vocab = kept.map((x) => x[0]);
+        this.vocabIndex = new Map(this.vocab.map((t, i) => [t, i]));
+        this.idf = kept.map(([, dfi]) => Math.log((N + 1) / (dfi + 1)) + 1);
+    }
+    embedSync(text) {
+        if (this.vocab.length === 0)
+            return [];
+        const tokens = tokenize(text);
+        const tf = new Map();
+        for (const t of tokens) {
+            const idx = this.vocabIndex.get(t);
+            if (idx === undefined)
+                continue;
+            tf.set(idx, (tf.get(idx) ?? 0) + 1);
+        }
+        const vec = new Array(this.vocab.length).fill(0);
+        const docLen = tokens.length || 1;
+        for (const [idx, count] of tf) {
+            vec[idx] = (count / docLen) * (this.idf[idx] ?? 1);
+        }
+        return l2Normalize(vec);
+    }
+    async embed(texts) {
+        return texts.map((t) => this.embedSync(t));
+    }
+}
+export function cosineSimilarity(a, b) {
+    const n = Math.min(a.length, b.length);
+    let dot = 0;
+    for (let i = 0; i < n; i++)
+        dot += (a[i] ?? 0) * (b[i] ?? 0);
+    return dot;
+}
+export function l2Normalize(v) {
+    let sum = 0;
+    for (const x of v)
+        sum += x * x;
+    if (sum === 0)
+        return v;
+    const norm = Math.sqrt(sum);
+    return v.map((x) => x / norm);
+}
+export function tokenize(text) {
+    return text
+        .toLowerCase()
+        .normalize('NFKD')
+        .replace(/[̀-ͯ]/g, '')
+        .split(/[^a-z0-9_-]+/)
+        .filter((t) => t.length >= 2 && !STOPWORDS.has(t));
+}
+const STOPWORDS = new Set([
+    'the', 'a', 'an', 'and', 'or', 'but', 'is', 'are', 'was', 'were', 'be',
+    'been', 'being', 'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would',
+    'should', 'could', 'may', 'might', 'must', 'shall', 'to', 'of', 'in', 'for',
+    'on', 'at', 'by', 'with', 'from', 'as', 'into', 'through', 'about', 'between',
+    'this', 'that', 'these', 'those', 'it', 'its', 'they', 'them', 'their', 'we',
+    'us', 'our', 'you', 'your', 'he', 'she', 'his', 'her', 'i', 'me', 'my',
+    'so', 'than', 'too', 'very', 'just', 'not', 'no', 'yes', 'if', 'then',
+]);
+//# sourceMappingURL=tfidf.js.map

package/dist/tfidf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tfidf.js","sourceRoot":"","sources":["../src/tfidf.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@moxxy/plugin-memory",
+  "version": "0.27.0",
+  "description": "Journal-based long-term memory for moxxy. Markdown files at ~/.moxxy/memory/ with type/description frontmatter + an index. Plus STM selectors over the event log.",
+  "keywords": [
+    "moxxy",
+    "agent",
+    "memory",
+    "recall",
+    "embeddings"
+  ],
+  "homepage": "https://moxxy.ai",
+  "bugs": {
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
+    "directory": "packages/plugin-memory"
+  },
+  "author": "Michal Makowski <michal.makowski97@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "moxxy": {
+    "plugin": {
+      "entry": "./dist/index.js",
+      "kind": "tools"
+    }
+  },
+  "dependencies": {
+    "zod": "^3.24.0",
+    "@moxxy/sdk": "0.27.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "@moxxy/tsconfig": "0.0.0",
+    "@moxxy/vitest-preset": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo"
+  }
+}

package/src/consolidate-nudge.test.ts

@@ -0,0 +1,98 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import type { LLMProvider, ProviderEvent } from '@moxxy/sdk';
+import { MemoryStore } from './store.js';
+import { buildMemoryConsolidatePlugin } from './consolidate.js';
+
+let tmp: string;
+beforeEach(async () => {
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-nudge-'));
+});
+afterEach(async () => {
+  await fs.rm(tmp, { recursive: true, force: true });
+});
+
+const stubProvider: LLMProvider = {
+  name: 'stub',
+  models: [],
+  async *stream(): AsyncIterable<ProviderEvent> {},
+  async countTokens() {
+    return 0;
+  },
+};
+
+const baseReq = (system?: string): import('@moxxy/sdk').ProviderRequest => ({
+  model: 'stub',
+  messages: [],
+  ...(system !== undefined ? { system } : {}),
+});
+
+const ctx = (): import('@moxxy/sdk').TurnContext => ({
+  sessionId: 's' as never,
+  cwd: '/tmp',
+  log: { length: 0, at: () => undefined, slice: () => [], ofType: () => [], byTurn: () => [], toJSON: () => [] },
+  env: {},
+  turnId: 't' as never,
+  iteration: 0,
+});
+
+async function fillMemories(store: MemoryStore, n: number): Promise<void> {
+  for (let i = 0; i < n; i++) {
+    await store.save({
+      name: `entry-${i}`,
+      type: 'fact',
+      description: `Entry ${i}`,
+      body: `body ${i}`,
+    });
+  }
+}
+
+describe('auto-consolidation nudge hook', () => {
+  it('appends a hint to system prompt when memory count exceeds threshold', async () => {
+    const store = new MemoryStore({ dir: tmp, embedder: null });
+    await fillMemories(store, 5);
+    const plugin = buildMemoryConsolidatePlugin(store, () => stubProvider, { autoNudgeThreshold: 3 });
+    const result = await plugin.hooks?.onBeforeProviderCall?.(baseReq('be terse'), ctx());
+    expect(result).toBeDefined();
+    expect(result!.system).toContain('be terse');
+    expect(result!.system).toContain('memory_consolidate');
+    expect(result!.system).toContain('5 entries');
+  });
+
+  it('does NOT append a hint when memory count is below threshold', async () => {
+    const store = new MemoryStore({ dir: tmp, embedder: null });
+    await fillMemories(store, 2);
+    const plugin = buildMemoryConsolidatePlugin(store, () => stubProvider, { autoNudgeThreshold: 10 });
+    const result = await plugin.hooks?.onBeforeProviderCall?.(baseReq(), ctx());
+    expect(result).toBeUndefined();
+  });
+
+  it('nudges at most once per session (no repeat fires)', async () => {
+    const store = new MemoryStore({ dir: tmp, embedder: null });
+    await fillMemories(store, 5);
+    const plugin = buildMemoryConsolidatePlugin(store, () => stubProvider, { autoNudgeThreshold: 3 });
+    const first = await plugin.hooks?.onBeforeProviderCall?.(baseReq(), ctx());
+    const second = await plugin.hooks?.onBeforeProviderCall?.(baseReq(), ctx());
+    expect(first).toBeDefined();
+    expect(second).toBeUndefined();
+  });
+
+  it('threshold:0 disables the nudge entirely', async () => {
+    const store = new MemoryStore({ dir: tmp, embedder: null });
+    const plugin = buildMemoryConsolidatePlugin(store, () => stubProvider, { autoNudgeThreshold: 0 });
+    // With threshold 0, no hooks are registered at all
+    expect(plugin.hooks?.onBeforeProviderCall).toBeUndefined();
+  });
+
+  it('default threshold is 30', async () => {
+    const store = new MemoryStore({ dir: tmp, embedder: null });
+    await fillMemories(store, 30);
+    const plugin = buildMemoryConsolidatePlugin(store, () => stubProvider);
+    // 30 is not greater than 30 → no nudge
+    const result = await plugin.hooks?.onBeforeProviderCall?.(baseReq(), ctx());
+    expect(result).toBeUndefined();
+  });
+
+});