@smyslenny/agent-memory 5.0.0 → 5.0.2

package/.github/workflows/test.yml

@@ -10,7 +10,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node: [18, 20, 22]
+        node: [18, 20, 22, 24]
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4

package/.pnpm-approve-builds.json

@@ -0,0 +1 @@
+{"better-sqlite3@11.10.0": true, "esbuild@0.27.4": true}

package/CHANGELOG.md

@@ -1,5 +1,120 @@
 # Changelog
 
+## 5.0.1 (2026-03-20)
+
+### 🐛 Fixes
+
+- **auto-ingest**: Daily log files (`YYYY-MM-DD.md`) are now skipped by default.
+  Only `MEMORY.md` (curated memory) is watched and ingested. Daily logs are raw
+  journals that often contain noise — they should be processed through the
+  memory-sync cron pipeline instead.
+- New environment variable `AGENT_MEMORY_AUTO_INGEST_DAILY=1` restores the
+  previous behavior of ingesting all `.md` files in the `memory/` directory.
+
+## 5.0.0 (2026-03-20)
+
+### 🧠 Memory Intelligence
+
+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`
+
+#### F1: Memory Links (记忆关联)
+
+- Automatic link creation during `syncOne()`: after a successful `add` or
+  `merge`, candidates with `dedup_score ∈ [0.45, 0.82)` are saved as `related`
+  links (up to 5 per memory)
+- `recall` and `surface` accept a new `related: boolean` parameter. When true,
+  top-K results are expanded with linked memories from the `links` table
+  (capped at `limit * 1.5`, with score scaled by `original_score * link_weight * 0.6`)
+- Related memories are tagged with `match_type: 'related'` and
+  `related_source_id` in results so the agent knows why they appeared
+- New MCP tool **`link`**: manually create or remove associations
+  (`relation`: `related` | `supersedes` | `contradicts`, with optional `weight`)
+
+#### F2: Conflict Detection (冲突检测)
+
+- Write Guard (`guard.ts`) now iterates over multiple candidates instead of
+  only the top-1 match
+- Three conflict signal types detected between incoming content and existing
+  candidates:
+  - **Negation**: one side contains negation words the other does not
+  - **Value**: same entity with different numeric values (IPs, ports, versions)
+  - **Status**: one side marked done/cancelled while the other is in-progress
+- Conflict score (0–1) is computed from weighted signals. Conflicts above 0.5
+  are reported in `GuardResult.conflicts` and propagated to `SyncResult`
+- **Conflict Override rule**: when `dedup_score ≥ 0.93` and a `status` or
+  `value` conflict is detected, the guard action is forced from `skip` to
+  `update` — preventing legitimate state changes (e.g. TODO → DONE) from being
+  silently deduplicated. `negation` conflicts do not trigger override (higher
+  false-positive rate)
+- Writes are never blocked by conflict detection — the agent decides what to do
+
+#### F3: Temporal Recall (时间维度召回)
+
+- `recall` and `surface` accept new optional parameters:
+  - `after` / `before` (ISO 8601) — time-range filter at the SQL layer for
+    both BM25 and vector search paths
+  - `recency_boost` (0–1) — blends a recency decay signal into the fusion
+    score: `final = (1 - boost) * base + boost * e^(-days/30)`
+- BM25 and vector search functions (`searchBM25`, `searchByVector`) extended
+  with `after` / `before` filter support
+
+#### F4: Passive Feedback (被动反馈)
+
+- `FeedbackSource` type extended to `"recall" | "surface" | "passive"`
+- When `recall` records access, the top-3 results automatically receive a
+  positive passive feedback event (value 0.7, vs 1.0 for explicit feedback)
+- Rate-limited: max 3 passive feedback events per memory per 24-hour window
+- Anti-N+1: deduplication check uses a single batch `WHERE memory_id IN (...)`
+  query instead of per-memory `SELECT COUNT(*)`
+
+#### F5: Semantic Decay (语义衰减)
+
+- New `isStaleContent(content, type)` function in `tidy.ts` detects
+  temporally-stale content via keyword pattern matching
+- Pattern sets are scoped by memory type:
+  - `event`: broad matching (e.g. `正在`, `in progress`, `TODO`, `just now`)
+  - `knowledge`: anchored-start-only patterns (e.g. `^TODO:`, `^WIP:`) to
+    avoid false positives on knowledge descriptions containing those words
+  - `identity` and `emotion`: exempt from semantic decay
+- Age thresholds: `in_progress` > 7d, `pending` > 14d, `ephemeral` > 3d
+- Matched memories have their `vitality` multiplied by the pattern's
+  `decay_factor`
+- `TidyResult` now includes `staleDecayed` count
+
+#### F6: Memory Provenance (记忆溯源)
+
+- Schema migration v6 → v7: three new nullable columns on `memories`:
+  - `source_session` — originating session ID
+  - `source_context` — trigger context (≤200 chars)
+  - `observed_at` — when the event actually happened (distinct from write time)
+- `Memory` interface and `CreateMemoryInput` updated with provenance fields
+- MCP `remember` tool accepts `session_id`, `context`, `observed_at`
+- `recall` / `surface` results include provenance fields when present
+- `guard.ts` `timeProximity()` now prefers `observed_at` over regex-guessed
+  timestamps from content/URI/source
+
+### 🧰 Tooling
+
+- MCP toolset expanded from **10 → 11 tools** (added `link`)
+- MCP server version string updated to `5.0.0`
+
+### ✅ Tests
+
+- Added `tests/v5/intelligence.test.ts` with **25 new test cases** covering
+  all six v5 features
+- Total test count: **96** (up from 69 in v4.2)
+
+### 📦 Schema
+
+- Database schema version: **7** (from 6)
+- Migration is additive (nullable columns only) — safe to upgrade in place
+- Rollback: ignore new columns, delete new link/feedback rows by type
+
+---
+
 ## 4.2.0 (2026-03-19)
 
 ### 🛡️ Anti-Noise Hardening

package/README.md

@@ -10,7 +10,7 @@
   <a href="https://www.npmjs.com/package/@smyslenny/agent-memory"><img src="https://img.shields.io/npm/v/@smyslenny/agent-memory" alt="npm" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
   <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%E2%89%A518-green.svg" alt="Node.js" /></a>
-  <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-10_tools-orange.svg" alt="MCP" /></a>
+  <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-11_tools-orange.svg" alt="MCP" /></a>
 </p>
 
 **English** | [简体中文说明](docs/README-zh.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: **`4.3.0`**.
+Current release: **`5.0.1`**.
 
 Without an embedding provider, AgentMemory still works in **BM25-only mode**.
 With one configured, it adds **hybrid recall** and **semantic dedup**.
@@ -40,16 +40,36 @@ That means it is designed around the things agent runtimes actually need:
 - a lifecycle path for decay, governance, reindexing, and recovery-friendly jobs
 - a local-first deployment model that stays useful even without extra infra
 
-Core building blocks in v4:
+Core building blocks:
 
 - **Typed memories**: `identity`, `emotion`, `knowledge`, `event`
 - **URI paths** for stable addressing
-- **Write Guard** with semantic dedup + typed merge policy
+- **Write Guard** with semantic dedup + typed merge policy + conflict detection
 - **Hybrid retrieval**: BM25 first, optional vector search
+- **Memory links** with automatic association and related-memory expansion
+- **Temporal recall** with time filtering and recency boost
 - **Context-aware surfacing** for task/recent-turn driven context injection
+- **Passive feedback** that records usage signals automatically
+- **Semantic decay** that detects stale content beyond pure time-based Ebbinghaus
+- **Memory provenance** for tracking where and when each memory originated
 - **Lifecycle jobs**: `reflect`, `reindex`, job checkpoints, feedback signals
 - **Three transport modes**: CLI, MCP stdio, HTTP/SSE
 
+### New in v5: Memory Intelligence
+
+v5 adds six features that turn agent-memory from a durable store into an
+intelligent memory layer. All features are backward-compatible — existing
+v4 workflows continue to work unchanged.
+
+| Feature | What it does |
+| --- | --- |
+| **F1 Memory Links** | Automatically detects semantically related memories during write and builds lightweight associations. `recall` and `surface` support `related` expansion to pull in linked memories. A new `link` tool allows manual link management. |
+| **F2 Conflict Detection** | Write Guard now scans candidates for contradictions (negation, value changes, status changes). Conflicts are reported in the sync result without blocking writes. A **Conflict Override** rule ensures status updates (e.g. TODO → DONE) are not incorrectly deduplicated. |
+| **F3 Temporal Recall** | `recall` and `surface` accept `after`, `before`, and `recency_boost` parameters. Time filtering happens at the SQL layer for both BM25 and vector paths. Recency boost blends a time-decay signal into the fusion score. |
+| **F4 Passive Feedback** | When `recall` returns results and records access, positive feedback is automatically logged for the top-3 hits. Rate-limited to 3 passive events per memory per 24 hours. |
+| **F5 Semantic Decay** | The `tidy` phase now detects stale content through keyword pattern matching (e.g. "in progress", "TODO:", "just now"). Patterns are scoped by memory type — `event` uses broad matching, `knowledge` uses anchored-start-only patterns. `identity` and `emotion` are exempt. |
+| **F6 Memory Provenance** | Memories can carry `source_session`, `source_context`, and `observed_at` metadata. This tracks where and when a memory originated, separate from its write timestamp. Schema migrated from v6 → v7. |
+
 ## 2) How is it different from a vector DB, a RAG pipeline, or memory summaries?
 
 | Thing | Good at | What AgentMemory adds |
@@ -177,18 +197,19 @@ npx agent-memory reflect all
 }
 ```
 
