@theihtisham/agent-shadow-brain 6.0.0 → 6.0.3

package/dist/brain/brain-memory-tiers.js

@@ -0,0 +1,292 @@
+// src/brain/brain-memory-tiers.ts — Episodic vs semantic memory split
+// v6.0.2 — Hive Mind Edition
+//
+// Human brains separate episodic memory (what happened, when, by whom) from
+// semantic memory (abstract facts distilled from many episodes). Mixing them
+// poisons recall — every "I solved this last Tuesday" buries the underlying
+// pattern. This module enforces the split with two append-only stores and a
+// promotion path from episodic → semantic when the same fact recurs.
+//
+// Storage layout (under ~/.shadow-brain/memory/):
+//   episodic/<project>.jsonl                — raw events, daily-rotated
+//   episodic/<project>-YYYY-MM-DD.jsonl     — rotated archives
+//   semantic/<project>.jsonl                — curated, mergeable facts
+//
+// Promotion criteria (ALL must hold):
+//   1. accessCount >= 3                     — recalled repeatedly
+//   2. importance >= 0.5                    — non-trivial
+//   3. linked to >= 2 other memories        — connected to the graph
+//   4. lastAccessed within 30 days          — still warm
+//
+// New memories always land in episodic. Promotion is explicit (callable) or
+// happens lazily during read() when criteria are met.
+//
+// Exposed: BrainMemoryTiers, getBrainMemoryTiers(), resetBrainMemoryTiersForTests()
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+const STORE_DIR = path.join(os.homedir(), '.shadow-brain', 'memory');
+const EPISODIC_DIR = path.join(STORE_DIR, 'episodic');
+const SEMANTIC_DIR = path.join(STORE_DIR, 'semantic');
+const DEFAULT_PROJECT = 'default';
+const PROMOTE_MIN_ACCESS = 3;
+const PROMOTE_MIN_IMPORTANCE = 0.5;
+const PROMOTE_MIN_LINKS = 2;
+const PROMOTE_MAX_AGE_DAYS = 30;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+export class BrainMemoryTiers {
+    constructor() {
+        this.initialized = false;
+    }
+    async init() {
+        if (this.initialized)
+            return;
+        fs.mkdirSync(EPISODIC_DIR, { recursive: true });
+        fs.mkdirSync(SEMANTIC_DIR, { recursive: true });
+        this.initialized = true;
+    }
+    /** Write a new memory. Defaults to episodic; module picks tier if not forced. */
+    async write(memory) {
+        await this.init();
+        const project = sanitizeProject(memory.project);
+        const now = new Date().toISOString();
+        const entry = {
+            id: memory.id ?? newId('mem'),
+            tier: memory.tier ?? 'episodic',
+            content: (memory.content || '').slice(0, 8000),
+            project,
+            createdAt: now,
+            lastAccessed: now,
+            accessCount: 0,
+            importance: clamp01(memory.importance ?? 0.5),
+            sourceAgent: memory.sourceAgent || 'unknown',
+            entityRefs: memory.entityRefs ?? [],
+            embedding: memory.embedding,
+            relatedTo: [],
+        };
+        this.rotateIfNeeded(project);
+        this.appendEntry(entry);
+        return entry;
+    }
+    /**
+     * Promote an episodic memory to semantic. If criteria are not met, throws
+     * unless the caller already forced it (re-issued with tier='semantic').
+     */
+    async promote(memoryId) {
+        await this.init();
+        const existing = this.findById(memoryId);
+        if (!existing)
+            throw new Error(`memory ${memoryId} not found`);
+        if (existing.tier === 'semantic')
+            return existing;
+        if (!this.meetsPromotionCriteria(existing)) {
+            throw new Error(`memory ${memoryId} does not meet promotion criteria`);
+        }
+        const promoted = {
+            ...existing,
+            id: newId('sem'),
+            tier: 'semantic',
+            derivedFromMemoryIds: [...(existing.derivedFromMemoryIds ?? []), existing.id],
+            lastAccessed: new Date().toISOString(),
+        };
+        this.appendEntry(promoted);
+        return promoted;
+    }
+    /** Read memories matching the options. Lazily promotes warm episodic on access. */
+    async read(opts = {}) {
+        await this.init();
+        const project = sanitizeProject(opts.project);
+        const wantTier = opts.tier ?? 'all';
+        const limit = opts.limit ?? 50;
+        const pool = [];
+        if (wantTier === 'episodic' || wantTier === 'all') {
+            pool.push(...this.loadTier('episodic', project));
+        }
+        if (wantTier === 'semantic' || wantTier === 'all') {
+            pool.push(...this.loadTier('semantic', project));
+        }
+        let results = pool;
+        if (opts.query) {
+            const q = opts.query.toLowerCase();
+            results = pool.filter(m => m.content.toLowerCase().includes(q));
+        }
+        // Mark access on the returned slice. (Cheap rewrite of last-accessed; we
+        // do NOT persist accessCount mutations here because the store is append-
+        // only — instead, we touch a sidecar.) For now, in-process mutation.
+        const now = new Date().toISOString();
+        const touched = results.slice(0, limit).map(m => ({
+            ...m,
+            lastAccessed: now,
+            accessCount: m.accessCount + 1,
+        }));
+        // Lazy promotion: if an episodic entry now meets criteria, queue a write.
+        for (const m of touched) {
+            if (m.tier === 'episodic' && this.meetsPromotionCriteria(m)) {
+                try {
+                    await this.promote(m.id);
+                }
+                catch { /* skip */ }
+            }
+        }
+        // Sort by importance desc, then recency desc
+        touched.sort((a, b) => (b.importance - a.importance) || b.createdAt.localeCompare(a.createdAt));
+        return touched;
+    }
+    stats(project) {
+        if (!this.initialized) {
+            // best-effort sync init for stats
+            try {
+                fs.mkdirSync(EPISODIC_DIR, { recursive: true });
+                fs.mkdirSync(SEMANTIC_DIR, { recursive: true });
+            }
+            catch { /* skip */ }
+        }
+        const proj = sanitizeProject(project);
+        const ep = this.loadTier('episodic', proj);
+        const sem = this.loadTier('semantic', proj);
+        const epStats = bucket(ep);
+        const semStats = bucket(sem);
+        const totalEpisodic = ep.length + sem.length;
+        const promotionRate = totalEpisodic > 0 ? +(sem.length / totalEpisodic).toFixed(3) : 0;
+        return { episodic: epStats, semantic: semStats, promotionRate };
+    }
+    // ── Internals ─────────────────────────────────────────────────────────
+    meetsPromotionCriteria(m) {
+        if (m.accessCount < PROMOTE_MIN_ACCESS)
+            return false;
+        if (m.importance < PROMOTE_MIN_IMPORTANCE)
+            return false;
+        const linkCount = (m.entityRefs?.length ?? 0) + (m.relatedTo?.length ?? 0);
+        if (linkCount < PROMOTE_MIN_LINKS)
+            return false;
+        const ageMs = Date.now() - Date.parse(m.lastAccessed);
+        if (!Number.isFinite(ageMs) || ageMs > PROMOTE_MAX_AGE_DAYS * MS_PER_DAY)
+            return false;
+        return true;
+    }
+    findById(id) {
+        for (const tier of ['episodic', 'semantic']) {
+            const dir = tier === 'episodic' ? EPISODIC_DIR : SEMANTIC_DIR;
+            if (!fs.existsSync(dir))
+                continue;
+            for (const file of fs.readdirSync(dir)) {
+                if (!file.endsWith('.jsonl'))
+                    continue;
+                try {
+                    const lines = fs.readFileSync(path.join(dir, file), 'utf-8').split('\n');
+                    for (const line of lines) {
+                        if (!line.trim())
+                            continue;
+                        try {
+                            const obj = JSON.parse(line);
+                            if (obj.id === id)
+                                return obj;
+                        }
+                        catch { /* skip line */ }
+                    }
+                }
+                catch { /* skip file */ }
+            }
+        }
+        return null;
+    }
+    loadTier(tier, project) {
+        const dir = tier === 'episodic' ? EPISODIC_DIR : SEMANTIC_DIR;
+        if (!fs.existsSync(dir))
+            return [];
+        const out = [];
+        const prefix = `${project}`;
+        for (const file of fs.readdirSync(dir)) {
+            if (!file.endsWith('.jsonl'))
+                continue;
+            if (!file.startsWith(prefix))
+                continue;
+            try {
+                const lines = fs.readFileSync(path.join(dir, file), 'utf-8').split('\n');
+                for (const line of lines) {
+                    if (!line.trim())
+                        continue;
+                    try {
+                        const obj = JSON.parse(line);
+                        if (obj.project !== project)
+                            continue;
+                        if (obj.tier !== tier)
+                            continue;
+                        out.push(obj);
+                    }
+                    catch { /* skip bad line */ }
+                }
+            }
+            catch { /* skip bad file */ }
+        }
+        return out;
+    }
+    appendEntry(entry) {
+        const dir = entry.tier === 'episodic' ? EPISODIC_DIR : SEMANTIC_DIR;
+        const file = path.join(dir, `${entry.project}.jsonl`);
+        try {
+            fs.appendFileSync(file, JSON.stringify(entry) + '\n');
+        }
+        catch { /* non-fatal */ }
+    }
+    rotateIfNeeded(project) {
+        // Daily rotation: if today's episodic file exceeds 2MB, archive it.
+        const file = path.join(EPISODIC_DIR, `${project}.jsonl`);
+        if (!fs.existsSync(file))
+            return;
+        try {
+            const sz = fs.statSync(file).size;
+            if (sz < 2 * 1024 * 1024)
+                return;
+            const stamp = new Date().toISOString().slice(0, 10);
+            const dest = path.join(EPISODIC_DIR, `${project}-${stamp}.jsonl`);
+            if (!fs.existsSync(dest))
+                fs.renameSync(file, dest);
+        }
+        catch { /* skip */ }
+    }
+}
+function sanitizeProject(p) {
+    if (!p)
+        return DEFAULT_PROJECT;
+    return p.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 80) || DEFAULT_PROJECT;
+}
+function clamp01(n) {
+    if (!Number.isFinite(n))
+        return 0;
+    return Math.max(0, Math.min(1, n));
+}
+function newId(prefix) {
+    const r = Math.random().toString(36).slice(2, 10);
+    const t = Date.now().toString(36);
+    return `${prefix}_${t}_${r}`;
+}
+function bucket(entries) {
+    if (entries.length === 0) {
+        return { count: 0, oldestAt: null, newestAt: null, avgImportance: 0 };
+    }
+    let oldest = entries[0].createdAt;
+    let newest = entries[0].createdAt;
+    let impSum = 0;
+    for (const e of entries) {
+        if (e.createdAt < oldest)
+            oldest = e.createdAt;
+        if (e.createdAt > newest)
+            newest = e.createdAt;
+        impSum += e.importance;
+    }
+    return {
+        count: entries.length,
+        oldestAt: oldest,
+        newestAt: newest,
+        avgImportance: +(impSum / entries.length).toFixed(3),
+    };
+}
+let _instance = null;
+export function getBrainMemoryTiers() {
+    if (!_instance)
+        _instance = new BrainMemoryTiers();
+    return _instance;
+}
+export function resetBrainMemoryTiersForTests() { _instance = null; }
+//# sourceMappingURL=brain-memory-tiers.js.map

