@cogmem/engram 0.0.0

package/src/cli/commands/health.ts

@@ -0,0 +1,82 @@
+import { defineCommand } from "citty";
+import { EngramEngine } from "../../core/engine.ts";
+import { focusUtilization } from "../../core/working-memory.ts";
+import { refreshActivations } from "../../core/forgetting.ts";
+import { bold, dim, green, yellow, red, isInteractive } from "../format.ts";
+
+export const healthCommand = defineCommand({
+  meta: {
+    name: "health",
+    description: "Brain health check — diagnose memory system issues",
+  },
+  run() {
+    const engine = EngramEngine.create();
+    try {
+      const { atRisk } = refreshActivations(engine.storage, engine.config);
+      const { used, capacity } = focusUtilization(engine.storage, engine.config);
+      const lastConsolidation = engine.storage.getLastConsolidation();
+      const totalMemories = engine.storage.getMemoryCount();
+      const associationCount = engine.storage.getAssociationCount();
+
+      if (!isInteractive()) {
+        const hoursAgo = lastConsolidation
+          ? (Date.now() - lastConsolidation.ranAt) / 3600000
+          : null;
+        console.log(
+          JSON.stringify({
+            atRisk,
+            workingMemory: { used, capacity },
+            totalMemories,
+            associations: associationCount,
+            lastConsolidationHoursAgo: hoursAgo ? Math.round(hoursAgo) : null,
+          }),
+        );
+        return;
+      }
+
+      console.log(bold("  engram — health check\n"));
+
+      if (atRisk > 0) {
+        console.log(yellow(`  ! ${atRisk} memories at risk of being forgotten`));
+      } else {
+        console.log(green("  + All memories above retrieval threshold"));
+      }
+
+      if (used <= capacity) {
+        console.log(green(`  + Working memory within capacity (${used}/${capacity})`));
+      } else {
+        console.log(red(`  ! Working memory over capacity (${used}/${capacity})`));
+      }
+
+      if (lastConsolidation) {
+        const hoursAgo = (Date.now() - lastConsolidation.ranAt) / 3600000;
+        if (hoursAgo > 18) {
+          console.log(red(`  ! Consolidation overdue (last: ${Math.round(hoursAgo)}h ago)`));
+        } else if (hoursAgo > 8) {
+          console.log(
+            yellow(`  ~ Consolidation recommended soon (last: ${Math.round(hoursAgo)}h ago)`),
+          );
+        } else {
+          console.log(green(`  + Consolidation recent (last: ${Math.round(hoursAgo)}h ago)`));
+        }
+      } else if (totalMemories > 0) {
+        console.log(yellow("  ! No consolidation has ever run — run `engram sleep`"));
+      } else {
+        console.log(dim("  ~ No memories encoded yet"));
+      }
+
+      if (totalMemories > 5 && associationCount === 0) {
+        console.log(yellow("  ! No associations formed — run `engram sleep` to discover links"));
+      } else if (associationCount > 0) {
+        const ratio = associationCount / Math.max(1, totalMemories);
+        if (ratio > 1) {
+          console.log(green(`  + Association network is rich (${associationCount} links)`));
+        } else {
+          console.log(green(`  + Association network is healthy (${associationCount} links)`));
+        }
+      }
+    } finally {
+      engine.close();
+    }
+  },
+});

package/src/cli/commands/inspect.ts

@@ -0,0 +1,36 @@
+import { defineCommand } from "citty";
+import { EngramEngine } from "../../core/engine.ts";
+import { formatMemoryInspection, dim } from "../format.ts";
+
+export const inspectCommand = defineCommand({
+  meta: {
+    name: "inspect",
+    description: "Examine a memory's full lifecycle",
+  },
+  args: {
+    id: {
+      type: "positional",
+      description: "Memory ID (or prefix) to inspect",
+      required: true,
+    },
+  },
+  run({ args }) {
+    const engine = EngramEngine.create();
+    try {
+      const allMemories = engine.storage.getAllMemories();
+      const match = allMemories.find((m) => m.id === args.id || m.id.startsWith(args.id));
+
+      if (!match) {
+        console.log(dim(`  No memory found matching "${args.id}"`));
+        return;
+      }
+
+      const accessLog = engine.storage.getAccessLog(match.id);
+      const associations = engine.storage.getAssociations(match.id);
+
+      console.log(formatMemoryInspection(match, accessLog.length, associations.length));
+    } finally {
+      engine.close();
+    }
+  },
+});

