@cogmem/engram 0.0.0

package/drizzle/meta/0000_snapshot.json

@@ -0,0 +1,417 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "99e5e201-971a-435f-b2d5-74854a400ee4",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "tables": {
+    "access_log": {
+      "name": "access_log",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "memory_id": {
+          "name": "memory_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "accessed_at": {
+          "name": "accessed_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "access_type": {
+          "name": "access_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "idx_access_log_memory_id": {
+          "name": "idx_access_log_memory_id",
+          "columns": [
+            "memory_id"
+          ],
+          "isUnique": false
+        },
+        "idx_access_log_accessed_at": {
+          "name": "idx_access_log_accessed_at",
+          "columns": [
+            "accessed_at"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {
+        "access_log_memory_id_memories_id_fk": {
+          "name": "access_log_memory_id_memories_id_fk",
+          "tableFrom": "access_log",
+          "tableTo": "memories",
+          "columnsFrom": [
+            "memory_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "associations": {
+      "name": "associations",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "source_id": {
+          "name": "source_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "target_id": {
+          "name": "target_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "strength": {
+          "name": "strength",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0.5
+        },
+        "formed_at": {
+          "name": "formed_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "type": {
+          "name": "type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "idx_associations_source": {
+          "name": "idx_associations_source",
+          "columns": [
+            "source_id"
+          ],
+          "isUnique": false
+        },
+        "idx_associations_target": {
+          "name": "idx_associations_target",
+          "columns": [
+            "target_id"
+          ],
+          "isUnique": false
+        },
+        "unique_source_target": {
+          "name": "unique_source_target",
+          "columns": [
+            "source_id",
+            "target_id"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {
+        "associations_source_id_memories_id_fk": {
+          "name": "associations_source_id_memories_id_fk",
+          "tableFrom": "associations",
+          "tableTo": "memories",
+          "columnsFrom": [
+            "source_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "associations_target_id_memories_id_fk": {
+          "name": "associations_target_id_memories_id_fk",
+          "tableFrom": "associations",
+          "tableTo": "memories",
+          "columnsFrom": [
+            "target_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "consolidation_log": {
+      "name": "consolidation_log",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "ran_at": {
+          "name": "ran_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "memories_strengthened": {
+          "name": "memories_strengthened",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        },
+        "memories_pruned": {
+          "name": "memories_pruned",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        },
+        "facts_extracted": {
+          "name": "facts_extracted",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        },
+        "associations_discovered": {
+          "name": "associations_discovered",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "memories": {
+      "name": "memories",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "type": {
+          "name": "type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "content": {
+          "name": "content",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "encoded_at": {
+          "name": "encoded_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "last_recalled_at": {
+          "name": "last_recalled_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "recall_count": {
+          "name": "recall_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        },
+        "activation": {
+          "name": "activation",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        },
+        "emotion": {
+          "name": "emotion",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'neutral'"
+        },
+        "emotion_weight": {
+          "name": "emotion_weight",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        },
+        "context": {
+          "name": "context",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "chunk_id": {
+          "name": "chunk_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "reconsolidation_count": {
+          "name": "reconsolidation_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        }
+      },
+      "indexes": {
+        "idx_memories_type": {
+          "name": "idx_memories_type",
+          "columns": [
+            "type"
+          ],
+          "isUnique": false
+        },
+        "idx_memories_activation": {
+          "name": "idx_memories_activation",
+          "columns": [
+            "activation"
+          ],
+          "isUnique": false
+        },
+        "idx_memories_encoded_at": {
+          "name": "idx_memories_encoded_at",
+          "columns": [
+            "encoded_at"
+          ],
+          "isUnique": false
+        },
+        "idx_memories_context": {
+          "name": "idx_memories_context",
+          "columns": [
+            "context"
+          ],
+          "isUnique": false
+        },
+        "idx_memories_chunk_id": {
+          "name": "idx_memories_chunk_id",
+          "columns": [
+            "chunk_id"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "working_memory": {
+      "name": "working_memory",
+      "columns": {
+        "slot": {
+          "name": "slot",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "memory_ref": {
+          "name": "memory_ref",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "content": {
+          "name": "content",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "pushed_at": {
+          "name": "pushed_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}

package/drizzle/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1772220277792,
+      "tag": "0000_jittery_ender_wiggin",
+      "breakpoints": true
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@cogmem/engram",
+  "version": "0.0.0",
+  "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"
+    }
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "bin": {
+    "engram": "src/cli/index.ts",
+    "engram-mcp": "src/mcp/server.ts"
+  },
+  "files": [
+    "src/",
+    "drizzle/"
+  ],
+  "scripts": {
+    "start": "bun run src/cli/index.ts",
+    "test": "bun test",
+    "mcp": "bun run src/mcp/server.ts",
+    "lint": "oxlint src/",
+    "fmt": "oxfmt --write src/",
+    "typecheck": "bunx tsc --noEmit",
+    "db:generate": "bunx drizzle-kit generate",
+    "db:push": "bunx drizzle-kit push"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "citty": "^0.2.1",
+    "cli-table3": "^0.6.5",
+    "dayjs": "^1.11.19",
+    "drizzle-orm": "^0.45.1",
+    "kleur": "^4.1.5",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.4",
+    "@types/bun": "latest",
+    "drizzle-kit": "^0.31.9",
+    "oxfmt": "^0.35.0",
+    "oxlint": "^1.50.0"
+  },
+  "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

@@ -0,0 +1,71 @@
+import { defineCommand } from "citty";
+import { EngramEngine } from "../../core/engine.ts";
+import { encode } from "../../core/encoder.ts";
+import { isValidEmotion } from "../../core/emotional-tag.ts";
+import { isValidMemoryType, Emotion } from "../../core/memory.ts";
+import { formatMemoryEncoded } from "../format.ts";
+
+export const encodeCommand = defineCommand({
+  meta: {
+    name: "encode",
+    description: "Form a new memory",
+  },
+  args: {
+    content: {
+      type: "positional",
+      description: "The memory content to encode",
+      required: true,
+    },
+    type: {
+      type: "string",
+      description: "Memory type (episodic, semantic, procedural)",
+      default: "semantic",
+    },
+    emotion: {
+      type: "string",
+      description: `Emotional tag (${Object.values(Emotion).join(", ")})`,
+      default: "neutral",
+    },
+    context: {
+      type: "string",
+      description: "Context tag (e.g. project:acme)",
+    },
+    emotionWeight: {
+      type: "string",
+      description: "Emotion intensity 0-1 (overrides default)",
+      alias: "w",
+    },
+  },
+  run({ args }) {
+    const typeStr = args.type ?? "semantic";
+    if (!isValidMemoryType(typeStr)) {
+      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(", ")}`);
+      process.exit(1);
+    }
+
+    const engine = EngramEngine.create();
+    try {
+      const memory = encode(
+        engine.storage,
+        {
+          content: args.content,
+          type: typeStr,
+          emotion: emotionStr,
+          emotionWeight: args.emotionWeight ? Number(args.emotionWeight) : undefined,
+          context: args.context ?? engine.projectContext ?? undefined,
+        },
+        engine.config,
+      );
+
+      console.log(formatMemoryEncoded(memory));
+    } finally {
+      engine.close();
+    }
+  },
+});

package/src/cli/commands/focus.ts

@@ -0,0 +1,106 @@
+import { defineCommand } from "citty";
+import { EngramEngine } from "../../core/engine.ts";
+import {
+  pushFocus,
+  popFocus,
+  getFocus,
+  clearFocus,
+  focusUtilization,
+} from "../../core/working-memory.ts";
+import { bold, dim, cyan, isInteractive } from "../format.ts";
+
+export const focusCommand = defineCommand({
+  meta: {
+    name: "focus",
+    description: "Manage working memory (what you're actively thinking about)",
+  },
+  args: {
+    content: {
+      type: "positional",
+      description: "Content to push into working memory (omit to view current focus)",
+    },
+    clear: {
+      type: "boolean",
+      description: "Clear all working memory",
+      default: false,
+    },
+    pop: {
+      type: "boolean",
+      description: "Remove the most recent item from working memory",
+      default: false,
+    },
+  },
+  run({ args }) {
+    const engine = EngramEngine.create();
+    try {
+      if (args.clear) {
+        const count = clearFocus(engine.storage);
+        if (!isInteractive()) {
+          console.log(JSON.stringify({ cleared: count }));
+        } else {
+          console.log(dim(`  Cleared ${count} items from working memory.`));
+        }
+        return;
+      }
+
+      if (args.pop) {
+        const popped = popFocus(engine.storage);
+        if (!isInteractive()) {
+          console.log(
+            JSON.stringify(popped ? { slot: popped.slot, content: popped.content } : null),
+          );
+        } else if (popped) {
+          console.log(dim("  Removed: ") + bold(popped.content));
+        } else {
+          console.log(dim("  Working memory is empty."));
+        }
+        return;
+      }
+
+      if (args.content) {
+        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,
+            }),
+          );
+        } else {
+          console.log(cyan("  Focused on: ") + bold(slot.content) + dim(` [slot ${slot.slot}]`));
+          if (evicted) {
+            console.log(dim(`  Evicted: "${evicted.content}" (oldest item, capacity reached)`));
+          }
+        }
+        return;
+      }
+
+      const slots = getFocus(engine.storage);
+      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 })),
+          }),
+        );
+        return;
+      }
+
+      if (slots.length === 0) {
+        console.log(dim("  Working memory is empty."));
+        return;
+      }
+
+      console.log(bold(`  Working Memory`) + dim(` [${used}/${capacity}]`));
+      for (const slot of slots) {
+        console.log(`  ${cyan(">")} ${slot.content}` + dim(` [slot ${slot.slot}]`));
+      }
+    } finally {
+      engine.close();
+    }
+  },
+});