package/dist/brain/brain-memory-tiers.js.map

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

package/dist/brain/brain-notebook.d.ts

@@ -0,0 +1,68 @@
+export type QueryType = 'recall' | 'search' | 'dna' | 'replay' | 'archetype' | 'stats';
+export type Cell = {
+    kind: 'markdown';
+    source: string;
+} | {
+    kind: 'query';
+    queryType: QueryType;
+    source: string;
+    lastResult?: string;
+    lastRun?: string;
+} | {
+    kind: 'code';
+    language: 'ts' | 'py' | 'sh';
+    source: string;
+};
+export interface NotebookMetadata {
+    project: string;
+    created: string;
+    modified: string;
+    brain_version: string;
+}
+export interface Notebook {
+    title: string;
+    cells: Cell[];
+    metadata: NotebookMetadata;
+}
+export interface NotebookRunResult {
+    cells: Array<{
+        index: number;
+        kind: Cell['kind'];
+        result?: string;
+        durationMs?: number;
+        error?: string;
+    }>;
+    totalDurationMs: number;
+    ranAt: string;
+}
+export declare class BrainNotebook {
+    /** Create a starter notebook on disk and return its path. */
+    createNotebook(project: string, title: string): Promise<{
+        path: string;
+    }>;
+    /** Parse a notebook from disk. */
+    parse(filePath: string): Promise<Notebook>;
+    /** Parse a notebook from a raw string (useful for tests). */
+    parseString(raw: string, source?: string): Notebook;
+    /** Run a single cell. Markdown cells are no-ops; code cells echo with a TODO. */
+    runCell(notebook: Notebook, cellIndex: number): Promise<{
+        result: string;
+        durationMs: number;
+    }>;
+    /** Run every query cell in order. */
+    runAll(notebook: Notebook): Promise<NotebookRunResult>;
+    /** Write the notebook back to disk with the latest run results inlined. */
+    save(notebook: Notebook, filePath: string): Promise<void>;
+    /** Render the notebook as a plain Markdown document. */
+    toMarkdown(notebook: Notebook): string;
+    private executeQuery;
+    private runRecall;
+    private runDna;
+    private runReplay;
+    private runArchetype;
+    private runStats;
+    private fallbackResult;
+}
+export declare function getBrainNotebook(): BrainNotebook;
+export declare function resetBrainNotebookForTests(): void;
+//# sourceMappingURL=brain-notebook.d.ts.map

package/dist/brain/brain-notebook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-notebook.d.ts","sourceRoot":"","sources":["../../src/brain/brain-notebook.ts"],"names":[],"mappings":"AAiBA,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,WAAW,GAAG,OAAO,CAAC;AAEvF,MAAM,MAAM,IAAI,GACZ;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9F;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,QAAQ,EAAE,gBAAgB,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1G,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,aAAa;IACxB,6DAA6D;IACvD,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAgB/E,kCAAkC;IAC5B,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAKhD,6DAA6D;IAC7D,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,SAAY,GAAG,QAAQ;IA2GtD,iFAAiF;IAC3E,OAAO,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAkBrG,qCAAqC;IAC/B,MAAM,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAmB5D,2EAA2E;IACrE,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ/D,wDAAwD;IACxD,UAAU,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM;YA2BxB,YAAY;YAyBZ,SAAS;YAiBT,MAAM;YAUN,SAAS;YAUT,YAAY;YAUZ,QAAQ;IAUtB,OAAO,CAAC,cAAc;CAGvB;AA6DD,wBAAgB,gBAAgB,IAAI,aAAa,CAGhD;AACD,wBAAgB,0BAA0B,IAAI,IAAI,CAAsB"}