@cogmem/engram 0.0.0

package/src/core/forgetting.ts

@@ -0,0 +1,58 @@
+import type { CognitiveConfig } from "../config/defaults.ts";
+import type { EngramStorage } from "../storage/sqlite.ts";
+import { baseLevelActivation } from "./activation.ts";
+
+// R(t) = e^{-t/S}
+export function ebbinghausRetention(timeSinceLastRecall: number, strength: number): number {
+  if (strength <= 0) return 0;
+  return Math.exp(-timeSinceLastRecall / strength);
+}
+
+export function memoryStrength(
+  recallCount: number,
+  emotionWeight: number,
+  associationCount: number,
+  emotionalBoostFactor: number,
+): number {
+  const recallStrength = 1 + recallCount * 0.8;
+  const emotionalStrength = 1 + emotionWeight * emotionalBoostFactor;
+  const associativeStrength = 1 + Math.log(1 + associationCount) * 0.5;
+  return recallStrength * emotionalStrength * associativeStrength;
+}
+
+export function refreshActivations(
+  storage: EngramStorage,
+  config: CognitiveConfig,
+  now?: number,
+): { updated: number; atRisk: number } {
+  const currentTime = now ?? Date.now();
+  const memories = storage.getAllMemories();
+  let updated = 0;
+  let atRisk = 0;
+
+  for (const memory of memories) {
+    if (memory.type === "procedural") continue;
+
+    const timestamps = storage.getAccessTimestamps(memory.id);
+    const newActivation = baseLevelActivation(timestamps, currentTime, config.decayRate);
+
+    const emotionBoost =
+      memory.emotionWeight > 0
+        ? Math.log(1 + memory.emotionWeight * config.emotionalBoostFactor)
+        : 0;
+
+    const finalActivation = newActivation + emotionBoost;
+
+    if (Math.abs(finalActivation - memory.activation) > 0.001) {
+      memory.activation = finalActivation;
+      storage.updateMemory(memory);
+      updated++;
+    }
+
+    if (finalActivation < config.retrievalThreshold) {
+      atRisk++;
+    }
+  }
+
+  return { updated, atRisk };
+}

package/src/core/memory.ts

@@ -0,0 +1,94 @@
+import type { Memory as _Memory } from "../storage/schema.ts";
+export {
+  type Memory,
+  type AccessLogEntry,
+  type Association,
+  type WorkingMemorySlot,
+  type ConsolidationLog,
+} from "../storage/schema.ts";
+
+export const MemoryType = {
+  Episodic: "episodic",
+  Semantic: "semantic",
+  Procedural: "procedural",
+} as const;
+export type MemoryType = (typeof MemoryType)[keyof typeof MemoryType];
+
+export const Emotion = {
+  Joy: "joy",
+  Anxiety: "anxiety",
+  Frustration: "frustration",
+  Surprise: "surprise",
+  Satisfaction: "satisfaction",
+  Curiosity: "curiosity",
+  Neutral: "neutral",
+} as const;
+export type Emotion = (typeof Emotion)[keyof typeof Emotion];
+
+export const AssociationType = {
+  Temporal: "temporal",
+  Semantic: "semantic",
+  CoRecall: "co-recall",
+} as const;
+export type AssociationType = (typeof AssociationType)[keyof typeof AssociationType];
+
+export const AccessType = {
+  Encode: "encode",
+  Recall: "recall",
+  Consolidate: "consolidate",
+} as const;
+export type AccessType = (typeof AccessType)[keyof typeof AccessType];
+
+export interface EncodeInput {
+  content: string;
+  type: MemoryType;
+  emotion?: Emotion;
+  emotionWeight?: number;
+  context?: string;
+}
+
+export interface RecallResult {
+  memory: _Memory;
+  activation: number;
+  spreadingActivation: number;
+  latency: number;
+}
+
+export function isValidMemoryType(s: string): s is MemoryType {
+  return (Object.values(MemoryType) as string[]).includes(s);
+}
+
+const TYPE_PREFIX: Record<MemoryType, string> = {
+  episodic: "epi",
+  semantic: "sem",
+  procedural: "proc",
+};
+
+function contentSlug(content: string, maxLen = 30): string {
+  return content
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, maxLen)
+    .replace(/-$/, "");
+}
+
+function shortHash(input: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    h = (h * 0x01000193) >>> 0;
+  }
+  return h.toString(16).padStart(6, "0").slice(0, 6);
+}
+
+export function generateMemoryId(content: string, type: MemoryType): string {
+  const prefix = TYPE_PREFIX[type];
+  const slug = contentSlug(content);
+  const hash = shortHash(content + Date.now());
+  return `${prefix}:${slug}:${hash}`;
+}
+
+export function generateId(): string {
+  return crypto.randomUUID();
+}