package/src/cli/commands/list.ts

@@ -0,0 +1,58 @@
+import { defineCommand } from "citty";
+import { EngramEngine } from "../../core/engine.ts";
+import { isValidMemoryType } from "../../core/memory.ts";
+import { formatMemoryList } from "../format.ts";
+
+export const listCommand = defineCommand({
+  meta: {
+    name: "list",
+    description: "Browse stored memories (read-only, no activation effects)",
+  },
+  args: {
+    type: {
+      type: "string",
+      description: "Filter by memory type (episodic, semantic, procedural)",
+    },
+    context: {
+      type: "string",
+      description: "Filter by context prefix (e.g. project:acme)",
+    },
+    all: {
+      type: "boolean",
+      description: "Show all memories regardless of context",
+      default: false,
+    },
+    limit: {
+      type: "string",
+      description: "Maximum number of results",
+      alias: "n",
+      default: "20",
+    },
+  },
+  run({ args }) {
+    const engine = EngramEngine.create();
+    try {
+      const type = args.type && isValidMemoryType(args.type) ? args.type : undefined;
+      const limit = Number(args.limit);
+
+      let memories;
+      let displayContext: string | null = null;
+
+      if (args.all) {
+        memories = engine.storage.getAllMemories(type).slice(0, limit);
+      } else {
+        const context = args.context ?? engine.projectContext;
+        if (context) {
+          displayContext = context;
+          memories = engine.storage.getMemoriesByContext(context, type, limit);
+        } else {
+          memories = engine.storage.getAllMemories(type).slice(0, limit);
+        }
+      }
+
+      console.log(formatMemoryList(memories, displayContext));
+    } finally {
+      engine.close();
+    }
+  },
+});

package/src/cli/commands/recall.ts

@@ -0,0 +1,55 @@
+import { defineCommand } from "citty";
+import { EngramEngine } from "../../core/engine.ts";
+import { recall } from "../../core/recall.ts";
+import { formatRecallResults } from "../format.ts";
+import { isValidMemoryType } from "../../core/memory.ts";
+
+export const recallCommand = defineCommand({
+  meta: {
+    name: "recall",
+    description: "Retrieve memories by cue (associative recall)",
+  },
+  args: {
+    cue: {
+      type: "positional",
+      description: "The recall cue — what you're trying to remember",
+      required: true,
+    },
+    type: {
+      type: "string",
+      description: "Filter by memory type (episodic, semantic, procedural)",
+    },
+    context: {
+      type: "string",
+      description: "Filter by context tag",
+    },
+    limit: {
+      type: "string",
+      description: "Maximum number of results",
+      alias: "n",
+      default: "10",
+    },
+    noAssociative: {
+      type: "boolean",
+      description: "Disable spreading activation",
+      default: false,
+    },
+  },
+  run({ args }) {
+    const engine = EngramEngine.create();
+    try {
+      const typeFilter = args.type && isValidMemoryType(args.type) ? args.type : undefined;
+
+      const results = recall(engine.storage, args.cue, engine.config, {
+        type: typeFilter,
+        context: args.context ?? engine.projectContext ?? undefined,
+        limit: Number(args.limit),
+        associative: !args.noAssociative,
+      });
+
+      console.log(formatRecallResults(results));
+    } finally {
+      engine.close();
+    }
+  },
+});

package/src/cli/commands/sleep.ts

