cogmem 3.6.2

package/dist/benchmark/ExternalBenchmarkRunner.d.ts

@@ -0,0 +1,8 @@
+import { type LongMemEvalBrain, type LongMemEvalMetrics } from './LongMemEvalAdapter.js';
+export declare class ExternalBenchmarkRunner {
+    private readonly brain;
+    private readonly datasetPath;
+    constructor(brain: LongMemEvalBrain, datasetPath: string);
+    runLongMemEval(): Promise<LongMemEvalMetrics>;
+}
+//# sourceMappingURL=ExternalBenchmarkRunner.d.ts.map

package/dist/benchmark/ExternalBenchmarkRunner.js

@@ -0,0 +1,12 @@
+import { LongMemEvalAdapter } from './LongMemEvalAdapter.js';
+export class ExternalBenchmarkRunner {
+    brain;
+    datasetPath;
+    constructor(brain, datasetPath) {
+        this.brain = brain;
+        this.datasetPath = datasetPath;
+    }
+    async runLongMemEval() {
+        return new LongMemEvalAdapter(this.brain).runDataset(this.datasetPath);
+    }
+}

package/dist/benchmark/LongMemEvalAdapter.d.ts

@@ -0,0 +1,46 @@
+import type { BrainRecallResult } from '../types/BrainRecallResult.js';
+import type { IngestInput } from '../types/index.js';
+export interface LongMemEvalQuestion {
+    id: string;
+    query: string;
+    expectedAnswer: string;
+    type: 'single_hop' | 'multi_hop' | 'temporal' | 'negative' | string;
+}
+export interface LongMemEvalSession {
+    id: string;
+    projectId?: string;
+    messages: Array<{
+        role: 'user' | 'assistant' | string;
+        content: string;
+    }>;
+    questions: LongMemEvalQuestion[];
+}
+export interface LongMemEvalDataset {
+    sessions: LongMemEvalSession[];
+}
+export interface LongMemEvalMetrics {
+    totalQuestions: number;
+    correct: number;
+    accuracy: number;
+    accuracyByType: Record<string, number>;
+    avgRecallMs: number;
+}
+export interface LongMemEvalBrain {
+    ingest(input: IngestInput): Promise<unknown>;
+    recall(query: string, options?: {
+        projectId?: string;
+        limit?: number;
+        includeRawEvidence?: boolean;
+    }): BrainRecallResult;
+}
+export declare class LongMemEvalAdapter {
+    private readonly brain;
+    constructor(brain: LongMemEvalBrain);
+    runDataset(datasetPath: string): Promise<LongMemEvalMetrics>;
+    private runSession;
+    private toMetrics;
+    private renderRecallAnswer;
+    private evaluateAnswer;
+    private answerTokens;
+}
+//# sourceMappingURL=LongMemEvalAdapter.d.ts.map

package/dist/benchmark/LongMemEvalAdapter.js

