@cogmem/engram 0.0.0

package/src/config/defaults.ts

@@ -0,0 +1,58 @@
+export interface CognitiveConfig {
+  decayRate: number;
+  retrievalThreshold: number;
+  latencyFactor: number;
+  latencyExponent: number;
+  activationNoise: number;
+  workingMemoryCapacity: number;
+  maxSpreadingActivation: number;
+  minAssociationStrength: number;
+  emotionalBoostFactor: number;
+  pruningThreshold: number;
+  associationFormationThreshold: number;
+  retrievalStrengtheningBoost: number;
+  reconsolidationBlendRate: number;
+  chunkingSimilarityThreshold: number;
+  semanticExtractionThreshold: number;
+  dbPath: string;
+}
+
+export const DEFAULT_CONFIG: CognitiveConfig = {
+  decayRate: 0.5,
+  retrievalThreshold: -3.0,
+  latencyFactor: 1.0,
+  latencyExponent: 1.0,
+  activationNoise: 0.25,
+  workingMemoryCapacity: 7,
+  maxSpreadingActivation: 1.5,
+  minAssociationStrength: 0.1,
+  emotionalBoostFactor: 2.0,
+  pruningThreshold: -2.0,
+  associationFormationThreshold: 2,
+  retrievalStrengtheningBoost: 0.1,
+  reconsolidationBlendRate: 0.1,
+  chunkingSimilarityThreshold: 0.6,
+  semanticExtractionThreshold: 3,
+  dbPath: "~/.engram/memory.db",
+};
+
+export function resolveDbPath(dbPath: string): string {
+  if (dbPath.startsWith("~")) {
+    const home = process.env.HOME || process.env.USERPROFILE || "/tmp";
+    return dbPath.replace("~", home);
+  }
+  return dbPath;
+}
+
+export function loadConfig(overrides?: Partial<CognitiveConfig>): CognitiveConfig {
+  const config = { ...DEFAULT_CONFIG, ...overrides };
+
+  if (process.env.ENGRAM_DB_PATH) config.dbPath = process.env.ENGRAM_DB_PATH;
+  if (process.env.ENGRAM_DECAY_RATE) config.decayRate = Number(process.env.ENGRAM_DECAY_RATE);
+  if (process.env.ENGRAM_WM_CAPACITY)
+    config.workingMemoryCapacity = Number(process.env.ENGRAM_WM_CAPACITY);
+  if (process.env.ENGRAM_RETRIEVAL_THRESHOLD)
+    config.retrievalThreshold = Number(process.env.ENGRAM_RETRIEVAL_THRESHOLD);
+
+  return config;
+}

package/src/core/activation.ts

@@ -0,0 +1,75 @@
+import type { CognitiveConfig } from "../config/defaults.ts";
+
+// B_i = ln(Σ t_j^{-d})
+export function baseLevelActivation(
+  accessTimestamps: number[],
+  now: number,
+  decayRate: number,
+): number {
+  if (accessTimestamps.length === 0) return -Infinity;
+
+  let sum = 0;
+  for (const ts of accessTimestamps) {
+    const elapsedSeconds = Math.max((now - ts) / 1000, 0.001);
+    sum += Math.pow(elapsedSeconds, -decayRate);
+  }
+
+  return Math.log(sum);
+}
+
+// S_ji = S - ln(fan_j)
+export function spreadingActivationStrength(maxStrength: number, fanCount: number): number {
+  if (fanCount <= 0) return 0;
+  return Math.max(0, maxStrength - Math.log(fanCount));
+}
+
+// A_i = B_i + Σ(W_j · S_ji) + ε
+export function totalActivation(baseLevel: number, spreadingSum: number, noise: number): number {
+  return baseLevel + spreadingSum + noise;
+}
+
+export function activationNoise(stddev: number): number {
+  if (stddev === 0) return 0;
+  const u1 = Math.random();
+  const u2 = Math.random();
+  const z = Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+  return z * stddev;
+}
+
+export function canRetrieve(activation: number, threshold: number): boolean {
+  return activation > threshold;
+}
+
+// Time = F · e^{-f · A_i}
+export function retrievalLatency(
+  activation: number,
+  latencyFactor: number,
+  latencyExponent: number,
+): number {
+  return latencyFactor * Math.exp(-latencyExponent * activation);
+}
+
+export function computeActivation(
+  accessTimestamps: number[],
+  now: number,
+  config: CognitiveConfig,
+  options?: {
+    spreadingSum?: number;
+    noiseOverride?: number;
+    emotionWeight?: number;
+  },
+): { activation: number; baseLevel: number; spreading: number; noise: number; latency: number } {
+  const baseLevel = baseLevelActivation(accessTimestamps, now, config.decayRate);
+
+  const emotionBoost = options?.emotionWeight
+    ? Math.log(1 + options.emotionWeight * config.emotionalBoostFactor)
+    : 0;
+
+  const spreading = options?.spreadingSum ?? 0;
+  const noise = options?.noiseOverride ?? activationNoise(config.activationNoise);
+
+  const activation = totalActivation(baseLevel + emotionBoost, spreading, noise);
+  const latency = retrievalLatency(activation, config.latencyFactor, config.latencyExponent);
+
+  return { activation, baseLevel: baseLevel + emotionBoost, spreading, noise, latency };
+}

