@cogmem/engram 0.0.0

package/src/mcp/tools.ts

@@ -0,0 +1,334 @@
+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 { encode } from "../core/encoder.ts";
+import { recall } from "../core/recall.ts";
+import {
+  pushFocus,
+  popFocus,
+  getFocus,
+  clearFocus,
+  focusUtilization,
+} from "../core/working-memory.ts";
+import { consolidate } from "../core/consolidation.ts";
+import { discoverChunks } from "../core/chunking.ts";
+import { refreshActivations } from "../core/forgetting.ts";
+import { reconsolidate, type ReconsolidationContext } from "../core/reconsolidation.ts";
+import { isValidEmotion } from "../core/emotional-tag.ts";
+
+export interface ToolResult {
+  [key: string]: unknown;
+  content: { type: "text"; text: string }[];
+  isError?: boolean;
+}
+
+function textResult(text: string): ToolResult {
+  return { content: [{ type: "text", text }] };
+}
+
+function errorResult(text: string): ToolResult {
+  return { content: [{ type: "text", text }], isError: true };
+}
+
+export function handleStore(
+  engine: EngramEngine,
+  args: { action: string; [key: string]: unknown },
+): ToolResult {
+  switch (args.action) {
+    case "encode":
+      return handleEncode(engine.storage, engine.config, args as any, engine.projectContext);
+    case "reconsolidate":
+      return handleReconsolidate(engine.storage, engine.config, args as any);
+    default:
+      return errorResult(`Unknown store action: ${args.action}`);
+  }
+}
+
+export function handleRecall(
+  engine: EngramEngine,
+  args: { action?: string; [key: string]: unknown },
+): ToolResult {
+  const action = args.action ?? "recall";
+  switch (action) {
+    case "recall":
+      return handleRecallQuery(engine.storage, engine.config, args as any, engine.projectContext);
+    case "inspect":
+      return handleInspect(engine.storage, args as any);
+    case "stats":
+      return handleStats(engine.storage, engine.config);
+    default:
+      return errorResult(`Unknown recall action: ${action}`);
+  }
+}
+
+export function handleManage(
+  engine: EngramEngine,
+  args: { action: string; [key: string]: unknown },
+): ToolResult {
+  switch (args.action) {
+    case "consolidate":
+      return handleConsolidate(engine.storage, engine.config);
+    case "focus_push":
+      return handleFocusPush(engine.storage, engine.config, args as any);
+    case "focus_pop":
+      return handleFocusPop(engine.storage);
+    case "focus_get":
+      return handleFocusGet(engine.storage, engine.config);
+    case "focus_clear":
+      return handleFocusClear(engine.storage);
+    default:
+      return errorResult(`Unknown manage action: ${args.action}`);
+  }
+}
+
+function handleEncode(
+  storage: EngramStorage,
+  config: CognitiveConfig,
+  args: {
+    content: string;
+    type?: string;
+    emotion?: string;
+    emotionWeight?: number;
+    context?: string;
+  },
+  defaultContext?: string | null,
+): ToolResult {
+  const typeStr = args.type ?? "semantic";
+  if (!isValidMemoryType(typeStr)) {
+    return errorResult(`Invalid type: ${typeStr}. Must be episodic, semantic, or procedural.`);
+  }
+
+  const emotionStr = args.emotion ?? "neutral";
+  if (!isValidEmotion(emotionStr)) {
+    return errorResult(`Invalid emotion: ${emotionStr}.`);
+  }
+
+  const memory = encode(
+    storage,
+    {
+      content: args.content,
+      type: typeStr,
+      emotion: emotionStr,
+      emotionWeight: args.emotionWeight,
+      context: args.context ?? defaultContext ?? undefined,
+    },
+    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,
+    }),
+  );
+}
+
+function handleRecallQuery(
+  storage: EngramStorage,
+  config: CognitiveConfig,
+  args: {
+    cue: string;
+    limit?: number;
+    type?: string;
+    context?: string;
+    associative?: boolean;
+    verbose?: boolean;
+  },
+  defaultContext?: string | null,
+): ToolResult {
+  const typeFilter = args.type && isValidMemoryType(args.type) ? args.type : undefined;
+
+  const results = recall(storage, args.cue, config, {
+    limit: args.limit ?? 5,
+    type: typeFilter,
+    context: args.context ?? defaultContext ?? undefined,
+    associative: args.associative ?? true,
+  });
+
+  if (results.length === 0) {
+    return textResult("No memories found above retrieval threshold.");
+  }
+
+  const formatted = args.verbose
+    ? results.map((r) => ({
+        id: r.memory.id,
+        content: r.memory.content,
+        type: r.memory.type,
+        activation: r.activation,
+        spreadingActivation: r.spreadingActivation,
+        latency: r.latency,
+        emotion: r.memory.emotion,
+        emotionWeight: r.memory.emotionWeight,
+        recallCount: r.memory.recallCount,
+        context: r.memory.context,
+      }))
+    : results.map((r) => ({
+        id: r.memory.id,
+        content: r.memory.content,
+        context: r.memory.context,
+        activation: r.activation,
+      }));
+
+  return textResult(JSON.stringify(formatted));
+}
+
+function handleFocusPush(
+  storage: EngramStorage,
+  config: CognitiveConfig,
+  args: { content: string; memoryRef?: string },
+): ToolResult {
+  const { slot, evicted } = pushFocus(storage, args.content, config, {
+    memoryRef: args.memoryRef,
+  });
+
+  return textResult(
+    JSON.stringify({
+      slot: slot.slot,
+      content: slot.content,
+      evicted: evicted ? { slot: evicted.slot, content: evicted.content } : null,
+    }),
+  );
+}
+
+function handleFocusPop(storage: EngramStorage): ToolResult {
+  const popped = popFocus(storage);
+  if (!popped) {
+    return textResult("Working memory is empty.");
+  }
+  return textResult(JSON.stringify({ slot: popped.slot, content: popped.content }));
+}
+
+function handleFocusGet(storage: EngramStorage, config: CognitiveConfig): ToolResult {
+  const slots = getFocus(storage);
+  const { used, capacity } = focusUtilization(storage, config);
+
+  return textResult(
+    JSON.stringify({
+      used,
+      capacity,
+      slots: slots.map((s) => ({ slot: s.slot, content: s.content, memoryRef: s.memoryRef })),
+    }),
+  );
+}
+
+function handleFocusClear(storage: EngramStorage): ToolResult {
+  const count = clearFocus(storage);
+  return textResult(`Cleared ${count} items from working memory.`);
+}
+
+function handleConsolidate(storage: EngramStorage, config: CognitiveConfig): ToolResult {
+  const result = consolidate(storage, config);
+  const chunks = discoverChunks(storage, config);
+
+  return textResult(
+    JSON.stringify({
+      memoriesStrengthened: result.memoriesStrengthened,
+      memoriesPruned: result.memoriesPruned,
+      factsExtracted: result.factsExtracted,
+      associationsDiscovered: result.associationsDiscovered,
+      chunksFormed: chunks.length,
+      extractedFacts: result.extractedFacts,
+      prunedIds: result.prunedIds,
+    }),
+  );
+}
+
+function handleStats(storage: EngramStorage, config: CognitiveConfig): ToolResult {
+  const { atRisk } = refreshActivations(storage, config);
+  const { used, capacity } = focusUtilization(storage, config);
+  const lastConsolidation = storage.getLastConsolidation();
+
+  return textResult(
+    JSON.stringify({
+      workingMemory: { used, capacity },
+      episodic: storage.getMemoryCount("episodic"),
+      semantic: storage.getMemoryCount("semantic"),
+      procedural: storage.getMemoryCount("procedural"),
+      associations: storage.getAssociationCount(),
+      atRisk,
+      lastConsolidation: lastConsolidation
+        ? {
+            ranAt: lastConsolidation.ranAt,
+            memoriesStrengthened: lastConsolidation.memoriesStrengthened,
+            memoriesPruned: lastConsolidation.memoriesPruned,
+          }
+        : null,
+    }),
+  );
+}
+
+function handleInspect(storage: EngramStorage, args: { id: string }): ToolResult {
+  const allMemories = storage.getAllMemories();
+  const match = allMemories.find((m) => m.id === args.id || m.id.startsWith(args.id));
+
+  if (!match) {
+    return errorResult(`No memory found matching "${args.id}".`);
+  }
+
+  const accessLog = storage.getAccessLog(match.id);
+  const associations = storage.getAssociations(match.id);
+
+  return textResult(
+    JSON.stringify({
+      id: match.id,
+      type: match.type,
+      content: match.content,
+      encodedAt: match.encodedAt,
+      lastRecalledAt: match.lastRecalledAt,
+      recallCount: match.recallCount,
+      activation: match.activation,
+      emotion: match.emotion,
+      emotionWeight: match.emotionWeight,
+      context: match.context,
+      chunkId: match.chunkId,
+      reconsolidationCount: match.reconsolidationCount,
+      accessCount: accessLog.length,
+      associationCount: associations.length,
+      associations: associations.map((a) => ({
+        id: a.id,
+        targetId: a.sourceId === match.id ? a.targetId : a.sourceId,
+        strength: a.strength,
+        type: a.type,
+      })),
+    }),
+  );
+}
+
+function handleReconsolidate(
+  storage: EngramStorage,
+  config: CognitiveConfig,
+  args: { id: string; newContext?: string; currentEmotion?: string; currentEmotionWeight?: number },
+): ToolResult {
+  const memory = storage.getMemory(args.id);
+  if (!memory) {
+    return errorResult(`No memory found with id "${args.id}".`);
+  }
+
+  const validEmotion =
+    args.currentEmotion && isValidEmotion(args.currentEmotion) ? args.currentEmotion : undefined;
+
+  const context: ReconsolidationContext = {
+    newContext: args.newContext,
+    currentEmotion: validEmotion,
+    currentEmotionWeight: args.currentEmotionWeight,
+  };
+
+  const updated = reconsolidate(storage, memory, context, config);
+
+  return textResult(
+    JSON.stringify({
+      id: updated.id,
+      content: updated.content,
+      emotion: updated.emotion,
+      emotionWeight: updated.emotionWeight,
+      context: updated.context,
+      reconsolidationCount: updated.reconsolidationCount,
+    }),
+  );
+}