package/src/core/procedural-store.ts

@@ -0,0 +1,36 @@
+import type { CognitiveConfig } from "../config/defaults.ts";
+import type { EngramStorage } from "../storage/sqlite.ts";
+import type { Memory } from "./memory.ts";
+import { encode } from "./encoder.ts";
+
+export function encodeProcedural(
+  storage: EngramStorage,
+  content: string,
+  config: CognitiveConfig,
+  options?: { context?: string; now?: number },
+): Memory {
+  return encode(
+    storage,
+    {
+      content,
+      type: "procedural",
+      context: options?.context,
+    },
+    config,
+    options?.now,
+  );
+}
+
+export function getSkills(storage: EngramStorage): Memory[] {
+  return storage.getAllMemories("procedural");
+}
+
+export function promoteToSkill(storage: EngramStorage, memoryId: string): Memory | null {
+  const memory = storage.getMemory(memoryId);
+  if (!memory) return null;
+
+  memory.type = "procedural";
+  storage.updateMemory(memory);
+
+  return memory;
+}

package/src/core/recall.ts

@@ -0,0 +1,102 @@
+import type { CognitiveConfig } from "../config/defaults.ts";
+import type { EngramStorage } from "../storage/sqlite.ts";
+import type { Memory, RecallResult } from "./memory.ts";
+import { computeActivation, spreadingActivationStrength } from "./activation.ts";
+
+export function recall(
+  storage: EngramStorage,
+  cue: string,
+  config: CognitiveConfig,
+  options?: {
+    limit?: number;
+    associative?: boolean;
+    type?: Memory["type"];
+    context?: string;
+    now?: number;
+    deterministic?: boolean;
+  },
+): RecallResult[] {
+  const now = options?.now ?? Date.now();
+  const limit = options?.limit ?? 10;
+  const associative = options?.associative ?? true;
+
+  const candidateMap = new Map<string, Memory>();
+
+  const ftsIds = storage.searchFTS(cue, limit * 2);
+  for (const id of ftsIds) {
+    const m = storage.getMemory(id);
+    if (!m) continue;
+    if (options?.type && m.type !== options.type) continue;
+    if (options?.context && (!m.context || !m.context.startsWith(options.context))) continue;
+    candidateMap.set(m.id, m);
+  }
+
+  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)) {
+    candidateMap.set(m.id, m);
+  }
+
+  if (candidateMap.size === 0) return [];
+
+  const results: RecallResult[] = [];
+
+  for (const memory of candidateMap.values()) {
+    const timestamps = storage.getAccessTimestamps(memory.id);
+
+    let spreadingSum = 0;
+    if (associative) {
+      const assocFrom = storage.getAssociationsFrom(memory.id);
+      const assocTo = storage.getAssociationsTo(memory.id);
+      const allAssocs = [...assocFrom, ...assocTo];
+
+      for (const assoc of allAssocs) {
+        const otherId = assoc.sourceId === memory.id ? assoc.targetId : assoc.sourceId;
+        const fanCount = storage.getFanCount(otherId);
+        const strength = spreadingActivationStrength(config.maxSpreadingActivation, fanCount);
+        spreadingSum += assoc.strength * strength;
+      }
+    }
+
+    const { activation, latency } = computeActivation(timestamps, now, config, {
+      spreadingSum,
+      noiseOverride: options?.deterministic ? 0 : undefined,
+      emotionWeight: memory.emotionWeight,
+    });
+
+    if (activation <= config.retrievalThreshold) continue;
+
+    results.push({
+      memory,
+      activation,
+      spreadingActivation: spreadingSum,
+      latency,
+    });
+  }
+
+  results.sort((a, b) => b.activation - a.activation);
+
+  for (const result of results.slice(0, limit)) {
+    storage.logAccess(result.memory.id, "recall", now);
+    result.memory.recallCount++;
+    result.memory.lastRecalledAt = now;
+    const newTimestamps = storage.getAccessTimestamps(result.memory.id);
+    const recomputed = computeActivation(newTimestamps, now, config, {
+      spreadingSum: result.spreadingActivation,
+      noiseOverride: 0,
+      emotionWeight: result.memory.emotionWeight,
+    });
+    result.memory.activation = recomputed.activation;
+    storage.updateMemory(result.memory);
+  }
+
+  return results.slice(0, limit);
+}

package/src/core/reconsolidation.ts

