@smyslenny/agent-memory 5.0.1 → 5.1.0

package/dist/bin/agent-memory.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// AgentMemory v2 — Sleep-cycle memory for AI agents
+// AgentMemory — Sleep-cycle memory for AI agents
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __esm = (fn, res) => function __init() {
@@ -100,6 +100,11 @@ function migrateDatabase(db, from, to) {
       v = 7;
       continue;
     }
+    if (v === 7) {
+      migrateV7ToV8(db);
+      v = 8;
+      continue;
+    }
     throw new Error(`Unsupported schema migration path: v${from} \u2192 v${to} (stuck at v${v})`);
   }
 }
@@ -187,6 +192,8 @@ function inferSchemaVersion(db) {
   const hasFeedbackEvents = tableExists(db, "feedback_events");
   const hasEmotionTag = tableHasColumn(db, "memories", "emotion_tag");
   const hasProvenance = tableHasColumn(db, "memories", "source_session") && tableHasColumn(db, "memories", "source_context") && tableHasColumn(db, "memories", "observed_at");
+  const hasMemoryArchive = tableExists(db, "memory_archive");
+  if (hasAgentScopedPaths && hasAgentScopedLinks && hasV4Embeddings && hasMaintenanceJobs && hasFeedbackEvents && hasEmotionTag && hasProvenance && hasMemoryArchive) return 8;
   if (hasAgentScopedPaths && hasAgentScopedLinks && hasV4Embeddings && hasMaintenanceJobs && hasFeedbackEvents && hasEmotionTag && hasProvenance) return 7;
   if (hasAgentScopedPaths && hasAgentScopedLinks && hasV4Embeddings && hasMaintenanceJobs && hasFeedbackEvents && hasEmotionTag) return 6;
   if (hasAgentScopedPaths && hasAgentScopedLinks && hasV4Embeddings && hasMaintenanceJobs && hasFeedbackEvents) return 5;
@@ -228,6 +235,11 @@ function ensureIndexes(db) {
       db.exec("CREATE INDEX IF NOT EXISTS idx_feedback_events_agent_source ON feedback_events(agent_id, source, created_at DESC);");
     }
   }
+  if (tableExists(db, "memory_archive")) {
+    db.exec("CREATE INDEX IF NOT EXISTS idx_memory_archive_agent ON memory_archive(agent_id);");
+    db.exec("CREATE INDEX IF NOT EXISTS idx_memory_archive_type ON memory_archive(type);");
+    db.exec("CREATE INDEX IF NOT EXISTS idx_memory_archive_archived_at ON memory_archive(archived_at);");
+  }
 }
 function ensureFeedbackEventSchema(db) {
   if (!tableExists(db, "feedback_events")) return;
@@ -403,11 +415,55 @@ function migrateV6ToV7(db) {
     throw e;
   }
 }
