@hmharness/evolution 0.3.0 → 0.4.0

package/dist/memory.d.ts

@@ -3,10 +3,18 @@ export interface MemoryNote {
     text: string;
 }
 export declare function readNotes(home: string): Promise<MemoryNote[]>;
-export declare function scoreNotes(notes: MemoryNote[], task: string): Array<{
+/** Resolve the workspace a cwd belongs to (longest path prefix wins).
+ *  Returns null outside every workspace - those notes stay global. */
+export declare function workspaceForCwd(home: string, cwd: string): Promise<string | null>;
+export declare function scoreNotes(notes: MemoryNote[], task: string, workspace?: string): Array<{
     note: MemoryNote;
     score: number;
 }>;
+export interface EmbeddingProvider {
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+}
 /**
  * Build the prompt block: top-k task-relevant notes plus the newest few
  * (deduplicated), bounded in chars. Empty string when memory is empty.
@@ -15,7 +23,10 @@ export declare function retrieveMemory(home: string, task: string, opts?: {
     topK?: number;
     newest?: number;
     maxChars?: number;
+    workspace?: string;
+    embedding?: EmbeddingProvider;
+    fetchImpl?: typeof fetch;
 }): Promise<string>;
 /** Legacy full load (tail-bounded) - kept for callers that want everything. */
 export declare function loadMemory(home: string): Promise<string>;
-export declare function appendMemory(home: string, note: string): Promise<void>;
+export declare function appendMemory(home: string, note: string, workspace?: string): Promise<void>;

package/dist/memory.js

@@ -2,11 +2,22 @@
  * @hmharness/evolution - memory
  * Cross-session persistent memory. Notes are append-only lines in
  * memory/memory.md (ACE lesson: append beats rewrite - rewriting is where
- * hard-won context gets lost). Injection is retrieval-based: notes are
- * scored against the current task (ASCII words + CJK bigrams, no deps) and
- * only the top matches plus the newest few enter the system prompt.
+ * hard-won context gets lost). Injection is retrieval-based and layered:
+ *
+ *   1. lexical scoring (ASCII words + CJK bigrams, no deps) - the baseline
+ *   2. workspace scoping - notes tagged [ws:<name>] are boosted 2.5x when
+ *      the current task runs inside that workspace and dampened to 0.3x in
+ *      others. Isolation WITHOUT walls: project-local facts rank first at
+ *      home, but global lessons stay reachable everywhere. Untagged notes
+ *      (the entire pre-existing memory) behave exactly as before.
+ *   3. optional embedding hybrid - when an embedding provider is passed in,
+ *      notes are vectorised once (cache: memory/embeddings.json, keyed by
+ *      content hash) and ranked by cosine similarity blended with the
+ *      lexical score. Any failure falls back to pure lexical - embeddings
+ *      are an upgrade, never a dependency.
  */
-import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 export async function readNotes(home) {
     let raw;
@@ -24,6 +35,35 @@ export async function readNotes(home) {
     }
     return notes;
 }
+/** Resolve the workspace a cwd belongs to (longest path prefix wins).
+ *  Returns null outside every workspace - those notes stay global. */
+export async function workspaceForCwd(home, cwd) {
+    let entries;
+    try {
+        const j = JSON.parse(await readFile(join(home, 'workspaces.json'), 'utf8'));
+        entries = Array.isArray(j) ? j : (j.workspaces ?? []);
+    }
+    catch {
+        return null;
+    }
+    const norm = (p) => p.replace(/[\\/]+/g, '\\').toLowerCase().replace(/\\$/, '');
+    const target = norm(cwd);
+    let best = null;
+    for (const w of entries) {
+        if (!w?.path || !w?.name)
+            continue;
+        const p = norm(w.path);
+        if ((target === p || target.startsWith(p + '\\')) && (!best || p.length > best.len)) {
+            best = { name: w.name, len: p.length };
+        }
+    }
+    return best?.name ?? null;
+}
+const WS_TAG = /\s*\[ws:([^\]]+)\]\s*$/;
+function noteWorkspace(text) {
+    const m = text.match(WS_TAG);
+    return m ? m[1] : null;
+}
 /** Tokenize for scoring: ASCII words as-is, CJK runs as bigrams. */
 function tokens(text) {
     const out = new Set();
@@ -35,19 +75,85 @@ function tokens(text) {
     }
     return out;
 }
