@cogmem/engram 0.2.0 → 0.3.0

package/README.md

@@ -19,6 +19,21 @@ bun install -g @cogmem/engram
 engram --help
 ```
 
+### Quick Setup for AI Editors
+
+The `install` command sets up the skill file and MCP server config for your editor:
+
+```bash
+engram install                                    # interactive — prompts for provider + scope
+engram install --provider claude --global         # no prompts, installs to ~/.claude/
+engram install --provider claude --project        # installs to ./.claude/ in current dir
+engram install --provider claude --global --dry-run  # preview without writing files
+```
+
+This installs two things:
+1. **SKILL.md** — a cognitive protocol that teaches agents how to use engram effectively
+2. **MCP config** — adds the engram server to your editor's MCP settings
+
 ## The Science
 
 engram is built on memory research. Every design decision traces back to how the brain operates.
@@ -158,7 +173,7 @@ engram exposes its cognitive model as an MCP (Model Context Protocol) server, so
 
 ### Setup
 
-Add to your MCP client configuration (e.g., Claude Code `settings.json`):
+The easiest way is `engram install` (see above). To configure manually, add to your MCP client configuration:
 
 ```json
 {

package/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: engram
+description: Cognitive memory for AI agents — use when encoding, recalling, or managing persistent memories across sessions
+---
+
+# Engram — Cognitive Memory Protocol
+
+You have a biologically-inspired memory system. Use it like a brain, not a database.
+
+## Session Lifecycle
+
+**Start:** Recall what you know about the current context.
+```
+memory_recall → { action: "recall", cue: "<project or topic>" }
+memory_manage → { action: "focus_get" }
+```
+
+**During:** Encode insights as they emerge. Don't batch everything at the end.
+```
+memory_store → { action: "encode", content: "...", type: "...", emotion: "..." }
+```
+
+**End:** Consolidate to strengthen and link memories.
+```
+memory_manage → { action: "consolidate" }
+```
+
+## Memory Types
+
+| Type | Use when | Examples |
+|------|----------|---------|
+| `episodic` | Something *happened* — events, interactions, debugging sessions | "User reported login failing on Safari", "Deployed v2.3 with new caching" |
+| `semantic` | A *fact* or *concept* — knowledge, definitions, relationships | "Auth uses JWT with 24h expiry", "The payments module depends on Stripe SDK" |
+| `procedural` | A *skill* or *process* — how to do things, patterns, workflows | "To deploy: run tests → build → push to staging → verify → promote" |
+
+**Default to `semantic`** when unsure. Procedural memories never decay — use them for durable skills.
+
+## Emotion Tags
+
+Tag memories with emotional context. This affects recall priority — emotional memories surface faster.
+
+| Emotion | When to use |
+|---------|-------------|
+| `joy` | Something worked well, positive outcome, breakthrough |
+| `satisfaction` | Task completed successfully, clean solution |
+| `curiosity` | Interesting finding, worth exploring further |
+| `surprise` | Unexpected behavior, counter-intuitive result |
+| `anxiety` | Risk identified, potential failure, fragile code |
+| `frustration` | Recurring problem, friction, workaround needed |
+| `neutral` | Routine fact, no emotional significance |
+
+Omit emotion for routine facts. Tag frustration on pain points — it helps surface them when they recur.
+
+## MCP Tools Reference
+
+### memory_store
+| Action | Required | Optional |
+|--------|----------|----------|
+| `encode` | `content` | `type`, `emotion`, `emotionWeight` (0-1), `context` |
+| `encode_batch` | `memories[]` (1-50) | each: `type`, `emotion`, `emotionWeight`, `context` |
+| `reconsolidate` | `id` | `newContext`, `currentEmotion`, `currentEmotionWeight` |
+
+### memory_recall
+| Action | Required | Optional |
+|--------|----------|----------|
+| `recall` | `cue` | `limit`, `type`, `context`, `associative` (bool), `format` |
+| `list` | — | `type`, `context`, `limit`, `offset`, `format` |
+| `inspect` | `id` | — |
+| `stats` | — | — |
+
+### memory_manage
+| Action | Required | Optional |
+|--------|----------|----------|
+| `consolidate` | — | — |
+| `focus_push` | `content` | `memoryRef` |
+| `focus_pop` | — | — |
+| `focus_get` | — | — |
+| `focus_clear` | — | — |
+| `recall_to_focus` | `cue` | `limit`, `type`, `context` |
+
+## Working Memory (Focus Buffer)
+
+7 slots. Use it to hold active context during complex tasks.
+
+- **Push** key facts you'll reference repeatedly during a task
+- **Recall to focus** loads top recall results into the buffer
+- **Pop/clear** when switching contexts
+- The buffer is LIFO — newest items pop first
+
+**Priming pattern:** At session start, recall + focus to seed your working context:
+```
+memory_manage → { action: "recall_to_focus", cue: "<current task>" }
+```
+
+## Key Behaviors
+
+- **Recall strengthens memories** — each recall boosts activation (use-it-or-lose-it)
+- **List does NOT strengthen** — use list for browsing without side effects
+- **Procedural memories never decay** — once encoded, they persist permanently
+- **Consolidation discovers associations** — run it to link related memories
+- **Emotional memories resist decay** — tagged memories survive longer
+- **Context scopes memories** — use `context: "project:name"` to partition
+
+## What to Encode
+
+**Encode:** decisions and their rationale, architectural insights, debugging breakthroughs, user preferences, recurring patterns, project-specific knowledge, lessons learned
+
+**Don't encode:** transient task state, information already in code/docs, obvious facts, raw data without interpretation
+
+## Context Convention
+
+Use hierarchical context tags: `project:engram`, `project:acme/auth`, `topic:deployment`.
+This lets you recall scoped to a project or topic without noise from other domains.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cogmem/engram",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Human memory for artificial minds — a cognitive memory system modeled on neuroscience",
   "type": "module",
   "exports": {
@@ -18,7 +18,8 @@
   },
   "files": [
     "src/",
-    "drizzle/"
+    "drizzle/",
+    "SKILL.md"
   ],
   "scripts": {
     "start": "bun run src/cli/index.ts",
@@ -34,6 +35,7 @@
     "@modelcontextprotocol/sdk": "^1.27.1",
     "citty": "^0.2.1",
     "cli-table3": "^0.6.5",
+    "consola": "^3.4.2",
     "dayjs": "^1.11.19",
     "drizzle-orm": "^0.45.1",
     "kleur": "^4.1.5",

package/src/cli/commands/install.ts

@@ -0,0 +1,113 @@
+import { defineCommand } from "citty";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { consola } from "consola";
+import { getProvider, availableProviders } from "../providers/index.ts";
+import { green, dim, yellow, bold } from "../format.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/index.ts

@@ -9,6 +9,7 @@ import { statsCommand } from "./commands/stats.ts";
 import { listCommand } from "./commands/list.ts";
 import { sleepCommand } from "./commands/sleep.ts";
 import { healthCommand } from "./commands/health.ts";
+import { installCommand } from "./commands/install.ts";
 
 const main = defineCommand({
   meta: {
@@ -25,6 +26,7 @@ const main = defineCommand({
     stats: statsCommand,
     sleep: sleepCommand,
     health: healthCommand,
+    install: installCommand,
   },
 });
 

package/src/cli/providers/claude.ts

@@ -0,0 +1,89 @@
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+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", "settings.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, ".claude", "settings.local.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,16 @@
+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/core/associations.ts

@@ -113,28 +113,30 @@ export function formSemanticAssociations(
   storage: EngramStorage,
   memory: Memory,
   now?: number,
+  preloadedMemories?: Memory[],
 ): Association[] {
   const currentTime = now ?? Date.now();
   const keywords = extractKeywords(memory.content);
   if (keywords.length === 0) return [];
 
-  const allMemories = storage.getAllMemories();
+  const candidates = preloadedMemories ?? storage.getAllMemories();
+  const existing = storage.getAssociations(memory.id);
+  const linkedSet = new Set(
+    existing.flatMap((a) => [
+      `${a.sourceId}:${a.targetId}`,
+      `${a.targetId}:${a.sourceId}`,
+    ]),
+  );
   const formed: Association[] = [];
 
-  for (const other of allMemories) {
+  for (const other of candidates) {
     if (other.id === memory.id) continue;
 
     const otherKeywords = extractKeywords(other.content);
     const overlap = keywords.filter((k) => otherKeywords.includes(k));
 
     if (overlap.length > 0) {
-      const existing = storage.getAssociations(memory.id);
-      const alreadyLinked = existing.some(
-        (a) =>
-          (a.sourceId === memory.id && a.targetId === other.id) ||
-          (a.sourceId === other.id && a.targetId === memory.id),
-      );
-      if (alreadyLinked) continue;
+      if (linkedSet.has(`${memory.id}:${other.id}`)) continue;
 
       const strength = overlap.length / Math.max(keywords.length, otherKeywords.length);
       const assoc = formAssociation(
@@ -146,6 +148,8 @@ export function formSemanticAssociations(
         currentTime,
       );
       formed.push(assoc);
+      linkedSet.add(`${memory.id}:${other.id}`);
+      linkedSet.add(`${other.id}:${memory.id}`);
     }
   }
 
@@ -156,26 +160,26 @@ export function formEmotionalAssociations(
   storage: EngramStorage,
   memory: Memory,
   now?: number,
+  preloadedMemories?: Memory[],
 ): Association[] {
   if (memory.emotion === "neutral" || memory.emotionWeight <= 0.3) return [];
 
   const currentTime = now ?? Date.now();
-  const allMemories = storage.getAllMemories();
+  const candidates = preloadedMemories ?? storage.getAllMemories();
+  const existing = storage.getAssociations(memory.id);
+  const emotionalLinks = new Set(
+    existing
+      .filter((a) => a.type === "emotional")
+      .flatMap((a) => [`${a.sourceId}:${a.targetId}`, `${a.targetId}:${a.sourceId}`]),
+  );
   const formed: Association[] = [];
   const memoryTier = AROUSAL_TIERS[memory.emotion];
 
-  for (const other of allMemories) {
+  for (const other of candidates) {
     if (other.id === memory.id) continue;
     if (other.emotion === "neutral" || other.emotionWeight <= 0.3) continue;
 
-    const existing = storage.getAssociations(memory.id);
-    const alreadyLinked = existing.some(
-      (a) =>
-        a.type === "emotional" &&
-        ((a.sourceId === memory.id && a.targetId === other.id) ||
-          (a.sourceId === other.id && a.targetId === memory.id)),
-    );
-    if (alreadyLinked) continue;
+    if (emotionalLinks.has(`${memory.id}:${other.id}`)) continue;
 
     let strength: number;
     if (memory.emotion === other.emotion) {
@@ -190,6 +194,8 @@ export function formEmotionalAssociations(
 
     const assoc = formAssociation(storage, memory.id, other.id, "emotional", strength, currentTime);
     formed.push(assoc);
+    emotionalLinks.add(`${memory.id}:${other.id}`);
+    emotionalLinks.add(`${other.id}:${memory.id}`);
   }
 
   return formed;

package/src/core/consolidation.ts

@@ -69,8 +69,8 @@ export function consolidate(
   const remainingMemories = storage.getAllMemories();
   for (const memory of remainingMemories) {
     const temporalAssocs = formTemporalAssociations(storage, memory, config, currentTime);
-    const semanticAssocs = formSemanticAssociations(storage, memory, currentTime);
-    const emotionalAssocs = formEmotionalAssociations(storage, memory, currentTime);
+    const semanticAssocs = formSemanticAssociations(storage, memory, currentTime, remainingMemories);
+    const emotionalAssocs = formEmotionalAssociations(storage, memory, currentTime, remainingMemories);
     const causalAssocs = formCausalAssociations(storage, memory, config, currentTime);
 
     for (const assoc of [...temporalAssocs, ...semanticAssocs, ...emotionalAssocs, ...causalAssocs]) {

package/src/core/recall.ts

@@ -35,17 +35,12 @@ export function recall(
     for (const m of contextMatches) seedIds.add(m.id);
   }
 
-  const allCandidates = options?.type
-    ? storage.getAllMemories(options.type)
-    : storage.getAllMemories();
-
-  let filtered = allCandidates;
-  if (options?.context) {
-    filtered = filtered.filter((m) => m.context?.startsWith(options.context!));
-  }
-
-  const sorted = filtered.sort((a, b) => b.activation - a.activation);
-  for (const m of sorted.slice(0, limit)) {
+  const topByActivation = storage.getTopMemoriesByActivation(
+    limit,
+    options?.type,
+    options?.context,
+  );
+  for (const m of topByActivation) {
     seedIds.add(m.id);
   }
 

package/src/storage/sqlite.ts

@@ -153,6 +153,20 @@ export class EngramStorage {
       .all();
   }
 
+  getTopMemoriesByActivation(limit: number, type?: MemoryType, contextPrefix?: string): Memory[] {
+    const conditions = [];
+    if (type) conditions.push(eq(memories.type, type));
+    if (contextPrefix) conditions.push(sql`${memories.context} LIKE ${contextPrefix + "%"}`);
+
+    return this.db
+      .select()
+      .from(memories)
+      .where(conditions.length ? and(...conditions) : undefined)
+      .orderBy(desc(memories.activation))
+      .limit(limit)
+      .all();
+  }
+
   getMemoriesBelowActivation(threshold: number): Memory[] {
     return this.db
       .select()