@@ -0,0 +1,102 @@
+import { defineCommand } from "citty";
+import { EngramEngine } from "../../core/engine.ts";
+import { consolidate } from "../../core/consolidation.ts";
+import { discoverChunks } from "../../core/chunking.ts";
+import { bold, dim, green, cyan, isInteractive } from "../format.ts";
+
+export const sleepCommand = defineCommand({
+  meta: {
+    name: "sleep",
+    description: "Run consolidation cycle (replay, strengthen, prune, extract, link)",
+  },
+  args: {
+    report: {
+      type: "boolean",
+      description: "Show detailed consolidation report",
+      default: false,
+    },
+  },
+  run({ args }) {
+    const engine = EngramEngine.create();
+    try {
+      const result = consolidate(engine.storage, engine.config);
+      const chunks = discoverChunks(engine.storage, engine.config);
+
+      if (!isInteractive()) {
+        console.log(
+          JSON.stringify({
+            memoriesStrengthened: result.memoriesStrengthened,
+            memoriesPruned: result.memoriesPruned,
+            factsExtracted: result.factsExtracted,
+            associationsDiscovered: result.associationsDiscovered,
+            chunksFormed: chunks.length,
+            ...(args.report
+              ? {
+                  extractedFacts: result.extractedFacts,
+                  prunedIds: result.prunedIds,
+                  chunks: chunks.map((c) => ({
+                    id: c.id,
+                    label: c.label,
+                    members: c.memberIds.length,
+                  })),
+                }
+              : {}),
+          }),
+        );
+        return;
+      }
+
+      console.log(dim("  Running consolidation cycle...\n"));
+      console.log(green("  Consolidation complete:\n"));
+      console.log(
+        `  ${cyan("Strengthened")} ${result.memoriesStrengthened} frequently-accessed memories`,
+      );
+      console.log(
+        `  ${cyan("Pruned")}       ${result.memoriesPruned} memories below activation threshold`,
+      );
+      console.log(
+        `  ${cyan("Extracted")}    ${result.factsExtracted} semantic facts from episodic patterns`,
+      );
+      console.log(`  ${cyan("Discovered")}   ${result.associationsDiscovered} new associations`);
+      if (chunks.length > 0) {
+        console.log(`  ${cyan("Chunked")}      ${chunks.length} new memory groups`);
+      }
+
+      if (args.report) {
+        console.log(dim("\n  ─── Detailed Report ───────────────────────\n"));
+
+        if (result.extractedFacts.length > 0) {
+          console.log(bold("  Extracted Facts:"));
+          for (const fact of result.extractedFacts) {
+            console.log(`    ${dim(">")} ${fact}`);
+          }
+          console.log("");
+        }
+
+        if (result.prunedIds.length > 0) {
+          console.log(bold("  Pruned Memories:"));
+          for (const id of result.prunedIds) {
+            console.log(`    ${dim(">")} ${id.slice(0, 8)}`);
+          }
+          console.log("");
+        }
+
+        if (chunks.length > 0) {
+          console.log(bold("  New Chunks:"));
+          for (const chunk of chunks) {
+            console.log(`    ${dim(">")} ${chunk.label} (${chunk.memberIds.length} memories)`);
+          }
+          console.log("");
+        }
+
+        if (result.discoveredAssociationPairs.length > 0) {
+          console.log(
+            bold(`  Associations Discovered: ${result.discoveredAssociationPairs.length}`),
+          );
+        }
+      }
+    } finally {
+      engine.close();
+    }
+  },
+});

package/src/cli/commands/stats.ts