@@ -0,0 +1,42 @@
+import type { CognitiveConfig } from "../config/defaults.ts";
+import type { EngramStorage } from "../storage/sqlite.ts";
+import type { Memory } from "./memory.ts";
+
+export interface ReconsolidationContext {
+  newContext?: string;
+  currentEmotion?: Memory["emotion"];
+  currentEmotionWeight?: number;
+}
+
+export function reconsolidate(
+  storage: EngramStorage,
+  memory: Memory,
+  recallContext: ReconsolidationContext,
+  config: CognitiveConfig,
+): Memory {
+  const blendRate = config.reconsolidationBlendRate;
+
+  if (recallContext.newContext && memory.context) {
+    if (!memory.context.includes(recallContext.newContext)) {
+      memory.context = `${memory.context}, ${recallContext.newContext}`;
+    }
+  } else if (recallContext.newContext && !memory.context) {
+    memory.context = recallContext.newContext;
+  }
+
+  if (recallContext.currentEmotion && recallContext.currentEmotion !== memory.emotion) {
+    const blendedWeight =
+      memory.emotionWeight * (1 - blendRate) +
+      (recallContext.currentEmotionWeight ?? 0.5) * blendRate;
+
+    if (blendRate > 0.3 || memory.emotionWeight < 0.2) {
+      memory.emotion = recallContext.currentEmotion;
+    }
+    memory.emotionWeight = blendedWeight;
+  }
+
+  memory.reconsolidationCount++;
+  storage.updateMemory(memory);
+
+  return memory;
+}

package/src/core/search.ts

@@ -0,0 +1,24 @@
+export function tokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((t) => t.length > 1);
+}
+
+function termFrequency(tokens: string[]): Map<string, number> {
+  const tf = new Map<string, number>();
+  for (const token of tokens) {
+    tf.set(token, (tf.get(token) ?? 0) + 1);
+  }
+  return tf;
+}
+
+export function extractKeywords(text: string, maxKeywords = 5): string[] {
+  const tokens = tokenize(text);
+  const tf = termFrequency(tokens);
+
+  return [...tf.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, maxKeywords)
+    .map(([term]) => term);
+}

package/src/core/working-memory.ts