+function migrateV7ToV8(db) {
+  if (tableExists(db, "memory_archive")) {
+    db.prepare("INSERT OR REPLACE INTO schema_meta (key, value) VALUES ('version', ?)").run(String(8));
+    return;
+  }
+  try {
+    db.exec("BEGIN");
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS memory_archive (
+        id             TEXT PRIMARY KEY,
+        content        TEXT NOT NULL,
+        type           TEXT NOT NULL,
+        priority       INTEGER NOT NULL,
+        emotion_val    REAL NOT NULL DEFAULT 0.0,
+        vitality       REAL NOT NULL DEFAULT 0.0,
+        stability      REAL NOT NULL DEFAULT 1.0,
+        access_count   INTEGER NOT NULL DEFAULT 0,
+        last_accessed  TEXT,
+        created_at     TEXT NOT NULL,
+        updated_at     TEXT NOT NULL,
+        archived_at    TEXT NOT NULL,
+        archive_reason TEXT NOT NULL DEFAULT 'eviction',
+        source         TEXT,
+        agent_id       TEXT NOT NULL DEFAULT 'default',
+        hash           TEXT,
+        emotion_tag    TEXT,
+        source_session TEXT,
+        source_context TEXT,
+        observed_at    TEXT
+      );
+    `);
+    db.exec("CREATE INDEX IF NOT EXISTS idx_memory_archive_agent ON memory_archive(agent_id);");
+    db.exec("CREATE INDEX IF NOT EXISTS idx_memory_archive_type ON memory_archive(type);");
+    db.exec("CREATE INDEX IF NOT EXISTS idx_memory_archive_archived_at ON memory_archive(archived_at);");
+    db.prepare("INSERT OR REPLACE INTO schema_meta (key, value) VALUES ('version', ?)").run(String(8));
+    db.exec("COMMIT");
+  } catch (e) {
+    try {
+      db.exec("ROLLBACK");
+    } catch {
+    }
+    throw e;
+  }
+}
 var SCHEMA_VERSION, SCHEMA_SQL;
 var init_db = __esm({
   "src/core/db.ts"() {
     "use strict";
-    SCHEMA_VERSION = 7;
+    SCHEMA_VERSION = 8;
     SCHEMA_SQL = `
 -- Memory entries
 CREATE TABLE IF NOT EXISTS memories (
@@ -513,6 +569,30 @@ CREATE TABLE IF NOT EXISTS schema_meta (
   value TEXT NOT NULL
 );
 
+-- Memory archive (eviction archive)
+CREATE TABLE IF NOT EXISTS memory_archive (
+  id             TEXT PRIMARY KEY,
+  content        TEXT NOT NULL,
+  type           TEXT NOT NULL,
+  priority       INTEGER NOT NULL,
+  emotion_val    REAL NOT NULL DEFAULT 0.0,
+  vitality       REAL NOT NULL DEFAULT 0.0,
+  stability      REAL NOT NULL DEFAULT 1.0,
+  access_count   INTEGER NOT NULL DEFAULT 0,
+  last_accessed  TEXT,
+  created_at     TEXT NOT NULL,
+  updated_at     TEXT NOT NULL,
+  archived_at    TEXT NOT NULL,
+  archive_reason TEXT NOT NULL DEFAULT 'eviction',
+  source         TEXT,
+  agent_id       TEXT NOT NULL DEFAULT 'default',
+  hash           TEXT,
+  emotion_tag    TEXT,
+  source_session TEXT,
+  source_context TEXT,
+  observed_at    TEXT
+);
+
 -- Indexes for common queries
 CREATE INDEX IF NOT EXISTS idx_memories_type ON memories(type);
 CREATE INDEX IF NOT EXISTS idx_memories_priority ON memories(priority);
@@ -523,6 +603,9 @@ CREATE INDEX IF NOT EXISTS idx_paths_memory ON paths(memory_id);
 CREATE INDEX IF NOT EXISTS idx_paths_domain ON paths(domain);
 CREATE INDEX IF NOT EXISTS idx_maintenance_jobs_phase_status ON maintenance_jobs(phase, status, started_at DESC);
 CREATE INDEX IF NOT EXISTS idx_feedback_events_memory ON feedback_events(memory_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_memory_archive_agent ON memory_archive(agent_id);
+CREATE INDEX IF NOT EXISTS idx_memory_archive_type ON memory_archive(type);
+CREATE INDEX IF NOT EXISTS idx_memory_archive_archived_at ON memory_archive(archived_at);
 `;
   }
 });
@@ -1152,9 +1235,54 @@ function updateMemory(db, id, input) {
 }
 function deleteMemory(db, id) {
   db.prepare("DELETE FROM memories_fts WHERE id = ?").run(id);
+  try {
+    db.prepare("DELETE FROM embeddings WHERE memory_id = ?").run(id);
+  } catch {
+  }
   const result = db.prepare("DELETE FROM memories WHERE id = ?").run(id);
   return result.changes > 0;
 }
+function archiveMemory(db, id, reason, opts) {
+  const mem = getMemory(db, id);
+  if (!mem) return false;
+  const minVitality = opts?.minVitality ?? 0.1;
+  if (mem.vitality < minVitality) {
+    deleteMemory(db, id);
+    return "deleted";
+  }
+  const archivedAt = now();
+  const archiveReason = reason ?? "eviction";
+  db.prepare(
+    `INSERT OR REPLACE INTO memory_archive
+     (id, content, type, priority, emotion_val, vitality, stability, access_count,
+      last_accessed, created_at, updated_at, archived_at, archive_reason,
+      source, agent_id, hash, emotion_tag, source_session, source_context, observed_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+  ).run(
+    mem.id,
+    mem.content,
+    mem.type,
+    mem.priority,
+    mem.emotion_val,
+    mem.vitality,
+    mem.stability,
+    mem.access_count,
+    mem.last_accessed,
+    mem.created_at,
+    mem.updated_at,
+    archivedAt,
+    archiveReason,
+    mem.source,
+    mem.agent_id,
+    mem.hash,
+    mem.emotion_tag,
+    mem.source_session,
+    mem.source_context,
+    mem.observed_at
+  );
+  deleteMemory(db, id);
+  return "archived";
+}
 function listMemories(db, opts) {
   const conditions = [];
   const params = [];
@@ -1649,21 +1777,20 @@ async function searchVectorBranch(db, query, opts) {
     before: opts.before
   });
 }
-function expandRelated(db, results, agentId, maxTotal) {
-  const existingIds = new Set(results.map((r) => r.memory.id));
+function fetchRelatedLinks(db, sourceIds, agentId, excludeIds, maxPerSource = 5) {
   const related = [];
-  for (const result of results) {
+  for (const sourceId of sourceIds) {
     const links = db.prepare(
       `SELECT l.target_id, l.weight, m.*
        FROM links l
        JOIN memories m ON m.id = l.target_id
        WHERE l.agent_id = ? AND l.source_id = ?
        ORDER BY l.weight DESC
-       LIMIT 5`
-    ).all(agentId, result.memory.id);
+       LIMIT ?`
+    ).all(agentId, sourceId, maxPerSource);
     for (const link of links) {
-      if (existingIds.has(link.target_id)) continue;
-      existingIds.add(link.target_id);
+      if (excludeIds.has(link.target_id)) continue;
+      excludeIds.add(link.target_id);
       const relatedMemory = {
         id: link.id,
         content: link.content,
@@ -1686,12 +1813,30 @@ function expandRelated(db, results, agentId, maxTotal) {
       };
       related.push({
         memory: relatedMemory,
-        score: result.score * link.weight * 0.6,
-        related_source_id: result.memory.id,
-        match_type: "related"
+        sourceId,
+        weight: link.weight
       });
     }
   }
+  return related;
+}
+function expandRelated(db, results, agentId, maxTotal) {
+  const existingIds = new Set(results.map((r) => r.memory.id));
+  const links = fetchRelatedLinks(
+    db,
+    results.map((r) => r.memory.id),
+    agentId,
+    existingIds
+  );
+  const related = links.map((link) => {
+    const sourceResult = results.find((r) => r.memory.id === link.sourceId);
+    return {
+      memory: link.memory,
+      score: (sourceResult?.score ?? 0) * link.weight * 0.6,
+      related_source_id: link.sourceId,
+      match_type: "related"
+    };
+  });
   const directResults = results.map((r) => ({
     ...r,
     match_type: "direct"
@@ -2192,7 +2337,8 @@ async function surfaceMemories(db, input) {
       }),
       lexical_rank: signal.queryRank ?? signal.recentRank ?? signal.taskRank,
       semantic_rank: signal.semanticRank,
-      semantic_similarity: signal.semanticSimilarity
+      semantic_similarity: signal.semanticSimilarity,
+      match_type: "direct"
     };
   }).sort((left, right) => {
     if (right.score !== left.score) return right.score - left.score;
@@ -2201,6 +2347,42 @@ async function surfaceMemories(db, input) {
     if (left.memory.priority !== right.memory.priority) return left.memory.priority - right.memory.priority;
     return right.memory.updated_at.localeCompare(left.memory.updated_at);
   }).slice(0, limit);
+  if (input.related) {
+    const existingIds = new Set(results.map((r) => r.memory.id));
+    const links = fetchRelatedLinks(
+      db,
+      results.map((r) => r.memory.id),
+      agentId,
+      existingIds
+    );
+    const relatedResults = links.map((link) => {
+      const sourceResult = results.find((r) => r.memory.id === link.sourceId);
+      const feedbackSummary = getFeedbackSummary(db, link.memory.id, agentId);
+      return {
+        memory: link.memory,
+        score: (sourceResult?.score ?? 0) * link.weight * 0.6,
+        semantic_score: 0,
+        lexical_score: 0,
+        task_match: 0,
+        vitality: link.memory.vitality,
+        priority_prior: priorityPrior(link.memory.priority),
+        feedback_score: feedbackSummary.score,
+        feedback_summary: feedbackSummary,
+        reason_codes: [`type:${link.memory.type}`, "related"],
+        related_source_id: link.sourceId,
+        match_type: "related"
+      };
+    });
+    const maxTotal = Math.floor(limit * 1.5);
+    const combined = [...results, ...relatedResults].sort((a, b) => b.score - a.score).slice(0, maxTotal);
+    return {
+      count: combined.length,
+      query: trimmedQuery,
+      task: trimmedTask,
+      intent: input.intent,
+      results: combined
+    };
+  }
   return {
     count: results.length,
     query: trimmedQuery,
@@ -2949,13 +3131,31 @@ function rankEvictionCandidates(db, opts) {
     return left.memory.priority - right.memory.priority;
   });
 }
+function parseEnvInt(envKey) {
+  const raw = process.env[envKey];
+  if (raw === void 0 || raw === "") return null;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+function getTieredCapacity(opts) {
+  const envMax = parseEnvInt("AGENT_MEMORY_MAX_MEMORIES");
+  return {
+    identity: parseEnvInt("AGENT_MEMORY_MAX_IDENTITY"),
+    // default: null (unlimited)
+    emotion: parseEnvInt("AGENT_MEMORY_MAX_EMOTION") ?? 50,
+    knowledge: parseEnvInt("AGENT_MEMORY_MAX_KNOWLEDGE") ?? 250,
+    event: parseEnvInt("AGENT_MEMORY_MAX_EVENT") ?? 50,
+    total: opts?.maxMemories ?? (envMax ?? 350)
+  };
+}
 function runGovern(db, opts) {
   const agentId = opts?.agent_id;
-  const envMax = Number.parseInt(process.env.AGENT_MEMORY_MAX_MEMORIES ?? "", 10);
-  const maxMemories = opts?.maxMemories ?? (Number.isFinite(envMax) && envMax > 0 ? envMax : 200);
+  const capacity = getTieredCapacity(opts);
   let orphanPaths = 0;
   let emptyMemories = 0;
   let evicted = 0;
+  let archived = 0;
+  const evictedByType = {};
   const transaction = db.transaction(() => {
     const pathResult = agentId ? db.prepare(
       `DELETE FROM paths
@@ -2965,17 +3165,48 @@ function runGovern(db, opts) {
     orphanPaths = pathResult.changes;
     const emptyResult = agentId ? db.prepare("DELETE FROM memories WHERE agent_id = ? AND TRIM(content) = ''").run(agentId) : db.prepare("DELETE FROM memories WHERE TRIM(content) = ''").run();
     emptyMemories = emptyResult.changes;
+    const typeLimits = [
+      { type: "identity", limit: capacity.identity },
+      { type: "emotion", limit: capacity.emotion },
+      { type: "knowledge", limit: capacity.knowledge },
+      { type: "event", limit: capacity.event }
+    ];
+    const allCandidates = rankEvictionCandidates(db, { agent_id: agentId });
+    const evictedIds = /* @__PURE__ */ new Set();
+    for (const { type, limit } of typeLimits) {
+      if (limit === null) continue;
+      const typeCount = db.prepare(
+        agentId ? "SELECT COUNT(*) as c FROM memories WHERE agent_id = ? AND type = ?" : "SELECT COUNT(*) as c FROM memories WHERE type = ?"
+      ).get(...agentId ? [agentId, type] : [type]).c;
+      const excess = Math.max(0, typeCount - limit);
+      if (excess <= 0) continue;
+      const typeCandidates = allCandidates.filter((c) => c.memory.type === type && !evictedIds.has(c.memory.id));
+      const toEvict = typeCandidates.slice(0, excess);
+      for (const candidate of toEvict) {
+        const result = archiveMemory(db, candidate.memory.id, "eviction");
+        evictedIds.add(candidate.memory.id);
+        evicted += 1;
+        if (result === "archived") archived += 1;
+        evictedByType[type] = (evictedByType[type] ?? 0) + 1;
+      }
+    }
     const total = db.prepare(agentId ? "SELECT COUNT(*) as c FROM memories WHERE agent_id = ?" : "SELECT COUNT(*) as c FROM memories").get(...agentId ? [agentId] : []).c;
-    const excess = Math.max(0, total - maxMemories);
-    if (excess <= 0) return;
-    const candidates = rankEvictionCandidates(db, { agent_id: agentId }).slice(0, excess);
-    for (const candidate of candidates) {
-      deleteMemory(db, candidate.memory.id);
-      evicted += 1;
+    const globalExcess = Math.max(0, total - capacity.total);
+    if (globalExcess > 0) {
+      const globalCandidates = allCandidates.filter((c) => !evictedIds.has(c.memory.id));
+      const toEvict = globalCandidates.slice(0, globalExcess);
+      for (const candidate of toEvict) {
+        const result = archiveMemory(db, candidate.memory.id, "eviction");
+        evictedIds.add(candidate.memory.id);
+        evicted += 1;
+        if (result === "archived") archived += 1;
+        const t = candidate.memory.type;
+        evictedByType[t] = (evictedByType[t] ?? 0) + 1;
+      }
     }
   });
   transaction();
-  return { orphanPaths, emptyMemories, evicted };
+  return { orphanPaths, emptyMemories, evicted, archived, evictedByType };
 }
 
 // src/sleep/jobs.ts
@@ -3218,12 +3449,21 @@ function getMemoryStatus(db, input) {
   const feedbackEvents = db.prepare(
     "SELECT COUNT(*) as c FROM feedback_events WHERE agent_id = ?"
   ).get(agentId);
+  const tiered = getTieredCapacity();
+  const capacity = {
+    identity: { count: stats.by_type.identity ?? 0, limit: tiered.identity },
+    emotion: { count: stats.by_type.emotion ?? 0, limit: tiered.emotion },
+    knowledge: { count: stats.by_type.knowledge ?? 0, limit: tiered.knowledge },
+    event: { count: stats.by_type.event ?? 0, limit: tiered.event },
+    total: { count: stats.total, limit: tiered.total }
+  };
   return {
     ...stats,
     paths: totalPaths.c,
     low_vitality: lowVitality.c,
     feedback_events: feedbackEvents.c,
-    agent_id: agentId
+    agent_id: agentId,
+    capacity
   };
 }
 
@@ -3357,6 +3597,8 @@ function formatRecallResponse(result) {
       vector_rank: row.vector_rank,
       bm25_score: row.bm25_score,
       vector_score: row.vector_score,
+      related_source_id: row.related_source_id,
+      match_type: row.match_type,
       updated_at: row.memory.updated_at
     }))
   };
@@ -3381,6 +3623,8 @@ function formatSurfaceResponse(result) {
       feedback_score: row.feedback_score,
       feedback_summary: row.feedback_summary,
       reason_codes: row.reason_codes,
+      related_source_id: row.related_source_id,
+      match_type: row.match_type,
       updated_at: row.memory.updated_at
     }))
   };
