@cogmem/engram 0.1.0 → 0.2.1

package/README.md

@@ -1,7 +1,5 @@
 # engram
 
-**Human memory for artificial minds.**
-
 > **Note:** This is an experiment in cognitive memory architecture. It's a research prototype, not production software.
 
 Every AI agent today has amnesia. They process, respond, and forget. engram fixes this — not with a smarter key-value store, but with a cognitive memory system modeled on how the human brain actually forms, stores, recalls, and forgets information.

package/package.json

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

package/src/config/defaults.ts

@@ -14,6 +14,9 @@ export interface CognitiveConfig {
   reconsolidationBlendRate: number;
   chunkingSimilarityThreshold: number;
   semanticExtractionThreshold: number;
+  temporalContextWindow: number;
+  recallSpreadingDepth: number;
+  workingMemoryPrimingWeight: number;
   dbPath: string;
 }
 
@@ -33,6 +36,9 @@ export const DEFAULT_CONFIG: CognitiveConfig = {
   reconsolidationBlendRate: 0.1,
   chunkingSimilarityThreshold: 0.6,
   semanticExtractionThreshold: 3,
+  temporalContextWindow: 10,
+  recallSpreadingDepth: 3,
+  workingMemoryPrimingWeight: 0.5,
   dbPath: "~/.engram/memory.db",
 };
 

package/src/core/associations.ts

@@ -1,9 +1,21 @@
 import type { CognitiveConfig } from "../config/defaults.ts";
 import type { EngramStorage } from "../storage/sqlite.ts";
-import type { Association, AssociationType, Memory } from "./memory.ts";
+import type { Association, AssociationType, Emotion, Memory } from "./memory.ts";
 import { generateId } from "./memory.ts";
 import { extractKeywords } from "./search.ts";
 