package/src/storage/schema.ts

@@ -0,0 +1,97 @@
+import { sqliteTable, text, integer, real, index, unique } from "drizzle-orm/sqlite-core";
+import { MemoryType, Emotion, AssociationType, AccessType } from "../core/memory.ts";
+
+export const memories = sqliteTable(
+  "memories",
+  {
+    id: text("id").primaryKey(),
+    type: text("type", {
+      enum: Object.values(MemoryType) as [MemoryType, ...MemoryType[]],
+    }).notNull(),
+    content: text("content").notNull(),
+    encodedAt: integer("encoded_at").notNull(),
+    lastRecalledAt: integer("last_recalled_at"),
+    recallCount: integer("recall_count").notNull().default(0),
+    activation: real("activation").notNull().default(0.0),
+    emotion: text("emotion", {
+      enum: Object.values(Emotion) as [Emotion, ...Emotion[]],
+    })
+      .notNull()
+      .default("neutral"),
+    emotionWeight: real("emotion_weight").notNull().default(0.0),
+    context: text("context"),
+    chunkId: text("chunk_id"),
+    reconsolidationCount: integer("reconsolidation_count").notNull().default(0),
+  },
+  (table) => [
+    index("idx_memories_type").on(table.type),
+    index("idx_memories_activation").on(table.activation),
+    index("idx_memories_encoded_at").on(table.encodedAt),
+    index("idx_memories_context").on(table.context),
+    index("idx_memories_chunk_id").on(table.chunkId),
+  ],
+);
+
+export const accessLog = sqliteTable(
+  "access_log",
+  {
+    id: text("id").primaryKey(),
+    memoryId: text("memory_id")
+      .notNull()
+      .references(() => memories.id, { onDelete: "cascade" }),
+    accessedAt: integer("accessed_at").notNull(),
+    accessType: text("access_type", {
+      enum: Object.values(AccessType) as [AccessType, ...AccessType[]],
+    }).notNull(),
+  },
+  (table) => [
+    index("idx_access_log_memory_id").on(table.memoryId),
+    index("idx_access_log_accessed_at").on(table.accessedAt),
+  ],
+);
+
+export const associations = sqliteTable(
+  "associations",
+  {
+    id: text("id").primaryKey(),
+    sourceId: text("source_id")
+      .notNull()
+      .references(() => memories.id, { onDelete: "cascade" }),
+    targetId: text("target_id")
+      .notNull()
+      .references(() => memories.id, { onDelete: "cascade" }),
+    strength: real("strength").notNull().default(0.5),
+    formedAt: integer("formed_at").notNull(),
+    type: text("type", {
+      enum: Object.values(AssociationType) as [AssociationType, ...AssociationType[]],
+    }).notNull(),
+  },
+  (table) => [
+    unique("unique_source_target").on(table.sourceId, table.targetId),
+    index("idx_associations_source").on(table.sourceId),
+    index("idx_associations_target").on(table.targetId),
+  ],
+);
+
+export const workingMemory = sqliteTable("working_memory", {
+  slot: integer("slot").primaryKey(),
+  memoryRef: text("memory_ref"),
+  content: text("content").notNull(),
+  pushedAt: integer("pushed_at").notNull(),
+});
+
+export const consolidationLog = sqliteTable("consolidation_log", {
+  id: text("id").primaryKey(),
+  ranAt: integer("ran_at").notNull(),
+  memoriesStrengthened: integer("memories_strengthened").notNull().default(0),
+  memoriesPruned: integer("memories_pruned").notNull().default(0),
+  factsExtracted: integer("facts_extracted").notNull().default(0),
+  associationsDiscovered: integer("associations_discovered").notNull().default(0),
+});
+
+export type Memory = typeof memories.$inferSelect;
+export type NewMemoryRow = typeof memories.$inferInsert;
+export type AccessLogEntry = typeof accessLog.$inferSelect;
+export type Association = typeof associations.$inferSelect;
+export type WorkingMemorySlot = typeof workingMemory.$inferSelect;
+export type ConsolidationLog = typeof consolidationLog.$inferSelect;