@cogmem/engram 0.0.0 → 0.1.0

package/README.md

@@ -167,7 +167,7 @@ Add to your MCP client configuration (e.g., Claude Code `settings.json`):
   "mcpServers": {
     "engram": {
       "command": "bunx",
-      "args": ["@cogmem/engram-mcp"]
+      "args": ["-p", "@cogmem/engram", "engram-mcp"]
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cogmem/engram",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "Human memory for artificial minds — a cognitive memory system modeled on neuroscience",
   "type": "module",
   "exports": {

package/src/core/recall.ts

@@ -31,6 +31,13 @@ export function recall(
     candidateMap.set(m.id, m);
   }
 
+  if (options?.context) {
+    const contextMatches = storage.getMemoriesByContext(options.context, options?.type, limit * 2);
+    for (const m of contextMatches) {
+      candidateMap.set(m.id, m);
+    }
+  }
+
   const allCandidates = options?.type
     ? storage.getAllMemories(options.type)
     : storage.getAllMemories();

package/src/mcp/server.ts

@@ -17,11 +17,7 @@ server.registerTool(
   "memory_store",
   {
     title: "Store Memory",
-    description: `Store memories. Requires "action" field.
-
-Actions:
-- action:"encode" — Create a new memory. Params: content (required), type? (semantic|episodic|procedural, default semantic), emotion? (neutral|curiosity|surprise|anxiety|satisfaction|frustration|confusion|excitement|calm|urgency), emotionWeight? (0-1), context? (e.g. "project:acme")
-- action:"reconsolidate" — Update an existing memory during recall. Params: id (required), newContext?, currentEmotion?, currentEmotionWeight?`,
+    description: `Actions: encode(content) — store memory | encode_batch(memories[]) — store multiple | reconsolidate(id) — update during recall. Optional: type, emotion, emotionWeight, context.`,
     inputSchema: z.discriminatedUnion("action", [
       z.object({
         action: z.literal("encode"),
@@ -31,6 +27,22 @@ Actions:
         emotionWeight: z.number().min(0).max(1).optional().describe("Emotion intensity 0-1"),
         context: z.string().optional().describe("Context tag (e.g. project:acme)"),
       }),
+      z.object({
+        action: z.literal("encode_batch"),
+        memories: z
+          .array(
+            z.object({
+              content: z.string(),
+              type: z.nativeEnum(MemoryType).optional(),
+              emotion: z.nativeEnum(Emotion).optional(),
+              emotionWeight: z.number().min(0).max(1).optional(),
+              context: z.string().optional(),
+            }),
+          )
+          .min(1)
+          .max(50)
+          .describe("Array of memories to encode"),
+      }),
       z.object({
         action: z.literal("reconsolidate"),
         id: z.string().describe("Memory ID to update"),
@@ -47,12 +59,7 @@ server.registerTool(
   "memory_recall",
   {
     title: "Recall Memories",
-    description: `Retrieve memories. Requires "action" field.
-
-Actions:
-- action:"recall" — Cue-based retrieval with spreading activation. Params: cue (required), limit? (default 5), type? (semantic|episodic|procedural), context?, associative? (default true), verbose?
-- action:"inspect" — Examine a specific memory's full lifecycle. Params: id (required, full ID or prefix)
-- action:"stats" — Memory system overview (counts, working memory usage, last consolidation). No extra params.`,
+    description: `Actions: recall(cue) — cue-based retrieval | list — browse without activation effects | inspect(id) — full lifecycle | stats — system overview. Optional: limit, type, context, format, verbose.`,
     inputSchema: z.discriminatedUnion("action", [
       z.object({
         action: z.literal("recall").optional().default("recall"),
@@ -62,11 +69,20 @@ Actions:
         context: z.string().optional().describe("Filter by context"),
         associative: z.boolean().optional().describe("Spreading activation (default: true)"),
         verbose: z.boolean().optional().describe("Full fields"),
+        format: z.enum(["full", "content", "ids"]).optional().describe("Response format (default: full)"),
       }),
       z.object({
         action: z.literal("inspect"),
         id: z.string().describe("Memory ID or prefix"),
       }),
+      z.object({
+        action: z.literal("list"),
+        type: z.nativeEnum(MemoryType).optional().describe("Filter by type"),
+        context: z.string().optional().describe("Filter by context prefix"),
+        limit: z.number().optional().describe("Max results (default: 20)"),
+        offset: z.number().optional().describe("Skip first N results (default: 0)"),
+        format: z.enum(["full", "content", "ids"]).optional().describe("Response format (default: full)"),
+      }),
       z.object({
         action: z.literal("stats"),
       }),
@@ -79,14 +95,7 @@ server.registerTool(
   "memory_manage",
   {
     title: "Manage Memory",
-    description: `Memory maintenance. Requires "action" field.
-
-Actions:
-- action:"consolidate" — Run sleep cycle (strengthen, prune, extract patterns, discover links). No extra params.
-- action:"focus_push" — Push to working memory buffer. Params: content (required), memoryRef?
-- action:"focus_pop" — Remove most recent item from working memory. No extra params.
-- action:"focus_get" — View current working memory contents. No extra params.
-- action:"focus_clear" — Clear all working memory. No extra params.`,
+    description: `Actions: consolidate — run sleep cycle | recall_to_focus(cue) — recall and load to working memory | focus_push(content) — push to buffer | focus_pop — pop newest | focus_get — view buffer | focus_clear — empty buffer.`,
     inputSchema: z.discriminatedUnion("action", [
       z.object({
         action: z.literal("consolidate"),
@@ -105,6 +114,13 @@ Actions:
       z.object({
         action: z.literal("focus_clear"),
       }),
+      z.object({
+        action: z.literal("recall_to_focus"),
+        cue: z.string().describe("Recall cue"),
+        limit: z.number().optional().describe("Max memories to load (default: 3)"),
+        type: z.nativeEnum(MemoryType).optional().describe("Filter by type"),
+        context: z.string().optional().describe("Filter by context"),
+      }),
     ]),
   },
   async (args) => handleManage(engine, args),

package/src/mcp/tools.ts

@@ -1,7 +1,7 @@
 import type { CognitiveConfig } from "../config/defaults.ts";
 import type { EngramStorage } from "../storage/sqlite.ts";
 import type { EngramEngine } from "../core/engine.ts";
-import { isValidMemoryType } from "../core/memory.ts";
+import { isValidMemoryType, MemoryType, Emotion } from "../core/memory.ts";
 import { encode } from "../core/encoder.ts";
 import { recall } from "../core/recall.ts";
 import {
@@ -38,6 +38,8 @@ export function handleStore(
   switch (args.action) {
     case "encode":
       return handleEncode(engine.storage, engine.config, args as any, engine.projectContext);
+    case "encode_batch":
+      return handleEncodeBatch(engine.storage, engine.config, args as any, engine.projectContext);
     case "reconsolidate":
       return handleReconsolidate(engine.storage, engine.config, args as any);
     default:
@@ -55,6 +57,8 @@ export function handleRecall(
       return handleRecallQuery(engine.storage, engine.config, args as any, engine.projectContext);
     case "inspect":
       return handleInspect(engine.storage, args as any);
+    case "list":
+      return handleList(engine.storage, args as any, engine.projectContext);
     case "stats":
       return handleStats(engine.storage, engine.config);
     default:
@@ -77,6 +81,8 @@ export function handleManage(
       return handleFocusGet(engine.storage, engine.config);
     case "focus_clear":
       return handleFocusClear(engine.storage);
+    case "recall_to_focus":
+      return handleRecallToFocus(engine.storage, engine.config, args as any, engine.projectContext);
     default:
       return errorResult(`Unknown manage action: ${args.action}`);
   }
@@ -96,12 +102,12 @@ function handleEncode(
 ): ToolResult {
   const typeStr = args.type ?? "semantic";
   if (!isValidMemoryType(typeStr)) {
-    return errorResult(`Invalid type: ${typeStr}. Must be episodic, semantic, or procedural.`);
+    return errorResult(`Invalid type '${typeStr}'. Valid: ${Object.values(MemoryType).join(", ")}`);
   }
 
   const emotionStr = args.emotion ?? "neutral";
   if (!isValidEmotion(emotionStr)) {
-    return errorResult(`Invalid emotion: ${emotionStr}.`);
+    return errorResult(`Invalid emotion '${emotionStr}'. Valid: ${Object.values(Emotion).join(", ")}`);
   }
 
   const memory = encode(
@@ -116,17 +122,58 @@ function handleEncode(
     config,
   );
 
-  return textResult(
-    JSON.stringify({
-      id: memory.id,
-      type: memory.type,
-      content: memory.content,
-      activation: memory.activation,
-      emotion: memory.emotion,
-      emotionWeight: memory.emotionWeight,
-      context: memory.context,
-    }),
-  );
+  return textResult(JSON.stringify({ id: memory.id }));
+}
+
+function handleEncodeBatch(
+  storage: EngramStorage,
+  config: CognitiveConfig,
+  args: {
+    memories: Array<{
+      content: string;
+      type?: string;
+      emotion?: string;
+      emotionWeight?: number;
+      context?: string;
+    }>;
+  },
+  defaultContext?: string | null,
+): ToolResult {
+  const ids: string[] = [];
+  const errors: string[] = [];
+
+  storage.transaction(() => {
+    for (let i = 0; i < args.memories.length; i++) {
+      const m = args.memories[i]!;
+      const typeStr = m.type ?? "semantic";
+      if (!isValidMemoryType(typeStr)) {
+        errors.push(`[${i}] Invalid type '${typeStr}'`);
+        continue;
+      }
+      const emotionStr = m.emotion ?? "neutral";
+      if (!isValidEmotion(emotionStr)) {
+        errors.push(`[${i}] Invalid emotion '${emotionStr}'`);
+        continue;
+      }
+      const memory = encode(
+        storage,
+        {
+          content: m.content,
+          type: typeStr,
+          emotion: emotionStr,
+          emotionWeight: m.emotionWeight,
+          context: m.context ?? defaultContext ?? undefined,
+        },
+        config,
+      );
+      ids.push(memory.id);
+    }
+  });
+
+  if (errors.length > 0) {
+    return textResult(JSON.stringify({ stored: ids, errors }));
+  }
+  return textResult(JSON.stringify({ stored: ids }));
 }
 
 function handleRecallQuery(
@@ -139,6 +186,7 @@ function handleRecallQuery(
     context?: string;
     associative?: boolean;
     verbose?: boolean;
+    format?: "full" | "content" | "ids";
   },
   defaultContext?: string | null,
 ): ToolResult {
@@ -155,6 +203,15 @@ function handleRecallQuery(
     return textResult("No memories found above retrieval threshold.");
   }
 
+  const format = args.format ?? "full";
+
+  if (format === "ids") {
+    return textResult(JSON.stringify(results.map((r) => r.memory.id)));
+  }
+  if (format === "content") {
+    return textResult(JSON.stringify(results.map((r) => r.memory.content)));
+  }
+
   const formatted = args.verbose
     ? results.map((r) => ({
         id: r.memory.id,
@@ -178,6 +235,56 @@ function handleRecallQuery(
   return textResult(JSON.stringify(formatted));
 }
 
+function handleList(
+  storage: EngramStorage,
+  args: {
+    type?: string;
+    context?: string;
+    limit?: number;
+    offset?: number;
+    format?: "full" | "content" | "ids";
+  },
+  defaultContext?: string | null,
+): ToolResult {
+  const limit = args.limit ?? 20;
+  const offset = args.offset ?? 0;
+  const typeFilter = args.type && isValidMemoryType(args.type) ? args.type : undefined;
+  const context = args.context ?? defaultContext ?? undefined;
+
+  let results;
+  if (context) {
+    results = storage.getMemoriesByContext(context, typeFilter, limit + offset);
+  } else {
+    results = storage.getAllMemories(typeFilter).slice(0, limit + offset);
+  }
+  results = results.slice(offset, offset + limit);
+
+  if (results.length === 0) {
+    return textResult("No memories found.");
+  }
+
+  const format = args.format ?? "full";
+
+  if (format === "ids") {
+    return textResult(JSON.stringify(results.map((m) => m.id)));
+  }
+  if (format === "content") {
+    return textResult(JSON.stringify(results.map((m) => m.content)));
+  }
+
+  return textResult(
+    JSON.stringify(
+      results.map((m) => ({
+        id: m.id,
+        content: m.content,
+        type: m.type,
+        context: m.context,
+        activation: m.activation,
+      })),
+    ),
+  );
+}
+
 function handleFocusPush(
   storage: EngramStorage,
   config: CognitiveConfig,
@@ -222,6 +329,34 @@ function handleFocusClear(storage: EngramStorage): ToolResult {
   return textResult(`Cleared ${count} items from working memory.`);
 }
 
+function handleRecallToFocus(
+  storage: EngramStorage,
+  config: CognitiveConfig,
+  args: { cue: string; limit?: number; type?: string; context?: string },
+  defaultContext?: string | null,
+): ToolResult {
+  const typeFilter = args.type && isValidMemoryType(args.type) ? args.type : undefined;
+  const limit = args.limit ?? 3;
+
+  const results = recall(storage, args.cue, config, {
+    limit,
+    type: typeFilter,
+    context: args.context ?? defaultContext ?? undefined,
+    associative: true,
+  });
+
+  const loaded: string[] = [];
+  for (const r of results) {
+    pushFocus(storage, r.memory.content, config, {
+      memoryRef: r.memory.id,
+    });
+    loaded.push(r.memory.id);
+  }
+
+  const { used, capacity } = focusUtilization(storage, config);
+  return textResult(JSON.stringify({ loaded, focus: { used, capacity } }));
+}
+
 function handleConsolidate(storage: EngramStorage, config: CognitiveConfig): ToolResult {
   const result = consolidate(storage, config);
   const chunks = discoverChunks(storage, config);
@@ -324,9 +459,6 @@ function handleReconsolidate(
   return textResult(
     JSON.stringify({
       id: updated.id,
-      content: updated.content,
-      emotion: updated.emotion,
-      emotionWeight: updated.emotionWeight,
       context: updated.context,
       reconsolidationCount: updated.reconsolidationCount,
     }),