package/src/core/associations.ts

@@ -0,0 +1,186 @@
+import type { CognitiveConfig } from "../config/defaults.ts";
+import type { EngramStorage } from "../storage/sqlite.ts";
+import type { Association, AssociationType, Memory } from "./memory.ts";
+import { generateId } from "./memory.ts";
+import { extractKeywords } from "./search.ts";
+
+export function formAssociation(
+  storage: EngramStorage,
+  sourceId: string,
+  targetId: string,
+  type: AssociationType,
+  strength?: number,
+  now?: number,
+): Association {
+  const assoc: Association = {
+    id: generateId(),
+    sourceId,
+    targetId,
+    strength: strength ?? 0.5,
+    formedAt: now ?? Date.now(),
+    type,
+  };
+
+  storage.insertAssociation(assoc);
+  return assoc;
+}
+
+export function strengthenAssociation(
+  storage: EngramStorage,
+  associationId: string,
+  boost: number = 0.1,
+): void {
+  storage.updateAssociationStrength(associationId, Math.min(1.0, boost));
+}
+
+export function formTemporalAssociations(
+  storage: EngramStorage,
+  memory: Memory,
+  windowMs: number = 300000,
+  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;
+
+    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;
+}
+
+export function formSemanticAssociations(
+  storage: EngramStorage,
+  memory: Memory,
+  now?: number,
+): Association[] {
+  const currentTime = now ?? Date.now();
+  const keywords = extractKeywords(memory.content);
+  if (keywords.length === 0) return [];
+
+  const allMemories = storage.getAllMemories();
+  const formed: Association[] = [];
+
+  for (const other of allMemories) {
+    if (other.id === memory.id) continue;
+
+    const otherKeywords = extractKeywords(other.content);
+    const overlap = keywords.filter((k) => otherKeywords.includes(k));
+
+    if (overlap.length > 0) {
+      const existing = storage.getAssociations(memory.id);
+      const alreadyLinked = existing.some(
+        (a) =>
+          (a.sourceId === memory.id && a.targetId === other.id) ||
+          (a.sourceId === other.id && a.targetId === memory.id),
+      );
+      if (alreadyLinked) continue;
+
+      const strength = overlap.length / Math.max(keywords.length, otherKeywords.length);
+      const assoc = formAssociation(
+        storage,
+        memory.id,
+        other.id,
+        "semantic",
+        Math.max(0.1, strength),
+        currentTime,
+      );
+      formed.push(assoc);
+    }
+  }
+
+  return formed;
+}
+
+export function recordCoRecall(
+  storage: EngramStorage,
+  memoryIds: string[],
+  now?: number,
+): Association[] {
+  const currentTime = now ?? Date.now();
+  const formed: Association[] = [];
+
+  for (let i = 0; i < memoryIds.length; i++) {
+    for (let j = i + 1; j < memoryIds.length; j++) {
+      const srcId = memoryIds[i]!;
+      const tgtId = memoryIds[j]!;
+      const existing = storage.getAssociations(srcId);
+      const link = existing.find(
+        (a) =>
+          (a.sourceId === srcId && a.targetId === tgtId) ||
+          (a.sourceId === tgtId && a.targetId === srcId),
+      );
+
+      if (link) {
+        const newStrength = Math.min(1.0, link.strength + 0.1);
+        storage.updateAssociationStrength(link.id, newStrength);
+      } else {
+        const assoc = formAssociation(storage, srcId, tgtId, "co-recall", 0.3, currentTime);
+        formed.push(assoc);
+      }
+    }
+  }
+
+  return formed;
+}
+
+export function getSpreadingActivationTargets(
+  storage: EngramStorage,
+  sourceId: string,
+  config: CognitiveConfig,
+  maxDepth: number = 2,
+): { memoryId: string; activationBoost: number; depth: number }[] {
+  const visited = new Set<string>([sourceId]);
+  const results: { memoryId: string; activationBoost: number; depth: number }[] = [];
+
+  let frontier = [{ id: sourceId, boost: 1.0 }];
+
+  for (let depth = 1; depth <= maxDepth; depth++) {
+    const nextFrontier: { id: string; boost: number }[] = [];
+
+    for (const { id, boost } of frontier) {
+      const associations = storage.getAssociations(id);
+
+      for (const assoc of associations) {
+        const targetId = assoc.sourceId === id ? assoc.targetId : assoc.sourceId;
+        if (visited.has(targetId)) continue;
+        visited.add(targetId);
+
+        const fanCount = storage.getFanCount(id);
+        const spreadStrength = Math.max(
+          0,
+          config.maxSpreadingActivation - Math.log(Math.max(1, fanCount)),
+        );
+        const activationBoost = boost * assoc.strength * spreadStrength;
+
+        if (activationBoost > 0.01) {
+          results.push({ memoryId: targetId, activationBoost, depth });
+          nextFrontier.push({ id: targetId, boost: activationBoost });
+        }
+      }
+    }
+
+    frontier = nextFrontier;
+  }
+
+  return results;
+}