@@ -0,0 +1,67 @@
+import type { CognitiveConfig } from "../config/defaults.ts";
+import type { EngramStorage } from "../storage/sqlite.ts";
+import type { WorkingMemorySlot } from "./memory.ts";
+
+export function pushFocus(
+  storage: EngramStorage,
+  content: string,
+  config: CognitiveConfig,
+  options?: { memoryRef?: string; now?: number },
+): { slot: WorkingMemorySlot; evicted: WorkingMemorySlot | null } {
+  const now = options?.now ?? Date.now();
+  const currentSlots = storage.getWorkingMemory();
+
+  let evicted: WorkingMemorySlot | null = null;
+
+  if (currentSlots.length >= config.workingMemoryCapacity) {
+    const oldest = currentSlots.reduce((min, s) => (s.pushedAt < min.pushedAt ? s : min));
+    evicted = oldest;
+    storage.removeWorkingMemorySlot(oldest.slot);
+  }
+
+  const usedSlots = new Set(storage.getWorkingMemory().map((s) => s.slot));
+  let nextSlot = 0;
+  while (usedSlots.has(nextSlot)) nextSlot++;
+
+  const slot: WorkingMemorySlot = {
+    slot: nextSlot,
+    memoryRef: options?.memoryRef ?? null,
+    content,
+    pushedAt: now,
+  };
+
+  storage.pushWorkingMemory(slot);
+  return { slot, evicted };
+}
+
+export function popFocus(storage: EngramStorage): WorkingMemorySlot | null {
+  const slots = storage.getWorkingMemory();
+  if (slots.length === 0) return null;
+
+  const newest = slots.reduce((max, s) => (s.pushedAt > max.pushedAt ? s : max));
+
+  storage.removeWorkingMemorySlot(newest.slot);
+  return newest;
+}
+
+export function getFocus(storage: EngramStorage): WorkingMemorySlot[] {
+  return storage.getWorkingMemory();
+}
+
+export function clearFocus(storage: EngramStorage): number {
+  const count = storage.getWorkingMemoryCount();
+  storage.clearWorkingMemory();
+  return count;
+}
+
+export function focusUtilization(
+  storage: EngramStorage,
+  config: CognitiveConfig,
+): { used: number; capacity: number; utilization: number } {
+  const used = storage.getWorkingMemoryCount();
+  return {
+    used,
+    capacity: config.workingMemoryCapacity,
+    utilization: used / config.workingMemoryCapacity,
+  };
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+export { EngramEngine } from "./core/engine.ts";
+export { EngramStorage } from "./storage/sqlite.ts";
+export { encode } from "./core/encoder.ts";
+export { recall } from "./core/recall.ts";
+export { consolidate, type ConsolidationResult } from "./core/consolidation.ts";
+export { reconsolidate, type ReconsolidationContext } from "./core/reconsolidation.ts";
+export {
+  pushFocus,
+  popFocus,
+  getFocus,
+  clearFocus,
+  focusUtilization,
+} from "./core/working-memory.ts";
+export {
+  formAssociation,
+  formTemporalAssociations,
+  formSemanticAssociations,
+  recordCoRecall,
+  getSpreadingActivationTargets,
+} from "./core/associations.ts";
+export { encodeProcedural, getSkills, promoteToSkill } from "./core/procedural-store.ts";
+export { discoverChunks, getChunkMembers, type Chunk } from "./core/chunking.ts";
+export {
+  baseLevelActivation,
+  spreadingActivationStrength,
+  totalActivation,
+  activationNoise,
+  canRetrieve,
+  retrievalLatency,
+  computeActivation,
+} from "./core/activation.ts";
+export { ebbinghausRetention, memoryStrength, refreshActivations } from "./core/forgetting.ts";
+export { tokenize, extractKeywords } from "./core/search.ts";
+export { defaultEmotionWeight, isValidEmotion } from "./core/emotional-tag.ts";
+export {
+  DEFAULT_CONFIG,
+  loadConfig,
+  resolveDbPath,
+  type CognitiveConfig,
+} from "./config/defaults.ts";
+export {
+  MemoryType,
+  Emotion,
+  AssociationType,
+  AccessType,
+  generateId,
+  generateMemoryId,
+} from "./core/memory.ts";
+export type {
+  Memory,
+  EncodeInput,
+  AccessLogEntry,
+  Association,
+  WorkingMemorySlot,
+  ConsolidationLog,
+  RecallResult,
+} from "./core/memory.ts";

package/src/mcp/server.ts

@@ -0,0 +1,122 @@
+#!/usr/bin/env bun
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod/v4";
+import { EngramEngine } from "../core/engine.ts";
+import { MemoryType, Emotion } from "../core/memory.ts";
+import { handleStore, handleRecall, handleManage } from "./tools.ts";
+
+const engine = EngramEngine.create();
+
+const server = new McpServer({
+  name: "engram",
+  version: "0.2.0",
+});
+
+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?`,
+    inputSchema: z.discriminatedUnion("action", [
+      z.object({
+        action: z.literal("encode"),
+        content: z.string().describe("Memory content"),
+        type: z.nativeEnum(MemoryType).optional().describe("Memory type (default: semantic)"),
+        emotion: z.nativeEnum(Emotion).optional().describe("Emotional tag"),
+        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("reconsolidate"),
+        id: z.string().describe("Memory ID to update"),
+        newContext: z.string().optional().describe("New context to blend"),
+        currentEmotion: z.nativeEnum(Emotion).optional().describe("Current emotional state"),
+        currentEmotionWeight: z.number().min(0).max(1).optional().describe("Emotion intensity"),
+      }),
+    ]),
+  },
+  async (args) => handleStore(engine, args),
+);
+
+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.`,
+    inputSchema: z.discriminatedUnion("action", [
+      z.object({
+        action: z.literal("recall").optional().default("recall"),
+        cue: z.string().describe("Recall cue"),
+        limit: z.number().optional().describe("Max results (default: 5)"),
+        type: z.nativeEnum(MemoryType).optional().describe("Filter by type"),
+        context: z.string().optional().describe("Filter by context"),
+        associative: z.boolean().optional().describe("Spreading activation (default: true)"),
+        verbose: z.boolean().optional().describe("Full fields"),
+      }),
+      z.object({
+        action: z.literal("inspect"),
+        id: z.string().describe("Memory ID or prefix"),
+      }),
+      z.object({
+        action: z.literal("stats"),
+      }),
+    ]),
+  },
+  async (args) => handleRecall(engine, args),
+);
+
+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.`,
+    inputSchema: z.discriminatedUnion("action", [
+      z.object({
+        action: z.literal("consolidate"),
+      }),
+      z.object({
+        action: z.literal("focus_push"),
+        content: z.string().describe("Content to hold in focus"),
+        memoryRef: z.string().optional().describe("Reference to existing memory ID"),
+      }),
+      z.object({
+        action: z.literal("focus_pop"),
+      }),
+      z.object({
+        action: z.literal("focus_get"),
+      }),
+      z.object({
+        action: z.literal("focus_clear"),
+      }),
+    ]),
+  },
+  async (args) => handleManage(engine, args),
+);
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("engram MCP server running on stdio");
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});