-Available MCP tools in v4:
+Available MCP tools:
 
-- `remember`
-- `recall`
-- `recall_path`
-- `boot`
-- `forget`
-- `reflect`
-- `status`
-- `ingest`
-- `reindex`
-- `surface`
+- `remember` — store a memory (supports provenance: `session_id`, `context`, `observed_at`)
+- `recall` — hybrid search (supports `related`, `after`, `before`, `recency_boost`)
+- `recall_path` — read or list memories by URI
+- `boot` — load startup memories (narrative or JSON)
+- `forget` — soft-decay or hard-delete a memory
+- `reflect` — run sleep cycle phases (decay, tidy, govern)
+- `status` — memory system statistics
+- `ingest` — extract structured memories from markdown
+- `reindex` — rebuild BM25 index and optional embeddings
+- `surface` — context-aware readonly surfacing (supports `related`, `after`, `before`, `recency_boost`)
+- `link` — manually create or remove associations between memories
 
 ### C. HTTP API
 
@@ -274,6 +295,22 @@ export AGENT_MEMORY_EMBEDDING_API_KEY=your-api-key
 Or use `AGENT_MEMORY_EMBEDDING_PROVIDER=local-http` for a local HTTP embedding
 service. If no provider is configured, AgentMemory falls back to BM25-only.
 