package/src/core/chunking.ts

@@ -0,0 +1,108 @@
+import type { CognitiveConfig } from "../config/defaults.ts";
+import type { EngramStorage } from "../storage/sqlite.ts";
+import type { Memory } from "./memory.ts";
+import { generateId } from "./memory.ts";
+import { extractKeywords } from "./search.ts";
+
+export interface Chunk {
+  id: string;
+  memberIds: string[];
+  label: string;
+}
+
+class UnionFind {
+  private parent: Map<string, string> = new Map();
+  private rank: Map<string, number> = new Map();
+
+  add(x: string): void {
+    if (!this.parent.has(x)) {
+      this.parent.set(x, x);
+      this.rank.set(x, 0);
+    }
+  }
+
+  find(x: string): string {
+    const p = this.parent.get(x);
+    if (p === undefined) return x;
+    if (p !== x) {
+      const root = this.find(p);
+      this.parent.set(x, root);
+      return root;
+    }
+    return x;
+  }
+
+  union(a: string, b: string): void {
+    const rootA = this.find(a);
+    const rootB = this.find(b);
+    if (rootA === rootB) return;
+
+    const rankA = this.rank.get(rootA) ?? 0;
+    const rankB = this.rank.get(rootB) ?? 0;
+
+    if (rankA < rankB) {
+      this.parent.set(rootA, rootB);
+    } else if (rankA > rankB) {
+      this.parent.set(rootB, rootA);
+    } else {
+      this.parent.set(rootB, rootA);
+      this.rank.set(rootA, rankA + 1);
+    }
+  }
+
+  components(): Map<string, string[]> {
+    const groups = new Map<string, string[]>();
+    for (const id of this.parent.keys()) {
+      const root = this.find(id);
+      const group = groups.get(root) ?? [];
+      group.push(id);
+      groups.set(root, group);
+    }
+    return groups;
+  }
+}
+
+export function discoverChunks(storage: EngramStorage, config: CognitiveConfig): Chunk[] {
+  const allMemories = storage.getAllMemories();
+  const memoryMap = new Map<string, Memory>();
+  const uf = new UnionFind();
+
+  for (const memory of allMemories) {
+    if (memory.chunkId) continue;
+    memoryMap.set(memory.id, memory);
+    uf.add(memory.id);
+  }
+
+  for (const memory of memoryMap.values()) {
+    const associations = storage.getAssociations(memory.id);
+    for (const assoc of associations) {
+      if (assoc.strength < config.chunkingSimilarityThreshold) continue;
+      const otherId = assoc.sourceId === memory.id ? assoc.targetId : assoc.sourceId;
+      if (!memoryMap.has(otherId)) continue;
+      uf.union(memory.id, otherId);
+    }
+  }
+
+  const chunks: Chunk[] = [];
+  for (const memberIds of uf.components().values()) {
+    if (memberIds.length < 2) continue;
+
+    const members = memberIds.map((id) => memoryMap.get(id)!);
+    const chunkId = generateId();
+    const keywords = extractKeywords(members.map((m) => m.content).join(" "), 3);
+    const label = keywords.join(" + ") || "chunk";
+
+    for (const member of members) {
+      member.chunkId = chunkId;
+      storage.updateMemory(member);
+    }
+
+    chunks.push({ id: chunkId, memberIds, label });
+  }
+
+  return chunks;
+}
+
+export function getChunkMembers(storage: EngramStorage, chunkId: string): Memory[] {
+  return storage.getAllMemories().filter((m) => m.chunkId === chunkId);
+}