+type ArousalTier = "high" | "medium" | "low";
+
+const AROUSAL_TIERS: Record<Emotion, ArousalTier> = {
+  anxiety: "high",
+  surprise: "high",
+  joy: "medium",
+  frustration: "medium",
+  satisfaction: "low",
+  curiosity: "low",
+  neutral: "low",
+};
+
 export function formAssociation(
   storage: EngramStorage,
   sourceId: string,
@@ -36,33 +48,62 @@ export function strengthenAssociation(
 export function formTemporalAssociations(
   storage: EngramStorage,
   memory: Memory,
-  windowMs: number = 300000,
+  config: CognitiveConfig,
   now?: number,
 ): Association[] {
   const currentTime = now ?? Date.now();
-  const allMemories = storage.getAllMemories();
   const formed: Association[] = [];
 
-  for (const other of allMemories) {
-    if (other.id === memory.id) continue;
+  if (memory.context) {
+    const contextMemories = storage
+      .getMemoriesByContext(memory.context, undefined, config.temporalContextWindow)
+      .filter((m) => m.id !== memory.id)
+      .sort((a, b) => b.encodedAt - a.encodedAt);
+
+    for (let i = 0; i < contextMemories.length; i++) {
+      const other = contextMemories[i]!;
+      const positionGap = i + 1;
+      const strength = 1 / (1 + positionGap);
 
-    const timeDiff = Math.abs(memory.encodedAt - other.encodedAt);
-    if (timeDiff <= windowMs) {
       const existing = storage.getAssociationsFrom(memory.id);
       const alreadyLinked = existing.some((a) => a.targetId === other.id);
       if (alreadyLinked) continue;
 
-      const strength = 1 - timeDiff / windowMs;
       const assoc = formAssociation(
         storage,
         memory.id,
         other.id,
         "temporal",
-        Math.max(0.1, strength * 0.8),
+        Math.max(0.1, strength),
         currentTime,
       );
       formed.push(assoc);
     }
+  } else {
+    const windowMs = 300000;
+    const allMemories = storage.getAllMemories();
+
+    for (const other of allMemories) {
+      if (other.id === memory.id) continue;
+
+      const timeDiff = Math.abs(memory.encodedAt - other.encodedAt);
+      if (timeDiff <= windowMs) {
+        const existing = storage.getAssociationsFrom(memory.id);
+        const alreadyLinked = existing.some((a) => a.targetId === other.id);
+        if (alreadyLinked) continue;
+
+        const strength = 1 - timeDiff / windowMs;
+        const assoc = formAssociation(
+          storage,
+          memory.id,
+          other.id,
+          "temporal",
+          Math.max(0.1, strength * 0.8),
+          currentTime,
+        );
+        formed.push(assoc);
+      }
+    }
   }
 
   return formed;
@@ -111,6 +152,86 @@ export function formSemanticAssociations(
   return formed;
 }
 
+export function formEmotionalAssociations(
+  storage: EngramStorage,
+  memory: Memory,
+  now?: number,
+): Association[] {
+  if (memory.emotion === "neutral" || memory.emotionWeight <= 0.3) return [];
+
+  const currentTime = now ?? Date.now();
+  const allMemories = storage.getAllMemories();
+  const formed: Association[] = [];
+  const memoryTier = AROUSAL_TIERS[memory.emotion];
+
+  for (const other of allMemories) {
+    if (other.id === memory.id) continue;
+    if (other.emotion === "neutral" || other.emotionWeight <= 0.3) continue;
+
+    const existing = storage.getAssociations(memory.id);
+    const alreadyLinked = existing.some(
+      (a) =>
+        a.type === "emotional" &&
+        ((a.sourceId === memory.id && a.targetId === other.id) ||
+          (a.sourceId === other.id && a.targetId === memory.id)),
+    );
+    if (alreadyLinked) continue;
+
+    let strength: number;
+    if (memory.emotion === other.emotion) {
+      strength = 1 - Math.abs(memory.emotionWeight - other.emotionWeight);
+    } else if (AROUSAL_TIERS[other.emotion] === memoryTier) {
+      strength = 0.3 * (1 - Math.abs(memory.emotionWeight - other.emotionWeight));
+    } else {
+      continue;
+    }
+
+    if (strength < 0.1) continue;
+
+    const assoc = formAssociation(storage, memory.id, other.id, "emotional", strength, currentTime);
+    formed.push(assoc);
+  }
+
+  return formed;
+}
+
+export function formCausalAssociations(
+  storage: EngramStorage,
+  memory: Memory,
+  config: CognitiveConfig,
+  now?: number,
+): Association[] {
+  if (!memory.context) return [];
+
+  const currentTime = now ?? Date.now();
+  const contextMemories = storage
+    .getMemoriesByContext(memory.context, undefined, config.temporalContextWindow)
+    .filter((m) => m.id !== memory.id && m.encodedAt < memory.encodedAt)
+    .sort((a, b) => b.encodedAt - a.encodedAt);
+
+  const formed: Association[] = [];
+
+  for (let i = 0; i < contextMemories.length; i++) {
+    const source = contextMemories[i]!;
+    const sequenceGap = i + 1;
+    const strength = 1 / (1 + sequenceGap);
+
+    const existing = storage.getAssociations(memory.id);
+    const alreadyLinked = existing.some(
+      (a) =>
+        a.type === "causal" &&
+        ((a.sourceId === source.id && a.targetId === memory.id) ||
+          (a.sourceId === memory.id && a.targetId === source.id)),
+    );
+    if (alreadyLinked) continue;
+
+    const assoc = formAssociation(storage, source.id, memory.id, "causal", strength, currentTime);
+    formed.push(assoc);
+  }
+
+  return formed;
+}
+
 export function recordCoRecall(
   storage: EngramStorage,
   memoryIds: string[],
@@ -147,7 +268,7 @@ export function getSpreadingActivationTargets(
   storage: EngramStorage,
   sourceId: string,
   config: CognitiveConfig,
-  maxDepth: number = 2,
+  maxDepth: number = config.recallSpreadingDepth,
 ): { memoryId: string; activationBoost: number; depth: number }[] {
   const visited = new Set<string>([sourceId]);
   const results: { memoryId: string; activationBoost: number; depth: number }[] = [];

package/src/core/consolidation.ts

@@ -3,7 +3,12 @@ import type { EngramStorage } from "../storage/sqlite.ts";
 import type { Memory, ConsolidationLog } from "./memory.ts";
 import { generateId } from "./memory.ts";
 import { refreshActivations } from "./forgetting.ts";
-import { formSemanticAssociations, formTemporalAssociations } from "./associations.ts";
+import {
+  formSemanticAssociations,
+  formTemporalAssociations,
+  formEmotionalAssociations,
+  formCausalAssociations,
+} from "./associations.ts";
 import { encode } from "./encoder.ts";
 import { extractKeywords, tokenize } from "./search.ts";
 
@@ -63,10 +68,12 @@ export function consolidate(
 
   const remainingMemories = storage.getAllMemories();
   for (const memory of remainingMemories) {
-    const temporalAssocs = formTemporalAssociations(storage, memory, 300000, currentTime);
+    const temporalAssocs = formTemporalAssociations(storage, memory, config, currentTime);
     const semanticAssocs = formSemanticAssociations(storage, memory, currentTime);
+    const emotionalAssocs = formEmotionalAssociations(storage, memory, currentTime);
+    const causalAssocs = formCausalAssociations(storage, memory, config, currentTime);
 
-    for (const assoc of [...temporalAssocs, ...semanticAssocs]) {
+    for (const assoc of [...temporalAssocs, ...semanticAssocs, ...emotionalAssocs, ...causalAssocs]) {
       result.associationsDiscovered++;
       result.discoveredAssociationPairs.push([assoc.sourceId, assoc.targetId]);
     }

package/src/core/encoder.ts

@@ -4,6 +4,7 @@ import type { Memory, EncodeInput } from "./memory.ts";
 import { generateMemoryId } from "./memory.ts";
 import { defaultEmotionWeight } from "./emotional-tag.ts";
 import { baseLevelActivation } from "./activation.ts";
+import { formEmotionalAssociations, formCausalAssociations } from "./associations.ts";
 
 export function encode(
   storage: EngramStorage,
@@ -43,5 +44,8 @@ export function encode(
     storage.logAccess(id, "encode", currentTime);
   });
 
+  formEmotionalAssociations(storage, memory, currentTime);
+  formCausalAssociations(storage, memory, config, currentTime);
+
   return memory;
 }

package/src/core/memory.ts

@@ -29,6 +29,8 @@ export const AssociationType = {
   Temporal: "temporal",
   Semantic: "semantic",
   CoRecall: "co-recall",
+  Emotional: "emotional",
+  Causal: "causal",
 } as const;
 export type AssociationType = (typeof AssociationType)[keyof typeof AssociationType];
 

package/src/core/recall.ts

@@ -2,6 +2,8 @@ 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";
+import { getSpreadingActivationTargets } from "./associations.ts";
+import { getWorkingMemoryIds } from "./working-memory.ts";
 
 export function recall(
   storage: EngramStorage,
@@ -20,22 +22,17 @@ export function recall(
   const limit = options?.limit ?? 10;
   const associative = options?.associative ?? true;
 
-  const candidateMap = new Map<string, Memory>();
+  const seedIds = new Set<string>();
+
+  const wmIds = getWorkingMemoryIds(storage);
+  for (const id of wmIds) seedIds.add(id);
 
   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);
-  }
+  for (const id of ftsIds) seedIds.add(id);
 
   if (options?.context) {
     const contextMatches = storage.getMemoriesByContext(options.context, options?.type, limit * 2);
-    for (const m of contextMatches) {
-      candidateMap.set(m.id, m);
-    }
+    for (const m of contextMatches) seedIds.add(m.id);
   }
 
   const allCandidates = options?.type
@@ -49,6 +46,32 @@ export function recall(
 
   const sorted = filtered.sort((a, b) => b.activation - a.activation);
   for (const m of sorted.slice(0, limit)) {
+    seedIds.add(m.id);
+  }
+
+  const candidateIds = new Set<string>(seedIds);
+  const graphBoosts = new Map<string, number>();
+
+  if (associative) {
+    for (const seedId of seedIds) {
+      const targets = getSpreadingActivationTargets(storage, seedId, config);
+      const isWmSeed = wmIds.includes(seedId);
+      const primingWeight = isWmSeed ? config.workingMemoryPrimingWeight : 1.0;
+
+      for (const t of targets) {
+        candidateIds.add(t.memoryId);
+        const existing = graphBoosts.get(t.memoryId) ?? 0;
+        graphBoosts.set(t.memoryId, existing + t.activationBoost * primingWeight);
+      }
+    }
+  }
+
+  const candidateMap = new Map<string, Memory>();
+  for (const id of candidateIds) {
+    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);
   }
 
@@ -59,8 +82,8 @@ export function recall(
   for (const memory of candidateMap.values()) {
     const timestamps = storage.getAccessTimestamps(memory.id);
 
-    let spreadingSum = 0;
-    if (associative) {
+    let spreadingSum = graphBoosts.get(memory.id) ?? 0;
+    if (associative && spreadingSum === 0) {
       const assocFrom = storage.getAssociationsFrom(memory.id);
       const assocTo = storage.getAssociationsTo(memory.id);
       const allAssocs = [...assocFrom, ...assocTo];

package/src/core/working-memory.ts

@@ -54,6 +54,13 @@ export function clearFocus(storage: EngramStorage): number {
   return count;
 }
 
+export function getWorkingMemoryIds(storage: EngramStorage): string[] {
+  return storage
+    .getWorkingMemory()
+    .filter((s) => s.memoryRef !== null)
+    .map((s) => s.memoryRef!);
+}
+
 export function focusUtilization(
   storage: EngramStorage,
   config: CognitiveConfig,

package/src/index.ts

@@ -10,11 +10,14 @@ export {
   getFocus,
   clearFocus,
   focusUtilization,
+  getWorkingMemoryIds,
 } from "./core/working-memory.ts";
 export {
   formAssociation,
   formTemporalAssociations,
   formSemanticAssociations,
+  formEmotionalAssociations,
+  formCausalAssociations,
   recordCoRecall,
   getSpreadingActivationTargets,
 } from "./core/associations.ts";

package/src/mcp/server.ts

@@ -62,7 +62,7 @@ server.registerTool(
     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"),
+        action: z.literal("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"),