@smyslenny/agent-memory 5.0.2 → 5.1.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 5.1.0 (2026-03-20)
+
+### ✨ Features
+
+#### Archive on Eviction (淘汰归档)
+
+- Memories evicted by governance are now **archived** to `memory_archive` instead
+  of permanently deleted. Only memories with `vitality ≥ 0.1` are archived;
+  lower-vitality memories (decayed noise) are still directly deleted.
+- New schema v8: adds `memory_archive` table (migration `v7 → v8` runs
+  automatically on startup).
+- New core functions: `archiveMemory()`, `restoreMemory()`, `listArchivedMemories()`,
+  `purgeArchive()`.
+- New MCP tool **`archive`**: `list` / `restore` / `purge` actions for managing
+  archived memories.
+- `GovernResult` now includes `archived` (count of memories actually written to
+  the archive table) and `evictedByType` breakdown.
+
+#### Tiered Capacity (分层容量)
+
+- Governance now enforces **per-type capacity limits** before the global cap.
+  Defaults: `identity: unlimited`, `emotion: 50`, `knowledge: 250`, `event: 50`,
+  `total: 350`.
+- Configurable via environment variables: `AGENT_MEMORY_MAX_IDENTITY`,
+  `AGENT_MEMORY_MAX_EMOTION`, `AGENT_MEMORY_MAX_KNOWLEDGE`,
+  `AGENT_MEMORY_MAX_EVENT`, `AGENT_MEMORY_MAX_MEMORIES`.
+- `status` MCP tool now returns a `capacity` object showing per-type counts and
+  limits.
+- Identity memories (P0) are **never evicted** unless an explicit
+  `AGENT_MEMORY_MAX_IDENTITY` is set.
+
+### ♻️ Notes
+
+- Tidy phase (`runTidy`) still deletes low-vitality memories directly — no
+  archiving. Only govern-phase evictions (capacity-based) go to the archive.
+- All new parameters have defaults; upgrading from 5.0.x requires no config
+  changes. Schema migration is automatic.
+
 ## 5.0.1 (2026-03-20)
 
 ### 🐛 Fixes
@@ -18,7 +56,7 @@
 v5 is a major feature release that adds six intelligence capabilities to the
 memory layer. All features are backward-compatible with v4 workflows.
 
-Design document: `docs/design/0018-v5-memory-intelligence.md`
+Design document: see the v5 feature table in [README.md](README.md).
 
 #### F1: Memory Links (记忆关联)
 

package/README.md

@@ -22,7 +22,7 @@ AgentMemory is a SQLite-first memory layer for AI agents. It lets an agent:
 - **maintain** them over time with `reflect`, `reindex`, and feedback signals
 - **integrate** through **CLI**, **MCP stdio**, or **HTTP/SSE**
 
-Current release: **`5.0.1`**.
+Current release: **`5.0.2`**.
 
 Without an embedding provider, AgentMemory still works in **BM25-only mode**.
 With one configured, it adds **hybrid recall** and **semantic dedup**.

package/dist/bin/agent-memory.js

@@ -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 = [];
@@ -3003,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
@@ -3019,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
@@ -3272,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
   };
 }