-export function scoreNotes(notes, task) {
+export function scoreNotes(notes, task, workspace) {
     const taskTokens = tokens(task);
-    return notes
-        .map((note, idx) => {
+    const ranked = notes.map((note, idx) => {
         const n = tokens(note.text);
         let overlap = 0;
         for (const t of n)
             if (taskTokens.has(t))
                 overlap++;
-        // tiny recency bias so equal-relevance ties favor recent notes
-        return { note, score: overlap + idx / Math.max(notes.length, 1) * 0.01 };
-    })
-        .sort((a, b) => b.score - a.score);
+        let score = overlap + idx / Math.max(notes.length, 1) * 0.01;
+        // workspace scoping: boost at home, dampen abroad, globals untouched
+        const ws = noteWorkspace(note.text);
+        if (workspace && ws === workspace)
+            score *= 2.5;
+        else if (workspace && ws && ws !== workspace)
+            score *= 0.3;
+        return { note, score };
+    });
+    return ranked.sort((a, b) => b.score - a.score);
+}
+function cosine(a, b) {
+    let dot = 0, na = 0, nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    return na && nb ? dot / (Math.sqrt(na) * Math.sqrt(nb)) : 0;
+}
+async function embed(inputs, p, fetchImpl) {
+    const doFetch = fetchImpl ?? fetch;
+    try {
+        const res = await doFetch(p.baseUrl.replace(/\/+$/, '') + '/embeddings', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${p.apiKey}` },
+            body: JSON.stringify({ model: p.model, input: inputs }),
+            signal: AbortSignal.timeout(20_000),
+        });
+        if (!res.ok)
+            return null;
+        const j = await res.json();
+        const out = (j.data ?? []).map((d) => d.embedding ?? []);
+        return out.length === inputs.length ? out : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function hybridRank(notes, task, workspace, home, embedding, fetchImpl) {
+    const lexical = scoreNotes(notes, task, workspace);
+    const maxLex = Math.max(...lexical.map((r) => r.score), 1e-9);
+    const cacheFile = join(home, 'memory', 'embeddings.json');
+    let cache = {};
+    try {
+        cache = JSON.parse(await readFile(cacheFile, 'utf8'));
+    }
+    catch { /* empty */ }
+    const hash = (s) => createHash('sha256').update(s).digest('hex').slice(0, 24);
+    const missing = [...new Set(notes.filter((n) => !cache[hash(n.text)]).map((n) => n.text))];
+    if (missing.length > 0) {
+        const vecs = await embed(missing, embedding, fetchImpl);
+        if (!vecs)
+            return null; // embedding endpoint down -> pure lexical
+        missing.forEach((text, i) => { cache[hash(text)] = vecs[i]; });
+        try {
+            await mkdir(join(home, 'memory'), { recursive: true });
+            await writeFile(cacheFile, JSON.stringify(cache), 'utf8');
+        }
+        catch { /* best effort */ }
+    }
+    const queryVec = await embed([task], embedding, fetchImpl);
+    if (!queryVec)
+        return null;
+    const q = queryVec[0];
+    const blended = lexical.map((r) => {
+        const v = cache[hash(r.note.text)];
+        const cos = v ? cosine(v, q) : 0;
+        return { note: r.note, score: 0.5 * (r.score / maxLex) + 0.5 * Math.max(cos, 0) };
+    });
+    return blended.sort((a, b) => b.score - a.score);
 }
 /**
  * Build the prompt block: top-k task-relevant notes plus the newest few
@@ -58,14 +164,20 @@ export async function retrieveMemory(home, task, opts = {}) {
     const notes = await readNotes(home);
     if (notes.length === 0)
         return '';
-    const ranked = scoreNotes(notes, task);
+    let ranked;
+    if (opts.embedding) {
+        ranked = (await hybridRank(notes, task, opts.workspace, home, opts.embedding, opts.fetchImpl)) ?? scoreNotes(notes, task, opts.workspace);
+    }
+    else {
+        ranked = scoreNotes(notes, task, opts.workspace);
+    }
     const picked = [];
     const seen = new Set();
     for (const { note } of ranked.slice(0, topK)) {
         picked.push(note);
         seen.add(note.text);
     }
-    for (const note of notes.slice(-newest)) {
+    for (const note of (newest > 0 ? notes.slice(-newest) : [])) {
         if (!seen.has(note.text))
             picked.push(note);
         seen.add(note.text);
@@ -90,9 +202,10 @@ export async function loadMemory(home) {
         return '';
     }
 }
-export async function appendMemory(home, note) {
+export async function appendMemory(home, note, workspace) {
     const dir = join(home, 'memory');
     await mkdir(dir, { recursive: true });
     const stamp = new Date().toISOString().slice(0, 16).replace('T', ' ');
-    await appendFile(join(dir, 'memory.md'), `\n- [${stamp}] ${note.replace(/\n+/g, ' ').trim()}\n`, 'utf8');
+    const tag = workspace ? ` [ws:${workspace}]` : '';
+    await appendFile(join(dir, 'memory.md'), `\n- [${stamp}] ${note.replace(/\n+/g, ' ').trim()}${tag}\n`, 'utf8');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hmharness/evolution",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "hmharness evolution subsystem: persistent memory, insight capture, skill library, and the bench that gives evolution its fitness signal. First-class kernel citizen, not a plugin.",
   "type": "module",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
     "build": "tsc -p tsconfig.build.json"
   },
   "dependencies": {
-    "@hmharness/kernel": "0.3.0"
+    "@hmharness/kernel": "0.4.0"
   },
   "files": [
     "dist"