package/src/core/consolidation.ts

@@ -0,0 +1,150 @@
+import type { CognitiveConfig } from "../config/defaults.ts";
+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 { encode } from "./encoder.ts";
+import { extractKeywords, tokenize } from "./search.ts";
+
+export interface ConsolidationResult {
+  memoriesStrengthened: number;
+  memoriesPruned: number;
+  factsExtracted: number;
+  associationsDiscovered: number;
+  prunedIds: string[];
+  extractedFacts: string[];
+  discoveredAssociationPairs: [string, string][];
+}
+
+export function consolidate(
+  storage: EngramStorage,
+  config: CognitiveConfig,
+  now?: number,
+): ConsolidationResult {
+  const currentTime = now ?? Date.now();
+
+  const result: ConsolidationResult = {
+    memoriesStrengthened: 0,
+    memoriesPruned: 0,
+    factsExtracted: 0,
+    associationsDiscovered: 0,
+    prunedIds: [],
+    extractedFacts: [],
+    discoveredAssociationPairs: [],
+  };
+
+  refreshActivations(storage, config, currentTime);
+
+  const allMemories = storage.getAllMemories();
+  for (const memory of allMemories) {
+    if (memory.type === "procedural") continue;
+
+    const timestamps = storage.getAccessTimestamps(memory.id);
+    const recentAccesses = timestamps.filter((t) => currentTime - t < 86400000);
+
+    if (recentAccesses.length >= 2) {
+      storage.logAccess(memory.id, "consolidate", currentTime);
+      result.memoriesStrengthened++;
+    }
+  }
+
+  refreshActivations(storage, config, currentTime);
+  const weakMemories = storage.getMemoriesBelowActivation(config.pruningThreshold);
+  for (const memory of weakMemories) {
+    result.prunedIds.push(memory.id);
+    storage.deleteMemory(memory.id);
+    result.memoriesPruned++;
+  }
+
+  const extractedFacts = extractSemanticFacts(storage, config, currentTime);
+  result.factsExtracted = extractedFacts.length;
+  result.extractedFacts = extractedFacts;
+
+  const remainingMemories = storage.getAllMemories();
+  for (const memory of remainingMemories) {
+    const temporalAssocs = formTemporalAssociations(storage, memory, 300000, currentTime);
+    const semanticAssocs = formSemanticAssociations(storage, memory, currentTime);
+
+    for (const assoc of [...temporalAssocs, ...semanticAssocs]) {
+      result.associationsDiscovered++;
+      result.discoveredAssociationPairs.push([assoc.sourceId, assoc.targetId]);
+    }
+  }
+
+  storage.deleteWeakAssociations(config.minAssociationStrength);
+
+  const logEntry: ConsolidationLog = {
+    id: generateId(),
+    ranAt: currentTime,
+    memoriesStrengthened: result.memoriesStrengthened,
+    memoriesPruned: result.memoriesPruned,
+    factsExtracted: result.factsExtracted,
+    associationsDiscovered: result.associationsDiscovered,
+  };
+  storage.logConsolidation(logEntry);
+
+  return result;
+}
+
+function extractSemanticFacts(
+  storage: EngramStorage,
+  config: CognitiveConfig,
+  now: number,
+): string[] {
+  const episodics = storage.getAllMemories("episodic");
+  if (episodics.length < config.semanticExtractionThreshold) return [];
+
+  const extracted: string[] = [];
+
+  const keywordGroups = new Map<string, Memory[]>();
+  for (const memory of episodics) {
+    const keywords = extractKeywords(memory.content, 3);
+    for (const keyword of keywords) {
+      const group = keywordGroups.get(keyword) ?? [];
+      group.push(memory);
+      keywordGroups.set(keyword, group);
+    }
+  }
+
+  for (const [keyword, group] of keywordGroups) {
+    if (group.length < config.semanticExtractionThreshold) continue;
+
+    const existing = storage.searchMemories(keyword, 5);
+    const alreadyExtracted = existing.some(
+      (m) => m.type === "semantic" && m.content.includes(`[extracted]`),
+    );
+    if (alreadyExtracted) continue;
+
+    const allTokenSets = group.map((m) => new Set(tokenize(m.content)));
+    const sharedTokens: string[] = [];
+    const firstSet = allTokenSets[0];
+    if (firstSet) {
+      for (const token of firstSet) {
+        if (allTokenSets.every((s) => s.has(token))) {
+          sharedTokens.push(token);
+        }
+      }
+    }
+
+    const factContent =
+      sharedTokens.length > 1
+        ? `[extracted] Pattern observed across ${group.length} episodes: ${sharedTokens.join(", ")}`
+        : `[extracted] Recurring theme (${group.length}x): ${keyword}`;
+
+    encode(
+      storage,
+      {
+        content: factContent,
+        type: "semantic",
+        context: group[0]?.context ?? undefined,
+      },
+      config,
+      now,
+    );
+
+    extracted.push(factContent);
+  }
+
+  return extracted;
+}