@@ -0,0 +1,95 @@
+import { defineCommand } from "citty";
+import { EngramEngine } from "../../core/engine.ts";
+import { focusUtilization } from "../../core/working-memory.ts";
+import { bold, dim, green, yellow, red, isInteractive } from "../format.ts";
+import { refreshActivations } from "../../core/forgetting.ts";
+
+export const statsCommand = defineCommand({
+  meta: {
+    name: "stats",
+    description: "Memory system health overview",
+  },
+  run() {
+    const engine = EngramEngine.create();
+    try {
+      const { atRisk } = refreshActivations(engine.storage, engine.config);
+
+      const episodicCount = engine.storage.getMemoryCount("episodic");
+      const semanticCount = engine.storage.getMemoryCount("semantic");
+      const proceduralCount = engine.storage.getMemoryCount("procedural");
+      const associationCount = engine.storage.getAssociationCount();
+      const { used, capacity } = focusUtilization(engine.storage, engine.config);
+
+      const lastConsolidation = engine.storage.getLastConsolidation();
+
+      const projectContext = engine.projectContext;
+      const projectCounts = projectContext
+        ? {
+            episodic: engine.storage.getMemoryCountByContext(projectContext, "episodic"),
+            semantic: engine.storage.getMemoryCountByContext(projectContext, "semantic"),
+            procedural: engine.storage.getMemoryCountByContext(projectContext, "procedural"),
+            total: engine.storage.getMemoryCountByContext(projectContext),
+          }
+        : null;
+
+      if (!isInteractive()) {
+        console.log(
+          JSON.stringify({
+            workingMemory: { used, capacity },
+            episodic: episodicCount,
+            semantic: semanticCount,
+            procedural: proceduralCount,
+            associations: associationCount,
+            atRisk,
+            lastConsolidation: lastConsolidation ? { ranAt: lastConsolidation.ranAt } : null,
+            ...(projectCounts ? { project: { context: projectContext, ...projectCounts } } : {}),
+          }),
+        );
+        return;
+      }
+
+      console.log(bold("  engram — memory system stats\n"));
+
+      const wmStatus =
+        used >= capacity
+          ? red(`${used}/${capacity} slots used (FULL)`)
+          : used > capacity * 0.7
+            ? yellow(`${used}/${capacity} slots used`)
+            : green(`${used}/${capacity} slots used`);
+      console.log(`  Working Memory:  ${wmStatus}`);
+
+      console.log(
+        `  Episodic:        ${episodicCount} memories` +
+          (atRisk > 0 ? ` ${yellow(`(${atRisk} at risk of forgetting)`)}` : ""),
+      );
+      console.log(`  Semantic:        ${semanticCount} facts`);
+      console.log(`  Procedural:      ${proceduralCount} skills ${dim("(immune to decay)")}`);
+
+      console.log(`  Associations:    ${associationCount} links`);
+
+      if (lastConsolidation) {
+        const hoursAgo = Math.round((Date.now() - lastConsolidation.ranAt) / 3600000);
+        const consolidationStatus =
+          hoursAgo > 12
+            ? red(`${hoursAgo}h ago (overdue)`)
+            : hoursAgo > 6
+              ? yellow(`${hoursAgo}h ago`)
+              : green(`${hoursAgo}h ago`);
+        console.log(`  Last sleep:      ${consolidationStatus}`);
+      } else {
+        console.log(`  Last sleep:      ${dim("never")}`);
+      }
+
+      if (projectCounts) {
+        console.log("");
+        console.log(bold(`  project: ${projectContext}\n`));
+        console.log(`  Episodic:        ${projectCounts.episodic} memories`);
+        console.log(`  Semantic:        ${projectCounts.semantic} facts`);
+        console.log(`  Procedural:      ${projectCounts.procedural} skills`);
+        console.log(dim(`  Total:           ${projectCounts.total} memories`));
+      }
+    } finally {
+      engine.close();
+    }
+  },
+});

package/src/cli/format.ts

