@smyslenny/agent-memory 5.0.1 → 5.1.0

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,158 @@
 # 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
+
+- **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: see the v5 feature table in [README.md](README.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.2`**.
 
 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)