package/src/core/emotional-tag.ts

@@ -0,0 +1,19 @@
+import { Emotion } from "./memory.ts";
+
+const EMOTION_WEIGHTS: Record<Emotion, number> = {
+  anxiety: 0.8,
+  frustration: 0.6,
+  surprise: 0.7,
+  joy: 0.5,
+  satisfaction: 0.4,
+  curiosity: 0.3,
+  neutral: 0.0,
+};
+
+export function defaultEmotionWeight(emotion: Emotion): number {
+  return EMOTION_WEIGHTS[emotion] ?? 0.0;
+}
+
+export function isValidEmotion(s: string): s is Emotion {
+  return (Object.values(Emotion) as string[]).includes(s);
+}

package/src/core/encoder.ts

@@ -0,0 +1,47 @@
+import type { CognitiveConfig } from "../config/defaults.ts";
+import type { EngramStorage } from "../storage/sqlite.ts";
+import type { Memory, EncodeInput } from "./memory.ts";
+import { generateMemoryId } from "./memory.ts";
+import { defaultEmotionWeight } from "./emotional-tag.ts";
+import { baseLevelActivation } from "./activation.ts";
+
+export function encode(
+  storage: EngramStorage,
+  input: EncodeInput,
+  config: CognitiveConfig,
+  now?: number,
+): Memory {
+  const currentTime = now ?? Date.now();
+
+  const emotion = input.emotion ?? "neutral";
+  const emotionWeight = input.emotionWeight ?? defaultEmotionWeight(emotion);
+
+  const id = generateMemoryId(input.content, input.type);
+
+  const initialActivation = baseLevelActivation([currentTime], currentTime, config.decayRate);
+
+  const emotionBoost =
+    emotionWeight > 0 ? Math.log(1 + emotionWeight * config.emotionalBoostFactor) : 0;
+
+  const memory: Memory = {
+    id,
+    type: input.type,
+    content: input.content,
+    encodedAt: currentTime,
+    lastRecalledAt: null,
+    recallCount: 0,
+    activation: initialActivation + emotionBoost,
+    emotion,
+    emotionWeight,
+    context: input.context ?? null,
+    chunkId: null,
+    reconsolidationCount: 0,
+  };
+
+  storage.transaction(() => {
+    storage.insertMemory(memory);
+    storage.logAccess(id, "encode", currentTime);
+  });
+
+  return memory;
+}

package/src/core/engine.ts

@@ -0,0 +1,50 @@
+import type { CognitiveConfig } from "../config/defaults.ts";
+import { loadConfig } from "../config/defaults.ts";
+import { EngramStorage } from "../storage/sqlite.ts";
+import { execSync } from "node:child_process";
+import { basename } from "node:path";
+
+export function detectProjectContext(): string | null {
+  try {
+    const root = execSync("git rev-parse --show-toplevel", {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    return `project:${basename(root)}`;
+  } catch {
+    return null;
+  }
+}
+
+export class EngramEngine {
+  readonly storage: EngramStorage;
+  readonly config: CognitiveConfig;
+  readonly projectContext: string | null;
+
+  private constructor(
+    storage: EngramStorage,
+    config: CognitiveConfig,
+    projectContext: string | null,
+  ) {
+    this.storage = storage;
+    this.config = config;
+    this.projectContext = projectContext;
+  }
+
+  static create(configOverrides?: Partial<CognitiveConfig>): EngramEngine {
+    const config = loadConfig(configOverrides);
+    const storage = EngramStorage.open(config.dbPath);
+    const projectContext = detectProjectContext();
+    return new EngramEngine(storage, config, projectContext);
+  }
+
+  static inMemory(configOverrides?: Partial<CognitiveConfig>): EngramEngine {
+    const config = loadConfig(configOverrides);
+    const storage = EngramStorage.inMemory();
+    return new EngramEngine(storage, config, null);
+  }
+
+  close(): void {
+    this.storage.close();
+  }
+}