+## Environment variables
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `AGENT_MEMORY_DB` | `./agent-memory.db` | SQLite database path |
+| `AGENT_MEMORY_AGENT_ID` | `default` | Agent scope for multi-agent setups |
+| `AGENT_MEMORY_MAX_MEMORIES` | `200` | Maximum memories retained during `reflect govern` |
+| `AGENT_MEMORY_AUTO_INGEST` | `1` | Set to `0` to disable the auto-ingest file watcher |
+| `AGENT_MEMORY_AUTO_INGEST_DAILY` | _(unset)_ | Set to `1` to include daily log files (`YYYY-MM-DD.md`) in auto-ingest. By default, only `MEMORY.md` is watched. |
+| `AGENT_MEMORY_WORKSPACE` | `~/.openclaw/workspace` | Workspace directory for the auto-ingest watcher |
+| `AGENT_MEMORY_EMBEDDING_PROVIDER` | _(unset)_ | `openai-compatible` or `local-http` |
+| `AGENT_MEMORY_EMBEDDING_BASE_URL` | _(unset)_ | Base URL for the embedding endpoint |
+| `AGENT_MEMORY_EMBEDDING_MODEL` | _(unset)_ | Embedding model name |
+| `AGENT_MEMORY_EMBEDDING_DIMENSION` | _(unset)_ | Embedding vector dimension |
+| `AGENT_MEMORY_EMBEDDING_API_KEY` | _(unset)_ | API key for the embedding provider |
+
 ## Documentation map
 
 - [Architecture](docs/architecture.md)

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() {
@@ -1649,21 +1649,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 +1685,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 +2209,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 +2219,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,
@@ -3357,6 +3411,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 +3437,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 +3608,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 +3627,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 +3652,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 +3791,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]