@@ -0,0 +1,88 @@
+export class LongMemEvalAdapter {
+    brain;
+    constructor(brain) {
+        this.brain = brain;
+    }
+    async runDataset(datasetPath) {
+        const dataset = JSON.parse(await Bun.file(datasetPath).text());
+        const results = [];
+        for (const session of dataset.sessions || []) {
+            results.push(...await this.runSession(session));
+        }
+        return this.toMetrics(results);
+    }
+    async runSession(session) {
+        const projectId = session.projectId || `longmemeval-${session.id}`;
+        for (const message of session.messages || []) {
+            await this.brain.ingest({
+                projectId,
+                type: 'chat',
+                sourceType: message.role === 'user' ? 'user_input' : 'llm_inference',
+                content: `${message.role}: ${message.content}`
+            });
+        }
+        return (session.questions || []).map((question) => {
+            const startedAt = Date.now();
+            const recall = this.brain.recall(question.query, { projectId, limit: 8, includeRawEvidence: true });
+            const recallMs = Math.max(0, Date.now() - startedAt);
+            const predicted = this.renderRecallAnswer(recall);
+            return {
+                questionId: question.id,
+                type: question.type,
+                correct: this.evaluateAnswer(predicted, question.expectedAnswer),
+                recallMs
+            };
+        });
+    }
+    toMetrics(results) {
+        const totalQuestions = results.length;
+        const correct = results.filter((result) => result.correct).length;
+        const byType = new Map();
+        for (const result of results) {
+            byType.set(result.type, [...(byType.get(result.type) || []), result]);
+        }
+        const accuracyByType = {};
+        for (const [type, rows] of byType) {
+            accuracyByType[type] = rows.length === 0 ? 0 : rows.filter((row) => row.correct).length / rows.length;
+        }
+        return {
+            totalQuestions,
+            correct,
+            accuracy: totalQuestions === 0 ? 0 : correct / totalQuestions,
+            accuracyByType,
+            avgRecallMs: totalQuestions === 0 ? 0 : results.reduce((sum, result) => sum + result.recallMs, 0) / totalQuestions
+        };
+    }
+    renderRecallAnswer(recall) {
+        return [
+            ...recall.compiledMemory.facts.map((fact) => [fact.subject, fact.predicateValue, fact.object].filter(Boolean).join(' ')),
+            ...recall.compiledMemory.events.map((event) => event.eventType),
+            ...recall.rawEvidence.map((neuron) => neuron.content),
+            ...recall.fallbackSnippets.map((snippet) => snippet.text)
+        ].join('\n');
+    }
+    evaluateAnswer(predicted, expected) {
+        const expectedTokens = this.answerTokens(expected);
+        const predictedTokens = this.answerTokens(predicted);
+        if (expectedTokens.size === 0)
+            return predictedTokens.size === 0;
+        if (predictedTokens.size === 0)
+            return false;
+        let overlap = 0;
+        for (const token of expectedTokens) {
+            if (predictedTokens.has(token))
+                overlap++;
+        }
+        const precision = overlap / predictedTokens.size;
+        const recall = overlap / expectedTokens.size;
+        const f1 = precision + recall === 0 ? 0 : (2 * precision * recall) / (precision + recall);
+        return f1 >= 0.5;
+    }
+    answerTokens(text) {
+        const stopwords = new Set(['the', 'a', 'an', 'is', 'are', 'was', 'were', 'to', 'of', 'and', 'or', 'what', 'did', 'user', 'about']);
+        return new Set(text.toLowerCase()
+            .split(/[^\p{L}\p{N}_-]+/u)
+            .map((token) => token.trim())
+            .filter((token) => token.length > 0 && !stopwords.has(token)));
+    }
+}

package/dist/benchmark/LongMemEvalCli.d.ts

@@ -0,0 +1,6 @@
+export interface LongMemEvalCliArgs {
+    datasetPath: string;
+}
+export declare function parseLongMemEvalArgs(argv: string[]): LongMemEvalCliArgs;
+export declare function runLongMemEvalCli(argv?: string[]): Promise<string>;
+//# sourceMappingURL=LongMemEvalCli.d.ts.map

package/dist/benchmark/LongMemEvalCli.js

@@ -0,0 +1,26 @@
+import { MemoryKernel } from '../factory.js';
+import { ExternalBenchmarkRunner } from './ExternalBenchmarkRunner.js';
+export function parseLongMemEvalArgs(argv) {
+    const datasetIndex = argv.indexOf('--dataset');
+    const datasetPath = datasetIndex >= 0 ? argv[datasetIndex + 1] : undefined;
+    if (!datasetPath) {
+        throw new Error('Usage: run-longmemeval --dataset <path>');
+    }
+    return { datasetPath };
+}
+export async function runLongMemEvalCli(argv = Bun.argv.slice(2)) {
+    const { datasetPath } = parseLongMemEvalArgs(argv);
+    const brain = new MemoryKernel();
+    await brain.initialize();
+    const metrics = await new ExternalBenchmarkRunner(brain, datasetPath).runLongMemEval();
+    const temporal = metrics.accuracyByType.temporal ?? 0;
+    return [
+        'LongMemEval Results',
+        '---------------------------------------',
+        `Total questions : ${metrics.totalQuestions}`,
+        `Correct         : ${metrics.correct}`,
+        `Overall accuracy: ${(metrics.accuracy * 100).toFixed(1)}% ${metrics.accuracy >= 0.4 ? 'pass' : 'fail'}  (baseline >= 40%)`,
+        `Temporal        : ${(temporal * 100).toFixed(1)}% ${temporal >= 0.3 ? 'pass' : 'fail'}  (baseline >= 30%)`,
+        `Avg recall ms   : ${Math.round(metrics.avgRecallMs)}ms`,
+    ].join('\n');
+}