@@ -3550,7 +3794,11 @@ function createHttpServer(options) {
           emotion_val: asNumber(body.emotion_val),
           agent_id: asString(body.agent_id) ?? defaultAgentId,
           conservative: asBoolean(body.conservative),
-          provider: options?.provider
+          provider: options?.provider,
+          emotion_tag: asString(body.emotion_tag),
+          source_session: asString(body.source_session),
+          source_context: asString(body.source_context),
+          observed_at: asString(body.observed_at)
         });
         sendJson(res, 200, result);
         return;
@@ -3565,7 +3813,12 @@ function createHttpServer(options) {
           query,
           limit: asNumber(body.limit),
           agent_id: asString(body.agent_id) ?? defaultAgentId,
-          provider: options?.provider
+          provider: options?.provider,
+          related: asBoolean(body.related),
+          after: asString(body.after),
+          before: asString(body.before),
+          recency_boost: asNumber(body.recency_boost),
+          emotion_tag: asString(body.emotion_tag)
         });
         sendJson(res, 200, formatRecallResponse(result));
         return;
@@ -3585,7 +3838,12 @@ function createHttpServer(options) {
           types,
           limit: asNumber(body.limit),
           agent_id: asString(body.agent_id) ?? defaultAgentId,
-          provider: options?.provider
+          provider: options?.provider,
+          related: asBoolean(body.related),
+          after: asString(body.after),
+          before: asString(body.before),
+          recency_boost: asNumber(body.recency_boost),
+          emotion_tag: asString(body.emotion_tag)
         });
         sendJson(res, 200, formatSurfaceResponse(result));
         return;
@@ -3719,7 +3977,7 @@ function getAgentId() {
 }
 function printHelp() {
   console.log(`
-\u{1F9E0} AgentMemory v4 \u2014 Sleep-cycle memory for AI agents
+\u{1F9E0} AgentMemory \u2014 Sleep-cycle memory for AI agents
 
 Usage: agent-memory <command> [options]