@cogmem/engram 0.2.1 → 0.3.1

package/README.md

@@ -19,6 +19,22 @@ 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         # skill → ~/.claude/skills/, MCP → ~/.claude.json
+engram install --provider claude --project        # skill → .claude/skills/, MCP → .mcp.json
+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.
@@ -27,12 +43,12 @@ engram is built on memory research. Every design decision traces back to how the
 
 The brain has distinct memory systems with different properties:
 
-| System | Brain Region | Duration | engram Mapping |
-|---|---|---|---|
-| **Working Memory** | Prefrontal Cortex | Seconds | `engram focus` — capacity-limited buffer (Miller's Law: 7 ± 2 items) |
-| **Episodic Memory** | Hippocampus → Neocortex | Minutes to lifetime | Contextual experiences — the *what, when, where, how it felt* |
-| **Semantic Memory** | Neocortex | Very long-term | Facts and concepts, detached from when you learned them |
-| **Procedural Memory** | Basal Ganglia | Lifetime | Skills and habits — immune to decay, expressed through action |
+| System                | Brain Region            | Duration            | engram Mapping                                                       |
+| --------------------- | ----------------------- | ------------------- | -------------------------------------------------------------------- |
+| **Working Memory**    | Prefrontal Cortex       | Seconds             | `engram focus` — capacity-limited buffer (Miller's Law: 7 ± 2 items) |
+| **Episodic Memory**   | Hippocampus → Neocortex | Minutes to lifetime | Contextual experiences — the _what, when, where, how it felt_        |
+| **Semantic Memory**   | Neocortex               | Very long-term      | Facts and concepts, detached from when you learned them              |
+| **Procedural Memory** | Basal Ganglia           | Lifetime            | Skills and habits — immune to decay, expressed through action        |
 
 ### ACT-R Activation Model
 
@@ -78,7 +94,7 @@ When one memory is activated, activation spreads along associative links to rela
 S_ji = S - ln(fan_j)
 ```
 
-Memories with many connections receive *less* boost from each (diffusion). Specific cues work better than generic ones.
+Memories with many connections receive _less_ boost from each (diffusion). Specific cues work better than generic ones.
 
 ### Consolidation (Sleep)
 
@@ -158,7 +174,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
 {
@@ -173,11 +189,11 @@ Add to your MCP client configuration (e.g., Claude Code `settings.json`):
 
 ### Available Tools
 
-| Tool | Description |
-|---|---|
-| `memory_store` | Encode new memories or reconsolidate existing ones |
+| Tool            | Description                                             |
+| --------------- | ------------------------------------------------------- |
+| `memory_store`  | Encode new memories or reconsolidate existing ones      |
 | `memory_recall` | Cue-based retrieval, memory inspection, or system stats |
-| `memory_manage` | Run consolidation or manage working memory |
+| `memory_manage` | Run consolidation or manage working memory              |
 
 ## Programmatic API
 
@@ -187,11 +203,15 @@ import { EngramEngine, encode, recall, consolidate } from "engram";
 const engine = EngramEngine.inMemory();
 
 // Encode
-const memory = encode(engine.storage, {
-  content: "important fact",
-  type: "semantic",
-  emotion: "curiosity",
-}, engine.config);
+const memory = encode(
+  engine.storage,
+  {
+    content: "important fact",
+    type: "semantic",
+    emotion: "curiosity",
+  },
+  engine.config,
+);
 
 // Recall
 const results = recall(engine.storage, "important", engine.config);
@@ -206,12 +226,12 @@ engine.close();
 
 Cognitive parameters can be tuned via environment variables or the `loadConfig()` function:
 
-| Parameter | Default | Env Variable | Description |
-|---|---|---|---|
-| `decayRate` | 0.5 | `ENGRAM_DECAY_RATE` | ACT-R power law decay parameter |
-| `retrievalThreshold` | -1.0 | `ENGRAM_RETRIEVAL_THRESHOLD` | Minimum activation for recall |
-| `workingMemoryCapacity` | 7 | `ENGRAM_WM_CAPACITY` | Miller's Law capacity limit |
-| `dbPath` | `~/.engram/memory.db` | `ENGRAM_DB_PATH` | SQLite database location |
+| Parameter               | Default               | Env Variable                 | Description                     |
+| ----------------------- | --------------------- | ---------------------------- | ------------------------------- |
+| `decayRate`             | 0.5                   | `ENGRAM_DECAY_RATE`          | ACT-R power law decay parameter |
+| `retrievalThreshold`    | -1.0                  | `ENGRAM_RETRIEVAL_THRESHOLD` | Minimum activation for recall   |
+| `workingMemoryCapacity` | 7                     | `ENGRAM_WM_CAPACITY`         | Miller's Law capacity limit     |
+| `dbPath`                | `~/.engram/memory.db` | `ENGRAM_DB_PATH`             | SQLite database location        |
 
 All parameters are also configurable programmatically:
 
@@ -227,8 +247,8 @@ const engine = new EngramEngine({
 
 ## References
 
-- Anderson, J.R. (1993). *Rules of the Mind*. ACT-R Cognitive Architecture.
-- Ebbinghaus, H. (1885). *Uber das Gedachtnis*. Memory and forgetting curves.
+- Anderson, J.R. (1993). _Rules of the Mind_. ACT-R Cognitive Architecture.
+- Ebbinghaus, H. (1885). _Uber das Gedachtnis_. Memory and forgetting curves.
 - Collins, A.M. & Loftus, E.F. (1975). A spreading-activation theory of semantic processing.
 - Nader, K., Schafe, G.E. & Le Doux, J.E. (2000). Fear memories require protein synthesis in the amygdala for reconsolidation after retrieval.
 - Miller, G.A. (1956). The magical number seven, plus or minus two.

package/SKILL.md

@@ -0,0 +1,120 @@
+---
+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/drizzle/meta/0000_snapshot.json

@@ -39,16 +39,12 @@
       "indexes": {
         "idx_access_log_memory_id": {
           "name": "idx_access_log_memory_id",
-          "columns": [
-            "memory_id"
-          ],
+          "columns": ["memory_id"],
           "isUnique": false
         },
         "idx_access_log_accessed_at": {
           "name": "idx_access_log_accessed_at",
-          "columns": [
-            "accessed_at"
-          ],
+          "columns": ["accessed_at"],
           "isUnique": false
         }
       },
@@ -57,12 +53,8 @@
           "name": "access_log_memory_id_memories_id_fk",
           "tableFrom": "access_log",
           "tableTo": "memories",
-          "columnsFrom": [
-            "memory_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
+          "columnsFrom": ["memory_id"],
+          "columnsTo": ["id"],
           "onDelete": "cascade",
           "onUpdate": "no action"
         }
@@ -121,24 +113,17 @@
       "indexes": {
         "idx_associations_source": {
           "name": "idx_associations_source",
-          "columns": [
-            "source_id"
-          ],
+          "columns": ["source_id"],
           "isUnique": false
         },
         "idx_associations_target": {
           "name": "idx_associations_target",
-          "columns": [
-            "target_id"
-          ],
+          "columns": ["target_id"],
           "isUnique": false
         },
         "unique_source_target": {
           "name": "unique_source_target",
-          "columns": [
-            "source_id",
-            "target_id"
-          ],
+          "columns": ["source_id", "target_id"],
           "isUnique": true
         }
       },
@@ -147,12 +132,8 @@
           "name": "associations_source_id_memories_id_fk",
           "tableFrom": "associations",
           "tableTo": "memories",
-          "columnsFrom": [
-            "source_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
+          "columnsFrom": ["source_id"],
+          "columnsTo": ["id"],
           "onDelete": "cascade",
           "onUpdate": "no action"
         },
@@ -160,12 +141,8 @@
           "name": "associations_target_id_memories_id_fk",
           "tableFrom": "associations",
           "tableTo": "memories",
-          "columnsFrom": [
-            "target_id"
-          ],
-          "columnsTo": [
-            "id"
-          ],
+          "columnsFrom": ["target_id"],
+          "columnsTo": ["id"],
           "onDelete": "cascade",
           "onUpdate": "no action"
         }
@@ -326,37 +303,27 @@
       "indexes": {
         "idx_memories_type": {
           "name": "idx_memories_type",
-          "columns": [
-            "type"
-          ],
+          "columns": ["type"],
           "isUnique": false
         },
         "idx_memories_activation": {
           "name": "idx_memories_activation",
-          "columns": [
-            "activation"
-          ],
+          "columns": ["activation"],
           "isUnique": false
         },
         "idx_memories_encoded_at": {
           "name": "idx_memories_encoded_at",
-          "columns": [
-            "encoded_at"
-          ],
+          "columns": ["encoded_at"],
           "isUnique": false
         },
         "idx_memories_context": {
           "name": "idx_memories_context",
-          "columns": [
-            "context"
-          ],
+          "columns": ["context"],
           "isUnique": false
         },
         "idx_memories_chunk_id": {
           "name": "idx_memories_chunk_id",
-          "columns": [
-            "chunk_id"
-          ],
+          "columns": ["chunk_id"],
           "isUnique": false
         }
       },
@@ -414,4 +381,4 @@
   "internal": {
     "indexes": {}
   }
-}
+}

package/drizzle/meta/_journal.json

@@ -10,4 +10,4 @@
       "breakpoints": true
     }
   ]
-}
+}

package/package.json

@@ -1,25 +1,43 @@
 {
   "name": "@cogmem/engram",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Human memory for artificial minds — a cognitive memory system modeled on neuroscience",
-  "type": "module",
-  "exports": {
-    ".": {
-      "bun": "./src/index.ts",
-      "types": "./src/index.ts",
-      "default": "./src/index.ts"
-    }
+  "keywords": [
+    "agents",
+    "ai",
+    "bun",
+    "cognitive",
+    "mcp",
+    "memory",
+    "neuroscience"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/faltawy/engram.git"
   },
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
   "bin": {
     "engram": "src/cli/index.ts",
     "engram-mcp": "src/mcp/server.ts"
   },
   "files": [
     "src/",
-    "drizzle/"
+    "drizzle/",
+    "SKILL.md"
   ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "bun": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "start": "bun run src/cli/index.ts",
     "test": "bun test",
@@ -34,6 +52,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",
@@ -49,23 +68,6 @@
   "peerDependencies": {
     "typescript": "^5"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/faltawy/engram.git"
-  },
-  "keywords": [
-    "memory",
-    "ai",
-    "agents",
-    "cognitive",
-    "mcp",
-    "bun",
-    "neuroscience"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "license": "MIT",
   "engines": {
     "bun": ">=1.0.0"
   }

package/src/cli/commands/encode.ts

@@ -1,7 +1,8 @@
 import { defineCommand } from "citty";
-import { EngramEngine } from "../../core/engine.ts";
-import { encode } from "../../core/encoder.ts";
+
 import { isValidEmotion } from "../../core/emotional-tag.ts";
+import { encode } from "../../core/encoder.ts";
+import { EngramEngine } from "../../core/engine.ts";
 import { isValidMemoryType, Emotion } from "../../core/memory.ts";
 import { formatMemoryEncoded } from "../format.ts";
 
@@ -39,13 +40,19 @@ export const encodeCommand = defineCommand({
   run({ args }) {
     const typeStr = args.type ?? "semantic";
     if (!isValidMemoryType(typeStr)) {
-      console.error(`Invalid type: ${typeStr}. Valid: episodic, semantic, procedural`);
+      console.error(
+        `Invalid type: ${typeStr}. Valid: episodic, semantic, procedural`
+      );
       process.exit(1);
     }
 
     const emotionStr = args.emotion ?? "neutral";
     if (!isValidEmotion(emotionStr)) {
-      console.error(`Invalid emotion: ${emotionStr}. Valid: ${Object.values(Emotion).join(", ")}`);
+      console.error(
+        `Invalid emotion: ${emotionStr}. Valid: ${Object.values(Emotion).join(
+          ", "
+        )}`
+      );
       process.exit(1);
     }
 
@@ -57,10 +64,12 @@ export const encodeCommand = defineCommand({
           content: args.content,
           type: typeStr,
           emotion: emotionStr,
-          emotionWeight: args.emotionWeight ? Number(args.emotionWeight) : undefined,
+          emotionWeight: args.emotionWeight
+            ? Number(args.emotionWeight)
+            : undefined,
           context: args.context ?? engine.projectContext ?? undefined,
         },
-        engine.config,
+        engine.config
       );
 
       console.log(formatMemoryEncoded(memory));

package/src/cli/commands/focus.ts

@@ -1,4 +1,5 @@
 import { defineCommand } from "citty";
+
 import { EngramEngine } from "../../core/engine.ts";
 import {
   pushFocus,
@@ -17,7 +18,8 @@ export const focusCommand = defineCommand({
   args: {
     content: {
       type: "positional",
-      description: "Content to push into working memory (omit to view current focus)",
+      description:
+        "Content to push into working memory (omit to view current focus)",
     },
     clear: {
       type: "boolean",
@@ -47,7 +49,9 @@ export const focusCommand = defineCommand({
         const popped = popFocus(engine.storage);
         if (!isInteractive()) {
           console.log(
-            JSON.stringify(popped ? { slot: popped.slot, content: popped.content } : null),
+            JSON.stringify(
+              popped ? { slot: popped.slot, content: popped.content } : null
+            )
           );
         } else if (popped) {
           console.log(dim("  Removed: ") + bold(popped.content));
@@ -58,34 +62,55 @@ export const focusCommand = defineCommand({
       }
 
       if (args.content) {
-        const { slot, evicted } = pushFocus(engine.storage, args.content, engine.config);
+        const { slot, evicted } = pushFocus(
+          engine.storage,
+          args.content,
+          engine.config
+        );
         if (!isInteractive()) {
           console.log(
             JSON.stringify({
               slot: slot.slot,
               content: slot.content,
-              evicted: evicted ? { slot: evicted.slot, content: evicted.content } : null,
-            }),
+              evicted: evicted
+                ? { slot: evicted.slot, content: evicted.content }
+                : null,
+            })
           );
         } else {
-          console.log(cyan("  Focused on: ") + bold(slot.content) + dim(` [slot ${slot.slot}]`));
+          console.log(
+            cyan("  Focused on: ") +
+              bold(slot.content) +
+              dim(` [slot ${slot.slot}]`)
+          );
           if (evicted) {
-            console.log(dim(`  Evicted: "${evicted.content}" (oldest item, capacity reached)`));
+            console.log(
+              dim(
+                `  Evicted: "${evicted.content}" (oldest item, capacity reached)`
+              )
+            );
           }
         }
         return;
       }
 
       const slots = getFocus(engine.storage);
-      const { used, capacity } = focusUtilization(engine.storage, engine.config);
+      const { used, capacity } = focusUtilization(
+        engine.storage,
+        engine.config
+      );
 
       if (!isInteractive()) {
         console.log(
           JSON.stringify({
             used,
             capacity,
-            slots: slots.map((s) => ({ slot: s.slot, content: s.content, memoryRef: s.memoryRef })),
-          }),
+            slots: slots.map((s) => ({
+              slot: s.slot,
+              content: s.content,
+              memoryRef: s.memoryRef,
+            })),
+          })
         );
         return;
       }
@@ -97,7 +122,9 @@ export const focusCommand = defineCommand({
 
       console.log(bold(`  Working Memory`) + dim(` [${used}/${capacity}]`));
       for (const slot of slots) {
-        console.log(`  ${cyan(">")} ${slot.content}` + dim(` [slot ${slot.slot}]`));
+        console.log(
+          `  ${cyan(">")} ${slot.content}` + dim(` [slot ${slot.slot}]`)
+        );
       }
     } finally {
       engine.close();