package/dist/bin/CliJson.d.ts

@@ -0,0 +1,17 @@
+export declare const CLI_JSON_SCHEMA_VERSION: "cogmem.cli.v1";
+interface QueueCounters {
+    candidate?: unknown;
+    promoted?: unknown;
+    needsConfirmation?: unknown;
+    needs_confirmation?: unknown;
+}
+export declare function formatCliJson(command: string, payload: unknown, options?: {
+    queue?: QueueCounters;
+    beliefs?: number;
+}): Record<string, unknown>;
+export declare function printCliJson(command: string, payload: unknown, options?: {
+    queue?: QueueCounters;
+    beliefs?: number;
+}): void;
+export {};
+//# sourceMappingURL=CliJson.d.ts.map

package/dist/bin/CliJson.js

@@ -0,0 +1,20 @@
+export const CLI_JSON_SCHEMA_VERSION = 'cogmem.cli.v1';
+export function formatCliJson(command, payload, options = {}) {
+    const queue = options.queue;
+    const output = payload && typeof payload === 'object' && !Array.isArray(payload)
+        ? { ...payload, schemaVersion: CLI_JSON_SCHEMA_VERSION, command }
+        : { schemaVersion: CLI_JSON_SCHEMA_VERSION, command, items: Array.isArray(payload) ? payload : [payload] };
+    if (queue) {
+        output.candidate = finiteCounter(queue.candidate);
+        output.promoted = finiteCounter(queue.promoted);
+        output.needs_confirmation = finiteCounter(queue.needs_confirmation ?? queue.needsConfirmation);
+        output.beliefs = finiteCounter(options.beliefs);
+    }
+    return output;
+}
+export function printCliJson(command, payload, options = {}) {
+    console.log(JSON.stringify(formatCliJson(command, payload, options), null, 2));
+}
+function finiteCounter(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : 0;
+}

package/dist/bin/brain-eval.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+export {};
+//# sourceMappingURL=brain-eval.d.ts.map

package/dist/bin/brain-eval.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env bun
+import { readFileSync } from 'node:fs';
+import { BrainEvalRunner } from '../benchmark/BrainEval.js';
+import { StrategyRolloutEvaluator } from '../eval/strategy/index.js';
+import { printCliJson } from './CliJson.js';
+function usage() {
+    return [
+        'Usage: cogmem brain-eval --input <samples.json> [--json]',
+        '       cogmem brain-eval --input <outcomes.json> --strategy-rollout [--json]',
+        'Normal input is BrainEvalSample[] or { "samples": BrainEvalSample[] }.',
+        'Strategy input is precomputed StrategyRolloutOutcome[] or { "outcomes": StrategyRolloutOutcome[] }; no online rollouts are generated.',
+    ].join('\n');
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.includes('--help') || argv.includes('-h')) {
+        console.log(usage());
+        return;
+    }
+    const index = argv.indexOf('--input');
+    const inputPath = index >= 0 ? argv[index + 1] : undefined;
+    if (!inputPath)
+        throw new Error(usage());
+    const parsed = JSON.parse(readFileSync(inputPath, 'utf8'));
+    if (argv.includes('--strategy-rollout')) {
+        const outcomes = Array.isArray(parsed) ? parsed : 'outcomes' in parsed ? parsed.outcomes : undefined;
+        if (!Array.isArray(outcomes))
+            throw new Error('Strategy rollout input must contain an outcomes array.');
+        const report = new StrategyRolloutEvaluator().evaluate(outcomes);
+        printCliJson('brain-eval.strategy-rollout', report);
+        if (!report.passed)
+            process.exitCode = 1;
+        return;
+    }
+    const samples = Array.isArray(parsed) ? parsed : 'samples' in parsed ? parsed.samples : undefined;
+    if (!Array.isArray(samples))
+        throw new Error('BrainEval input must contain a samples array.');
+    const report = new BrainEvalRunner().evaluate(samples);
+    printCliJson('brain-eval', report);
+    if (!report.passed)
+        process.exitCode = 1;
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/dist/bin/cogmem.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+export {};
+//# sourceMappingURL=cogmem.d.ts.map

