@cogmem/engram 0.2.1 → 0.3.1

package/src/cli/commands/health.ts

@@ -1,7 +1,8 @@
 import { defineCommand } from "citty";
+
 import { EngramEngine } from "../../core/engine.ts";
-import { focusUtilization } from "../../core/working-memory.ts";
 import { refreshActivations } from "../../core/forgetting.ts";
+import { focusUtilization } from "../../core/working-memory.ts";
 import { bold, dim, green, yellow, red, isInteractive } from "../format.ts";
 
 export const healthCommand = defineCommand({
@@ -13,7 +14,10 @@ export const healthCommand = defineCommand({
     const engine = EngramEngine.create();
     try {
       const { atRisk } = refreshActivations(engine.storage, engine.config);
-      const { used, capacity } = focusUtilization(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();
@@ -29,7 +33,7 @@ export const healthCommand = defineCommand({
             totalMemories,
             associations: associationCount,
             lastConsolidationHoursAgo: hoursAgo ? Math.round(hoursAgo) : null,
-          }),
+          })
         );
         return;
       }
@@ -37,42 +41,72 @@ export const healthCommand = defineCommand({
       console.log(bold("  engram — health check\n"));
 
       if (atRisk > 0) {
-        console.log(yellow(`  ! ${atRisk} memories at risk of being forgotten`));
+        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})`));
+        console.log(
+          green(`  + Working memory within capacity (${used}/${capacity})`)
+        );
       } else {
-        console.log(red(`  ! Working memory over capacity (${used}/${capacity})`));
+        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)`));
+          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)`),
+            yellow(
+              `  ~ Consolidation recommended soon (last: ${Math.round(
+                hoursAgo
+              )}h ago)`
+            )
           );
         } else {
-          console.log(green(`  + Consolidation recent (last: ${Math.round(hoursAgo)}h ago)`));
+          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`"));
+        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"));
+        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)`));
+          console.log(
+            green(`  + Association network is rich (${associationCount} links)`)
+          );
         } else {
-          console.log(green(`  + Association network is healthy (${associationCount} links)`));
+          console.log(
+            green(
+              `  + Association network is healthy (${associationCount} links)`
+            )
+          );
         }
       }
     } finally {

package/src/cli/commands/inspect.ts

@@ -1,4 +1,5 @@
 import { defineCommand } from "citty";
+
 import { EngramEngine } from "../../core/engine.ts";
 import { formatMemoryInspection, dim } from "../format.ts";
 
@@ -18,7 +19,9 @@ export const inspectCommand = defineCommand({
     const engine = EngramEngine.create();
     try {
       const allMemories = engine.storage.getAllMemories();
-      const match = allMemories.find((m) => m.id === args.id || m.id.startsWith(args.id));
+      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}"`));
@@ -28,7 +31,9 @@ export const inspectCommand = defineCommand({
       const accessLog = engine.storage.getAccessLog(match.id);
       const associations = engine.storage.getAssociations(match.id);
 
-      console.log(formatMemoryInspection(match, accessLog.length, associations.length));
+      console.log(
+        formatMemoryInspection(match, accessLog.length, associations.length)
+      );
     } finally {
       engine.close();
     }

package/src/cli/commands/install.ts

@@ -0,0 +1,122 @@
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { defineCommand } from "citty";
+import { consola } from "consola";
+
+import { green, dim, yellow, bold } from "../format.ts";
+import { getProvider, availableProviders } from "../providers/index.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SKILL_PATH = join(__dirname, "..", "..", "..", "SKILL.md");
+
+function loadSkillContent(): string {
+  return readFileSync(SKILL_PATH, "utf-8");
+}
+
+export const installCommand = defineCommand({
+  meta: {
+    name: "install",
+    description: "Install engram skill + MCP config for your AI editor",
+  },
+  args: {
+    provider: {
+      type: "string",
+      description: "Provider to install for (claude)",
+      alias: "p",
+    },
+    global: {
+      type: "boolean",
+      description: "Install globally (~/.claude/)",
+      alias: "g",
+    },
+    project: {
+      type: "boolean",
+      description: "Install to current project directory",
+    },
+    dryRun: {
+      type: "boolean",
+      description: "Show what would be installed without writing files",
+      alias: "n",
+    },
+  },
+  async run({ args }) {
+    const dryRun = args.dryRun ?? false;
+
+    let providerName = args.provider;
+    if (!providerName) {
+      const choices = availableProviders.map((p) => ({
+        label: p.available ? p.displayName : `${p.displayName} (coming soon)`,
+        value: p.name,
+        disabled: !p.available,
+      }));
+
+      providerName = (await consola.prompt("Select a provider", {
+        type: "select",
+        options: choices,
+      })) as unknown as string;
+
+      if (typeof providerName === "symbol") process.exit(0);
+    }
+
+    const provider = getProvider(providerName);
+    if (!provider) {
+      consola.error(`Unknown provider: ${providerName}`);
+      process.exit(1);
+    }
+    if (!provider.available) {
+      consola.error(`${provider.displayName} is not yet supported`);
+      process.exit(1);
+    }
+
+    let scope: "global" | "project" | undefined;
+    if (args.global) scope = "global";
+    else if (args.project) scope = "project";
+
+    if (!scope) {
+      scope = (await consola.prompt("Install scope", {
+        type: "select",
+        options: [
+          { label: `Global (~/.claude/)`, value: "global" },
+          { label: `Project (./.claude/)`, value: "project" },
+        ],
+      })) as unknown as "global" | "project";
+
+      if (typeof scope === "symbol") process.exit(0);
+    }
+
+    const skillContent = loadSkillContent();
+
+    if (dryRun) console.log(yellow("\n  dry run — no files will be written\n"));
+
+    const result =
+      scope === "global"
+        ? await provider.installGlobal(skillContent, dryRun)
+        : await provider.installProject(skillContent, process.cwd(), dryRun);
+
+    if (result.status === "already_installed") {
+      console.log(dim("  already installed — nothing to do"));
+      console.log(dim(`  skill: ${result.skillPath}`));
+      if (result.mcpConfigPath)
+        console.log(dim(`  mcp:   ${result.mcpConfigPath}`));
+      return;
+    }
+
+    const prefix = dryRun ? "would install" : "installed";
+    const check = dryRun ? yellow("~") : green("\u2713");
+
+    console.log(
+      `  ${check} Skill ${prefix} ${dim("\u2192")} ${bold(result.skillPath)}`
+    );
+    if (result.mcpConfigured && result.mcpConfigPath) {
+      console.log(
+        `  ${check} MCP ${prefix}   ${dim("\u2192")} ${bold(
+          result.mcpConfigPath
+        )}`
+      );
+    } else if (result.mcpConfigPath) {
+      console.log(dim(`  - MCP already configured → ${result.mcpConfigPath}`));
+    }
+  },
+});

package/src/cli/commands/list.ts

@@ -1,4 +1,5 @@
 import { defineCommand } from "citty";
+
 import { EngramEngine } from "../../core/engine.ts";
 import { isValidMemoryType } from "../../core/memory.ts";
 import { formatMemoryList } from "../format.ts";
@@ -32,7 +33,8 @@ export const listCommand = defineCommand({
   run({ args }) {
     const engine = EngramEngine.create();
     try {
-      const type = args.type && isValidMemoryType(args.type) ? args.type : undefined;
+      const type =
+        args.type && isValidMemoryType(args.type) ? args.type : undefined;
       const limit = Number(args.limit);
 
       let memories;

package/src/cli/commands/recall.ts

@@ -1,8 +1,9 @@
 import { defineCommand } from "citty";
+
 import { EngramEngine } from "../../core/engine.ts";
+import { isValidMemoryType } from "../../core/memory.ts";
 import { recall } from "../../core/recall.ts";
 import { formatRecallResults } from "../format.ts";
-import { isValidMemoryType } from "../../core/memory.ts";
 
 export const recallCommand = defineCommand({
   meta: {
@@ -38,7 +39,8 @@ export const recallCommand = defineCommand({
   run({ args }) {
     const engine = EngramEngine.create();
     try {
-      const typeFilter = args.type && isValidMemoryType(args.type) ? args.type : undefined;
+      const typeFilter =
+        args.type && isValidMemoryType(args.type) ? args.type : undefined;
 
       const results = recall(engine.storage, args.cue, engine.config, {
         type: typeFilter,

package/src/cli/commands/sleep.ts

@@ -1,13 +1,15 @@
 import { defineCommand } from "citty";
-import { EngramEngine } from "../../core/engine.ts";
-import { consolidate } from "../../core/consolidation.ts";
+
 import { discoverChunks } from "../../core/chunking.ts";
+import { consolidate } from "../../core/consolidation.ts";
+import { EngramEngine } from "../../core/engine.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)",
+    description:
+      "Run consolidation cycle (replay, strengthen, prune, extract, link)",
   },
   args: {
     report: {
@@ -41,7 +43,7 @@ export const sleepCommand = defineCommand({
                   })),
                 }
               : {}),
-          }),
+          })
         );
         return;
       }
@@ -49,17 +51,29 @@ export const sleepCommand = defineCommand({
       console.log(dim("  Running consolidation cycle...\n"));
       console.log(green("  Consolidation complete:\n"));
       console.log(
-        `  ${cyan("Strengthened")} ${result.memoriesStrengthened} frequently-accessed memories`,
+        `  ${cyan("Strengthened")} ${
+          result.memoriesStrengthened
+        } frequently-accessed memories`
       );
       console.log(
-        `  ${cyan("Pruned")}       ${result.memoriesPruned} memories below activation threshold`,
+        `  ${cyan("Pruned")}       ${
+          result.memoriesPruned
+        } memories below activation threshold`
       );
       console.log(
-        `  ${cyan("Extracted")}    ${result.factsExtracted} semantic facts from episodic patterns`,
+        `  ${cyan("Extracted")}    ${
+          result.factsExtracted
+        } semantic facts from episodic patterns`
+      );
+      console.log(
+        `  ${cyan("Discovered")}   ${
+          result.associationsDiscovered
+        } new associations`
       );
-      console.log(`  ${cyan("Discovered")}   ${result.associationsDiscovered} new associations`);
       if (chunks.length > 0) {
-        console.log(`  ${cyan("Chunked")}      ${chunks.length} new memory groups`);
+        console.log(
+          `  ${cyan("Chunked")}      ${chunks.length} new memory groups`
+        );
       }
 
       if (args.report) {
@@ -84,14 +98,20 @@ export const sleepCommand = defineCommand({
         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(
+              `    ${dim(">")} ${chunk.label} (${
+                chunk.memberIds.length
+              } memories)`
+            );
           }
           console.log("");
         }
 
         if (result.discoveredAssociationPairs.length > 0) {
           console.log(
-            bold(`  Associations Discovered: ${result.discoveredAssociationPairs.length}`),
+            bold(
+              `  Associations Discovered: ${result.discoveredAssociationPairs.length}`
+            )
           );
         }
       }

package/src/cli/commands/stats.ts

@@ -1,8 +1,9 @@
 import { defineCommand } from "citty";
+
 import { EngramEngine } from "../../core/engine.ts";
+import { refreshActivations } from "../../core/forgetting.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: {
@@ -18,16 +19,28 @@ export const statsCommand = defineCommand({
       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 { 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"),
+            episodic: engine.storage.getMemoryCountByContext(
+              projectContext,
+              "episodic"
+            ),
+            semantic: engine.storage.getMemoryCountByContext(
+              projectContext,
+              "semantic"
+            ),
+            procedural: engine.storage.getMemoryCountByContext(
+              projectContext,
+              "procedural"
+            ),
             total: engine.storage.getMemoryCountByContext(projectContext),
           }
         : null;
@@ -41,9 +54,13 @@ export const statsCommand = defineCommand({
             procedural: proceduralCount,
             associations: associationCount,
             atRisk,
-            lastConsolidation: lastConsolidation ? { ranAt: lastConsolidation.ranAt } : null,
-            ...(projectCounts ? { project: { context: projectContext, ...projectCounts } } : {}),
-          }),
+            lastConsolidation: lastConsolidation
+              ? { ranAt: lastConsolidation.ranAt }
+              : null,
+            ...(projectCounts
+              ? { project: { context: projectContext, ...projectCounts } }
+              : {}),
+          })
         );
         return;
       }
@@ -54,27 +71,33 @@ export const statsCommand = defineCommand({
         used >= capacity
           ? red(`${used}/${capacity} slots used (FULL)`)
           : used > capacity * 0.7
-            ? yellow(`${used}/${capacity} slots used`)
-            : green(`${used}/${capacity} slots used`);
+          ? 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)`)}` : ""),
+          (atRisk > 0 ? ` ${yellow(`(${atRisk} at risk of forgetting)`)}` : "")
       );
       console.log(`  Semantic:        ${semanticCount} facts`);
-      console.log(`  Procedural:      ${proceduralCount} skills ${dim("(immune to decay)")}`);
+      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 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`);
+            ? yellow(`${hoursAgo}h ago`)
+            : green(`${hoursAgo}h ago`);
         console.log(`  Last sleep:      ${consolidationStatus}`);
       } else {
         console.log(`  Last sleep:      ${dim("never")}`);

package/src/cli/format.ts

@@ -1,8 +1,9 @@
-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";
+import kleur from "kleur";
+
+import type { Memory, RecallResult } from "../core/memory.ts";
 
 dayjs.extend(relativeTime);
 

package/src/cli/index.ts

@@ -1,14 +1,16 @@
 #!/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 { healthCommand } from "./commands/health.ts";
 import { inspectCommand } from "./commands/inspect.ts";
-import { statsCommand } from "./commands/stats.ts";
+import { installCommand } from "./commands/install.ts";
 import { listCommand } from "./commands/list.ts";
+import { recallCommand } from "./commands/recall.ts";
 import { sleepCommand } from "./commands/sleep.ts";
-import { healthCommand } from "./commands/health.ts";
+import { statsCommand } from "./commands/stats.ts";
 
 const main = defineCommand({
   meta: {
@@ -25,6 +27,7 @@ const main = defineCommand({
     stats: statsCommand,
     sleep: sleepCommand,
     health: healthCommand,
+    install: installCommand,
   },
 });
 

package/src/cli/providers/claude.ts

@@ -0,0 +1,100 @@
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import type { ProviderInstaller } from "./types.ts";
+
+const MCP_SERVER_CONFIG = {
+  command: "bunx",
+  args: ["-p", "@cogmem/engram", "engram-mcp"],
+};
+
+function ensureDir(dir: string) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+function readJsonFile(path: string): Record<string, unknown> {
+  if (!existsSync(path)) return {};
+  return JSON.parse(readFileSync(path, "utf-8"));
+}
+
+function writeJsonFile(path: string, data: Record<string, unknown>) {
+  writeFileSync(path, JSON.stringify(data, null, 2) + "\n");
+}
+
+function installSkill(skillDir: string, skillContent: string, dryRun: boolean): boolean {
+  const skillPath = join(skillDir, "SKILL.md");
+  if (existsSync(skillPath)) {
+    const existing = readFileSync(skillPath, "utf-8");
+    if (existing === skillContent) return false;
+  }
+  if (!dryRun) {
+    ensureDir(skillDir);
+    writeFileSync(skillPath, skillContent);
+  }
+  return true;
+}
+
+function configureMcp(configPath: string, dryRun: boolean): boolean {
+  const config = readJsonFile(configPath);
+  const servers = (config.mcpServers ?? {}) as Record<string, unknown>;
+  if (servers.engram) return false;
+  if (!dryRun) {
+    servers.engram = MCP_SERVER_CONFIG;
+    config.mcpServers = servers;
+    ensureDir(join(configPath, ".."));
+    writeJsonFile(configPath, config);
+  }
+  return true;
+}
+
+export const claudeProvider: ProviderInstaller = {
+  name: "claude",
+  displayName: "Claude Code",
+  available: true,
+
+  async installGlobal(skillContent, dryRun) {
+    const home = homedir();
+    const skillDir = join(home, ".claude", "skills", "engram");
+    const configPath = join(home, ".claude.json");
+
+    const skillInstalled = installSkill(skillDir, skillContent, dryRun);
+    const mcpInstalled = configureMcp(configPath, dryRun);
+
+    const status =
+      !skillInstalled && !mcpInstalled
+        ? "already_installed"
+        : skillInstalled && mcpInstalled
+          ? "installed"
+          : "updated";
+
+    return {
+      status,
+      skillPath: join(skillDir, "SKILL.md"),
+      mcpConfigured: mcpInstalled,
+      mcpConfigPath: configPath,
+    };
+  },
+
+  async installProject(skillContent, projectDir, dryRun) {
+    const skillDir = join(projectDir, ".claude", "skills", "engram");
+    const configPath = join(projectDir, ".mcp.json");
+
+    const skillInstalled = installSkill(skillDir, skillContent, dryRun);
+    const mcpInstalled = configureMcp(configPath, dryRun);
+
+    const status =
+      !skillInstalled && !mcpInstalled
+        ? "already_installed"
+        : skillInstalled && mcpInstalled
+          ? "installed"
+          : "updated";
+
+    return {
+      status,
+      skillPath: join(skillDir, "SKILL.md"),
+      mcpConfigured: mcpInstalled,
+      mcpConfigPath: configPath,
+    };
+  },
+};

package/src/cli/providers/index.ts

@@ -0,0 +1,12 @@
+import { claudeProvider } from "./claude.ts";
+import type { ProviderInstaller } from "./types.ts";
+
+const providers: Record<string, ProviderInstaller> = {
+  claude: claudeProvider,
+};
+
+export function getProvider(name: string): ProviderInstaller | undefined {
+  return providers[name];
+}
+
+export const availableProviders = Object.values(providers);

package/src/cli/providers/types.ts

@@ -0,0 +1,20 @@
+export type InstallStatus = "installed" | "already_installed" | "updated";
+
+export interface InstallResult {
+  status: InstallStatus;
+  skillPath: string;
+  mcpConfigured: boolean;
+  mcpConfigPath: string | null;
+}
+
+export interface ProviderInstaller {
+  name: string;
+  displayName: string;
+  available: boolean;
+  installGlobal(skillContent: string, dryRun: boolean): Promise<InstallResult>;
+  installProject(
+    skillContent: string,
+    projectDir: string,
+    dryRun: boolean
+  ): Promise<InstallResult>;
+}

package/src/config/defaults.ts

@@ -50,11 +50,14 @@ export function resolveDbPath(dbPath: string): string {
   return dbPath;
 }
 
-export function loadConfig(overrides?: Partial<CognitiveConfig>): CognitiveConfig {
+export function loadConfig(
+  overrides?: Partial<CognitiveConfig>
+): CognitiveConfig {
   const config = { ...DEFAULT_CONFIG, ...overrides };
 
   if (process.env.ENGRAM_DB_PATH) config.dbPath = process.env.ENGRAM_DB_PATH;
-  if (process.env.ENGRAM_DECAY_RATE) config.decayRate = Number(process.env.ENGRAM_DECAY_RATE);
+  if (process.env.ENGRAM_DECAY_RATE)
+    config.decayRate = Number(process.env.ENGRAM_DECAY_RATE);
   if (process.env.ENGRAM_WM_CAPACITY)
     config.workingMemoryCapacity = Number(process.env.ENGRAM_WM_CAPACITY);
   if (process.env.ENGRAM_RETRIEVAL_THRESHOLD)