@@ -0,0 +1,231 @@
+import type { Memory, RecallResult } from "../core/memory.ts";
+import kleur from "kleur";
+import Table from "cli-table3";
+import dayjs from "dayjs";
+import relativeTime from "dayjs/plugin/relativeTime.js";
+
+dayjs.extend(relativeTime);
+
+export function isInteractive(): boolean {
+  return !!process.stdout.isTTY;
+}
+
+const dim = (s: string) => kleur.dim(s);
+const bold = (s: string) => kleur.bold(s);
+const green = (s: string) => kleur.green(s);
+const yellow = (s: string) => kleur.yellow(s);
+const red = (s: string) => kleur.red(s);
+const cyan = (s: string) => kleur.cyan(s);
+const magenta = (s: string) => kleur.magenta(s);
+
+export function formatMemoryEncoded(memory: Memory): string {
+  if (!isInteractive()) {
+    return JSON.stringify({
+      id: memory.id,
+      type: memory.type,
+      content: memory.content,
+      activation: memory.activation,
+      emotion: memory.emotion,
+      context: memory.context,
+    });
+  }
+
+  const lines: string[] = [];
+  lines.push(green("  Encoded memory") + dim(` [${memory.id.slice(0, 8)}]`));
+  lines.push(`  ${bold(memory.content)}`);
+  lines.push(
+    dim(`  type: ${memory.type}`) +
+      (memory.emotion !== "neutral"
+        ? ` ${dim("emotion:")} ${formatEmotion(memory.emotion, memory.emotionWeight)}`
+        : "") +
+      (memory.context ? ` ${dim("context:")} ${memory.context}` : ""),
+  );
+  lines.push(dim(`  activation: ${memory.activation.toFixed(3)}`));
+  return lines.join("\n");
+}
+
+export function formatRecallResults(results: RecallResult[]): string {
+  if (!isInteractive()) {
+    return JSON.stringify(
+      results.map((r) => ({
+        id: r.memory.id,
+        content: r.memory.content,
+        context: r.memory.context,
+        activation: r.activation,
+      })),
+    );
+  }
+
+  if (results.length === 0) {
+    return dim("  No memories found above retrieval threshold.");
+  }
+
+  const lines: string[] = [];
+  for (const result of results) {
+    const m = result.memory;
+    const activationColor = result.activation > 0.5 ? green : result.activation > 0 ? yellow : red;
+
+    lines.push(`  ${activationColor("●")} ${bold(m.content)} ` + dim(`[${m.id.slice(0, 8)}]`));
+
+    const meta: string[] = [];
+    meta.push(`type: ${m.type}`);
+    meta.push(`activation: ${result.activation.toFixed(3)}`);
+    if (m.recallCount > 0) meta.push(`recalled: ${m.recallCount}x`);
+    if (result.spreadingActivation > 0) {
+      meta.push(`spreading: +${result.spreadingActivation.toFixed(3)}`);
+    }
+    if (m.emotion !== "neutral") {
+      meta.push(`emotion: ${formatEmotion(m.emotion, m.emotionWeight)}`);
+    }
+    if (m.context) meta.push(`context: ${m.context}`);
+
+    lines.push(dim(`    ${meta.join(" | ")}`));
+    lines.push(
+      dim(`    latency: ${result.latency.toFixed(0)}ms`) +
+        dim(` | encoded: ${formatTimeAgo(m.encodedAt)}`),
+    );
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+function formatEmotion(emotion: string, weight: number): string {
+  const w = weight.toFixed(1);
+  switch (emotion) {
+    case "anxiety":
+      return red(`${emotion}(${w})`);
+    case "frustration":
+      return red(`${emotion}(${w})`);
+    case "joy":
+      return green(`${emotion}(${w})`);
+    case "satisfaction":
+      return green(`${emotion}(${w})`);
+    case "surprise":
+      return yellow(`${emotion}(${w})`);
+    case "curiosity":
+      return cyan(`${emotion}(${w})`);
+    default:
+      return dim(`${emotion}(${w})`);
+  }
+}
+
+export function formatTimeAgo(timestamp: number): string {
+  return dayjs(timestamp).fromNow();
+}
+
+export function formatMemoryInspection(
+  memory: Memory,
+  accessCount: number,
+  associationCount: number,
+): string {
+  if (!isInteractive()) {
+    return JSON.stringify({
+      id: memory.id,
+      type: memory.type,
+      content: memory.content,
+      encodedAt: memory.encodedAt,
+      lastRecalledAt: memory.lastRecalledAt,
+      recallCount: memory.recallCount,
+      activation: memory.activation,
+      emotion: memory.emotion,
+      emotionWeight: memory.emotionWeight,
+      context: memory.context,
+      chunkId: memory.chunkId,
+      reconsolidationCount: memory.reconsolidationCount,
+      accessCount,
+      associationCount,
+    });
+  }
+
+  const lines: string[] = [];
+  lines.push(bold(`Memory [${memory.id.slice(0, 8)}]`));
+  lines.push(`  ${bold(memory.content)}`);
+  lines.push("");
+  lines.push(dim("  Lifecycle:"));
+  lines.push(`    Type:           ${memory.type}`);
+  lines.push(`    Encoded:        ${new Date(memory.encodedAt).toISOString()}`);
+  lines.push(
+    `    Last recalled:  ${memory.lastRecalledAt ? new Date(memory.lastRecalledAt).toISOString() : "never"}`,
+  );
+  lines.push(`    Recall count:   ${memory.recallCount}`);
+  lines.push(`    Reconsolidations: ${memory.reconsolidationCount}`);
+  lines.push("");
+  lines.push(dim("  Activation:"));
+  lines.push(`    Current:        ${memory.activation.toFixed(4)}`);
+  lines.push(`    Emotion:        ${formatEmotion(memory.emotion, memory.emotionWeight)}`);
+  lines.push(`    Associations:   ${associationCount} links`);
+  lines.push(`    Total accesses: ${accessCount}`);
+  if (memory.context) {
+    lines.push(`    Context:        ${memory.context}`);
+  }
+  if (memory.chunkId) {
+    lines.push(`    Chunk:          ${memory.chunkId.slice(0, 8)}`);
+  }
+  return lines.join("\n");
+}
+
+export function formatMemoryList(memories: Memory[], context?: string | null): string {
+  if (!isInteractive()) {
+    return JSON.stringify(
+      memories.map((m) => ({
+        id: m.id,
+        type: m.type,
+        content: m.content,
+        activation: m.activation,
+        recallCount: m.recallCount,
+        emotion: m.emotion,
+        context: m.context,
+        encodedAt: m.encodedAt,
+      })),
+    );
+  }
+
+  if (memories.length === 0) {
+    return context
+      ? dim(`  No memories found for context: ${context}`)
+      : dim("  No memories found.");
+  }
+
+  const table = new Table({
+    head: ["", "content", "id", "type", "act.", "recalls", "emotion", "encoded"],
+    style: { head: ["dim"], border: ["dim"] },
+    chars: {
+      top: "─",
+      "top-mid": "┬",
+      "top-left": "┌",
+      "top-right": "┐",
+      bottom: "─",
+      "bottom-mid": "┴",
+      "bottom-left": "└",
+      "bottom-right": "┘",
+      left: "│",
+      "left-mid": "├",
+      mid: "─",
+      "mid-mid": "┼",
+      right: "│",
+      "right-mid": "┤",
+      middle: "│",
+    },
+  });
+
+  for (const m of memories) {
+    const activationColor = m.activation > 0.5 ? green : m.activation > 0 ? yellow : red;
+    const emotionStr =
+      m.emotion !== "neutral" ? formatEmotion(m.emotion, m.emotionWeight) : dim("—");
+
+    table.push([
+      activationColor("●"),
+      m.content,
+      dim(m.id.slice(0, 8)),
+      m.type,
+      m.activation.toFixed(3),
+      m.recallCount > 0 ? `${m.recallCount}x` : dim("—"),
+      emotionStr,
+      formatTimeAgo(m.encodedAt),
+    ]);
+  }
+
+  return table.toString();
+}
+
+export { dim, bold, green, yellow, red, cyan, magenta };

package/src/cli/index.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env bun
+import { defineCommand, runMain } from "citty";
+import pkg from "../../package.json";
+import { encodeCommand } from "./commands/encode.ts";
+import { recallCommand } from "./commands/recall.ts";
+import { focusCommand } from "./commands/focus.ts";
+import { inspectCommand } from "./commands/inspect.ts";
+import { statsCommand } from "./commands/stats.ts";
+import { listCommand } from "./commands/list.ts";
+import { sleepCommand } from "./commands/sleep.ts";
+import { healthCommand } from "./commands/health.ts";
+
+const main = defineCommand({
+  meta: {
+    name: "engram",
+    version: pkg.version,
+    description: "Human memory for artificial minds",
+  },
+  subCommands: {
+    encode: encodeCommand,
+    recall: recallCommand,
+    focus: focusCommand,
+    inspect: inspectCommand,
+    list: listCommand,
+    stats: statsCommand,
+    sleep: sleepCommand,
+    health: healthCommand,
+  },
+});
+
+runMain(main);