package/dist/bin/cogmem.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env bun
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const COMMANDS = {
+    init: 'init',
+    doctor: 'doctor',
+    connect: 'connect',
+    update: 'update',
+    openclaw: 'openclaw',
+    compact: 'compact',
+    memory: 'memory',
+    'explain-recall': 'explain-recall',
+    mcp: 'mcp',
+    repair: 'repair',
+    'import-openclaw': 'import-openclaw',
+    'import-hermes': 'import-hermes',
+    'normalize-transcript': 'normalize-transcript',
+    snapshot: 'snapshot',
+    're-embed': 're-embed',
+    'migrate-vectors': 'migrate-vectors',
+    migrate: 'migrate',
+    prospective: 'prospective',
+    strategy: 'strategy',
+    'brain-eval': 'brain-eval',
+    episode: 'episode',
+    dream: 'dream',
+};
+function usage() {
+    return [
+        'Usage: cogmem <command> [args]',
+        '',
+        'Commands:',
+        '  init                 interactive setup',
+        '  doctor               validate config; use --fix --agent openclaw to repair OpenClaw auto memory wiring',
+        '  connect openclaw     install OpenClaw/Hermes integration files; use --auto for OpenClaw runtime hooks',
+        '  update               show or run package update command',
+        '  openclaw diagnose    inspect generated OpenClaw plugin files and hook audit without opening the DB',
+        '  compact              dry-run or apply vector-only storage compaction',
+        '  memory               audit/search/show raw and compiled memory; run dream/candidates queue',
+        '  import-openclaw      import OpenClaw memory files',
+        '  import-hermes        import Hermes memory files',
+        '  explain-recall       explain governed recall',
+        '  mcp                  start stdio MCP server',
+        '  repair               conservative upgrade repair commands such as project-scope',
+        '  snapshot             export/import snapshots',
+        '  re-embed             inspect or run re-embedding',
+        '  migrate-vectors      migrate vector backend data',
+        '  migrate              plan or apply schema migrations with optional backup',
+        '  prospective          manage confirmed-only future-memory candidates; never executes tasks',
+        '  strategy             inspect current-turn memory policy and read-only outcome telemetry',
+        '  brain-eval           evaluate recall, provenance, leakage, budget, and false activation',
+        '  episode              append, import, inspect, seal, or repair conversation episodes',
+        '  dream                conditionally process sealed episode backlog',
+        '',
+        'JSON output: commands with --json emit cogmem.cli.v1. Object fields stay top-level; arrays use items.',
+        'Queue commands expose candidate, promoted, needs_confirmation, and beliefs at the top level.',
+    ].join('\n');
+}
+function siblingEntrypoint(command) {
+    const base = dirname(fileURLToPath(import.meta.url));
+    const jsPath = join(base, `${command}.js`);
+    if (existsSync(jsPath))
+        return jsPath;
+    return join(base, `${command}.ts`);
+}
+async function main() {
+    const [command, ...rest] = process.argv.slice(2);
+    if (!command || command === '--help' || command === '-h') {
+        console.log(usage());
+        return;
+    }
+    const entrypoint = COMMANDS[command];
+    if (!entrypoint) {
+        console.error(`Unknown cogmem command: ${command}`);
+        console.error(usage());
+        process.exit(1);
+    }
+    const proc = Bun.spawn({
+        cmd: [process.execPath || 'bun', siblingEntrypoint(entrypoint), ...rest],
+        cwd: process.cwd(),
+        stdout: 'pipe',
+        stderr: 'pipe',
+        env: process.env,
+    });
+    const stdout = await new Response(proc.stdout).text();
+    const stderr = await new Response(proc.stderr).text();
+    await Bun.write(Bun.stdout, stdout);
+    await Bun.write(Bun.stderr, stderr);
+    process.exit(await proc.exited);
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/dist/bin/compact.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+export {};
+//# sourceMappingURL=compact.d.ts.map

package/dist/bin/compact.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env bun
+import { loadCogmemConfig, resolveCogmemConfigPath } from '../config/CogmemConfig.js';
+import { DEFAULT_VECTOR_DIMENSION, parseVectorDimensionValue } from '../config/VectorDimension.js';
+import { compactStorage } from '../storage/StorageCompactor.js';
+import { printCliJson } from './CliJson.js';
+function parseArgs(argv) {
+    let dbPath = '';
+    let configPath = '';
+    let dimension;
+    let projectId = '';
+    let statuses;
+    let dryRun = false;
+    let apply = false;
+    let json = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--db')
+            dbPath = argv[++index] ?? '';
+        else if (arg === '--config')
+            configPath = argv[++index] ?? '';
+        else if (arg === '--dimension')
+            dimension = parseDimensionArg(argv[++index], '--dimension');
+        else if (arg === '--project')
+            projectId = argv[++index] ?? '';
+        else if (arg === '--status')
+            statuses = parseStatuses(argv[++index] ?? '');
+        else if (arg === '--dry-run')
+            dryRun = true;
+        else if (arg === '--apply')
+            apply = true;
+        else if (arg === '--json')
+            json = true;
+    }
+    if (!dryRun && !apply)
+        dryRun = true;
+    if (dryRun && apply)
+        throw new Error('Use either --dry-run or --apply, not both.');
+    return {
+        dbPath: dbPath || undefined,
+        configPath: configPath || undefined,
+        dimension,
+        projectId: projectId || undefined,
+        statuses,
+        dryRun,
+        json,
+    };
+}
+function parseDimensionArg(value, label) {
+    if (!value || value.startsWith('--'))
+        throw new Error(`${label} must be a positive integer.`);
+    const diagnostics = [];
+    const dimension = parseVectorDimensionValue(value, label, diagnostics);
+    const error = diagnostics.find((diagnostic) => diagnostic.severity === 'error');
+    if (error || dimension === undefined)
+        throw new Error(error?.message ?? `${label} must be a positive integer.`);
+    return dimension;
+}
+function parseStatuses(value) {
+    const allowed = new Set(['cold', 'suspect', 'archived']);
+    const statuses = value.split(',').map((item) => item.trim()).filter(Boolean);
+    for (const status of statuses) {
+        if (!allowed.has(status))
+            throw new Error('--status must contain only cold,suspect,archived');
+    }
+    return statuses;
+}
+async function main() {
+    const args = parseArgs(Bun.argv.slice(2));
+    const resolution = args.configPath ? resolveCogmemConfigPath({ configPath: args.configPath }) : resolveCogmemConfigPath();
+    const loaded = resolution.kind === 'toml' ? loadCogmemConfig({ configPath: resolution.path }) : undefined;
+    const dbPath = args.dbPath || loaded?.options.dbPath;
+    if (!dbPath) {
+        throw new Error('Usage: cogmem compact [--config <config.toml>|--db <memory.db>] [--status archived,suspect,cold] [--dimension 384] [--dry-run|--apply] [--json]');
+    }
+    const result = compactStorage({
+        dbPath,
+        dryRun: args.dryRun,
+        statuses: args.statuses,
+        projectId: args.projectId,
+        dimension: args.dimension ?? loaded?.options.vectorDimension ?? DEFAULT_VECTOR_DIMENSION,
+    });
+    if (args.json) {
+        printCliJson('compact', result);
+        return;
+    }
+    console.log(`cogmem compact ${result.dryRun ? 'dry-run' : 'applied'}`);
+    console.log(`raw events deleted: ${result.rawEventsDeleted}`);
+    console.log(`eligible vectors: ${result.eligibleVectorCount}`);
+    console.log(`vectors deleted: ${result.vectorsDeleted}`);
+    console.log(`vector bytes before: ${result.vectorBytesBefore}`);
+    console.log(`vector bytes after: ${result.vectorBytesAfter}`);
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/dist/bin/connect.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+export {};
+//# sourceMappingURL=connect.d.ts.map