@smyslenny/agent-memory 2.2.0 → 3.1.0

package/CHANGELOG.md

@@ -1,57 +1,61 @@
 # Changelog
 
-## 2.1.2 (2026-02-22)
+## 3.0.1 (2026-02-24)
 
-### 🔗 OpenClaw Integration V1 (Cron Synchronization)
+### 🛠️ OpenClaw P0 fixes
 
-- **Capture → Consolidate → Surface closed loop** — agent-memory now integrates seamlessly with OpenClaw's built-in memory cron jobs (`memory-sync`, `memory-tidy`, `memory-surface`) with zero code changes ([DD-0004](docs/design/0004-agent-memory-integration.md))
-- **memory-sync** (14:00 & 22:00): Each new journal bullet is auto-synced to agent-memory via `mcporter call agent-memory.remember` with keyword-based type classification and URI dedup
-- **memory-tidy** (03:00): Triggers `agent-memory.reflect phase=all` (Ebbinghaus decay + tidy + govern) after Markdown consolidation, with consistency spot-check
-- **memory-surface** (14:05 & 22:05): Generates structured `RECENT.md` (≤80 lines) from high-vitality agent-memory entries, with fallback to raw journal reading
-- **Design principle**: Markdown remains source of truth; agent-memory is a derived index layer with best-effort sync
-- **README updated** with full OpenClaw Integration guide
+- **Fixed memory-sync session path mismatch** in cron prompt:
+  - removed hardcoded `~/.openclaw/agents/main/sessions/*.jsonl`
+  - switched to dynamic discovery with `noah` + env-derived agent path + `main` fallback
+- **Aligned memory-tidy prompt** with the same session path health check strategy
+- **Added memory-sync health output contract**:
+  - `session_scan_glob`
+  - `session_file_count`
+  - `latest_session_file`
+  - `extracted_message_count`
+  - `appended_bullet_count`
+  - `synced_memory_count`
+  - `sync_error_count`
 
-## 2.1.1 (2026-02-21)
+### ✨ Auto-ingest watcher implemented
 
-### 📝 Documentation
+- Added `fs.watch`-based auto-ingest watcher for:
+  - `~/.openclaw/workspace/memory/*.md`
+  - `~/.openclaw/workspace/MEMORY.md`
+- New module: `src/ingest/watcher.ts`
+- MCP server now starts watcher by default (configurable):
+  - `AGENT_MEMORY_AUTO_INGEST=0` to disable
+  - `AGENT_MEMORY_WORKSPACE` to override workspace path
 
-- **Memory-janitor integration guide** — New `examples/openclaw-setup.md` section explaining what a memory janitor is and how to wire it to agent-memory (decay trigger + consistency check) ([PR #2](https://github.com/smysle/agent-memory/pull/2))
-- **Phase 5 prompt template** — New `examples/memory-janitor-phase5.md` with full prompt template for appending decay + consistency phases to an existing janitor cron job
-- Covers Gap 1 (Ebbinghaus decay never fires without external trigger) and Gap 2 (two-store divergence between agent-memory and canonical memory files)
-- Includes configurable conflict resolution strategies (canonical wins / agent-memory wins / manual review)
+### 🧱 Ingest refactor + tests
 
-## 2.0.0 (2026-02-20)
+- Extracted ingest core logic from MCP server into reusable module:
+  - `src/ingest/ingest.ts`
+- MCP `ingest` tool now delegates to shared `ingestText()`
+- Added ingest tests:
+  - dry-run extraction does not write DB
+  - source marker stored as `auto:{source}`
 
-### 🎉 Complete Rewrite
+### 📚 Documentation realigned to v3 reality
 
-AgentMemory v2 is a ground-up rewrite incorporating the best ideas from 4 open-source memory projects (nocturne_memory, Memory Palace, PowerMem, our v1) while keeping the codebase minimal (3 dependencies).
+- Rewrote `README.md` and `README.en.md` to match actual v3 capabilities
+- Removed stale v2-era claims (embedding/reranker/link/snapshot/hybrid stack narrative)
+- Added explicit auto-ingest watcher behavior and env vars
 
-### ✨ New Features
+---
 
-- **URI Path System** — `core://`, `emotion://`, `knowledge://`, `event://` namespaces with Content-Path separation
-- **Write Guard** — Hash dedup → URI conflict → BM25 similarity → 4-criterion gate pipeline
-- **Ebbinghaus Forgetting Curve** — Scientific decay model `R = e^(-t/S)` with recall strengthening
-- **Knowledge Graph** — Association links with multi-hop BFS traversal
-- **Snapshot/Rollback** — Auto-snapshot before every modification, one-click restore
-- **Intent-Aware Search** — Factual / temporal / causal / exploratory query classification
-- **Sleep Cycle Engine** — Automated sync → decay → tidy → govern pipeline
-- **Priority System** — P0 identity (never decays) through P3 event (14-day half-life)
-- **Multi-Agent Isolation** — Per-agent memory scoping via `agent_id`
-- **MCP Server** — 9 tools for Claude Code / Cursor / OpenClaw integration
-- **CLI** — 7 commands: init, remember, recall, boot, status, reflect, migrate
-- **Markdown Migration** — Import existing MEMORY.md + daily journals + weekly summaries
+## 3.0.0 (2026-02-23)
 
-### 📊 Stats
+### 🎉 v3 Simplification
 
-- 14 source modules
-- 9 MCP tools
-- 7 CLI commands
-- 41 tests passing
-- 3 production dependencies
+- Repositioned agent-memory as a structured companion to memory-core
+- Removed redundant v2 capabilities at API/tooling level
+- MCP toolset finalized at 9 tools:
+  - `remember`, `recall`, `recall_path`, `boot`, `forget`, `reflect`, `status`, `ingest`, `surface`
+- Added narrative warm-boot and human-readable reflect report
 
-### 🙏 Inspired By
+---
 
-- [nocturne_memory](https://github.com/Dataojitori/nocturne_memory) — URI paths, Content-Path separation, boot loading
-- [Memory Palace](https://github.com/AGI-is-going-to-arrive/Memory-Palace) — Write Guard, intent search, vitality decay
-- [PowerMem](https://github.com/oceanbase/powermem) — Ebbinghaus curve, knowledge graph, multi-agent
-- Our v1 production experience — Sleep cycle, dedup, 4-criterion gate, emotional priority
+## 2.x (legacy)
+
+v2.x included embedding/reranker/link/snapshot-era behavior. See git history and design docs for full details.

package/README.en.md

@@ -0,0 +1,153 @@
+# 🧠 AgentMemory v3
+
+> Structured long-term memory layer for AI agents: write, recall, decay, and auto-ingest.
+
+[![npm](https://img.shields.io/npm/v/@smyslenny/agent-memory)](https://www.npmjs.com/package/@smyslenny/agent-memory)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-≥18-green.svg)](https://nodejs.org/)
+[![MCP](https://img.shields.io/badge/MCP-9_tools-orange.svg)](https://modelcontextprotocol.io/)
+
+**[简体中文](README.md)** | **English**
+
+---
+
+## Positioning in v3
+
+AgentMemory v3 is explicitly a **structured memory companion** to OpenClaw memory-core, not a second full-stack retrieval system.
+
+- Markdown (`memory/*.md` + `MEMORY.md`) remains the human-readable source of truth
+- agent-memory is a derived, structured lifecycle layer
+
+Core capabilities:
+
+- **Typed memory model**: `identity / emotion / knowledge / event`
+- **URI path addressing**: `core://`, `emotion://`, `knowledge://`, `event://`
+- **Write Guard** for dedup/conflict gating
+- **BM25 recall** with priority × vitality weighting
+- **Sleep-cycle maintenance** via `reflect` (decay / tidy / govern)
+- **Ingest** for markdown-to-memory extraction
+- **Surface** for readonly context surfacing (no access side effects)
+- **Warm boot / reflect narrative output**
+- **Multi-agent isolation** by `agent_id`
+
+---
+
+## Quick Start
+
+### Install
+
+```bash
+npm install -g @smyslenny/agent-memory
+```
+
+### CLI examples
+
+```bash
+# Initialize DB
+agent-memory init
+
+# Store memory
+agent-memory remember "User prefers dark mode" --type knowledge --uri knowledge://preferences/theme
+
+# Search
+agent-memory recall "user preferences" --limit 5
+
+# Startup boot (narrative output)
+agent-memory boot
+
+# Run sleep cycle
+agent-memory reflect all
+```
+
+---
+
+## MCP Server
+
+### Example config
+
+```json
+{
+  "mcpServers": {
+    "agent-memory": {
+      "command": "node",
+      "args": ["node_modules/@smyslenny/agent-memory/dist/mcp/server.js"],
+      "env": {
+        "AGENT_MEMORY_DB": "./agent-memory.db",
+        "AGENT_MEMORY_AGENT_ID": "noah",
+        "AGENT_MEMORY_AUTO_INGEST": "1",
+        "AGENT_MEMORY_WORKSPACE": "/home/user/.openclaw/workspace"
+      }
+    }
+  }
+}
+```
+
+### MCP tools (9)
+
+- `remember`
+- `recall`
+- `recall_path`
+- `boot`
+- `forget`
+- `reflect`
+- `status`
+- `ingest`
+- `surface`
+
+> `link` and `snapshot` were removed in v3.
+
+---
+
+## Auto-Ingest (file change watcher)
+
+When MCP server starts, watcher is enabled by default (`fs.watch`) for:
+
+- `~/.openclaw/workspace/memory/*.md`
+- `~/.openclaw/workspace/MEMORY.md`
+
+On file changes, ingest runs automatically (still guarded by Write Guard and dedup).
+
+Environment variables:
+
+- `AGENT_MEMORY_AUTO_INGEST`
+  - `1` (default): enabled
+  - `0`: disabled
+- `AGENT_MEMORY_WORKSPACE`
+  - default: `$HOME/.openclaw/workspace`
+
+---
+
+## Recommended OpenClaw integration
+
+Use a 3-stage cron pipeline:
+
+1. `memory-sync` (14:00 / 22:00)
+   - dynamic session JSONL discovery
+   - append incremental entries to `memory/YYYY-MM-DD.md`
+   - best-effort `agent-memory.remember`
+   - emit health metrics (scan path / file count / extracted / synced)
+
+2. `memory-tidy` (03:00)
+   - markdown consolidation/distillation
+   - call `agent-memory.reflect phase=all`
+
+3. `memory-surface` (14:05 / 22:05)
+   - generate `RECENT.md`
+
+Design principle: **Markdown is source of truth; agent-memory is a derived index layer.**
+
+---
+
+## Development
+
+```bash
+npm install
+npm test
+npm run build
+```
+
+---
+
+## License
+
+MIT

package/README.md

@@ -1,220 +1,153 @@
-# 🧠 AgentMemory v2
+# 🧠 AgentMemory v3
 
-> **Sleep-cycle memory architecture for AI agents** — remember, recall, forget, evolve.
+> 面向 AI Agent 的结构化长期记忆层：可写入、可检索、可衰减、可自动摄取。
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![npm](https://img.shields.io/npm/v/@smyslenny/agent-memory)](https://www.npmjs.com/package/@smyslenny/agent-memory)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/Node.js-≥18-green.svg)](https://nodejs.org/)
-[![MCP](https://img.shields.io/badge/protocol-MCP-orange.svg)](https://modelcontextprotocol.io/)
+[![MCP](https://img.shields.io/badge/MCP-9_tools-orange.svg)](https://modelcontextprotocol.io/)
 
-**English** | **[简体中文](README.zh-CN.md)**
+**简体中文** | **[English](README.en.md)**
 
 ---
 
-## 💡 The Problem
+## 项目定位（v3）
 
-AI agents forget everything between sessions. Context windows are finite. Conversation history gets truncated. Important decisions, lessons, and preferences vanish.
+AgentMemory 在 v3 中明确定位为 **OpenClaw memory-core 的结构化补充层**，而不是第二套全栈检索系统：
 
-## 🌙 The Solution: Sleep-Cycle Memory
+- Markdown（`memory/*.md` + `MEMORY.md`）是可读可编辑的事实源
+- agent-memory 是派生索引层，负责结构化记忆生命周期
 
-Inspired by how human brains consolidate memories during sleep, AgentMemory manages information across four phases:
+核心能力：
 
-```
-  Awake          Light Sleep       Deep Sleep        Recall
-  (Journal)      (Sync)            (Tidy)           (Search)
-  ────────── ──→ ────────── ──→ ────────── ──→ ──────────
-  Real-time      Deduplicate      Compress          Intent-aware
-  capture        + extract        + distill         BM25 search
-                                  + decay           + priority
-```
+- **类型化记忆**：`identity / emotion / knowledge / event`
+- **URI 路径寻址**：`core://`、`emotion://`、`knowledge://`、`event://`
+- **Write Guard**：写入前做去重与冲突门控
+- **BM25 检索**：带 priority × vitality 加权
+- **睡眠周期**：`reflect` 触发 decay / tidy / govern
+- **ingest 自动摄取**：从 markdown 提取并入库
+- **surface 只读浮现**：无副作用地补充上下文
+- **warm boot / reflect 报告**：人类可读输出
+- **多 Agent 隔离**：同库不同 agent_id 互不污染
 
-## ✨ Key Features
-
-| Feature | Description | Inspired By |
-|---------|-------------|-------------|
-| 🔗 **URI Path System** | `core://user/name`, `emotion://2026-02-20/love` — structured, multi-entry access | nocturne_memory |
-| 🛡️ **Write Guard** | Hash dedup → URI conflict → BM25 similarity → 4-criterion gate | Memory Palace + our v1 |
-| 🧠 **Ebbinghaus Decay** | `R = e^(-t/S)` — scientific forgetting curve with recall strengthening | PowerMem |
-| 🕸️ **Knowledge Graph** | Multi-hop traversal across memory associations | PowerMem |
-| 📸 **Snapshots** | Auto-snapshot before every change, one-click rollback | nocturne + Memory Palace |
-| 🔍 **Intent-Aware Search** | Factual / temporal / causal / exploratory query routing | Memory Palace |
-| 🌙 **Sleep Cycle** | Automated sync → decay → tidy → govern pipeline | - |
-| 💚 **Priority System** | P0 identity (never decays) → P3 event (14-day half-life) | - |
-| 🤝 **Multi-Agent** | Agent isolation via `agent_id` scope | PowerMem |
-| 🔌 **MCP Server** | 9 tools, works with Claude Code / Cursor / OpenClaw | Standard MCP |
+---
 
-## 🚀 Quick Start
+## 快速开始
 
-### Install
+### 安装
 
 ```bash
-npm install @smyslenny/agent-memory
+npm install -g @smyslenny/agent-memory
 ```
 
-### CLI
+### CLI 示例
 
 ```bash
-# Initialize database
+# 初始化数据库
 agent-memory init
 
-# Store memories
-agent-memory remember "User prefers dark mode" --type knowledge --uri knowledge://user/preferences
-agent-memory remember "I am Noah, a succubus" --type identity --uri core://agent/identity
+# 写入记忆
+agent-memory remember "用户偏好深色模式" --type knowledge --uri knowledge://preferences/theme
 
-# Search
-agent-memory recall "user preferences"
+# 检索
+agent-memory recall "用户偏好" --limit 5
 
-# Load identity at startup
+# 启动时加载（叙事格式）
 agent-memory boot
 
-# Run sleep cycle
+# 触发睡眠周期
 agent-memory reflect all
-
-# Import from Markdown
-agent-memory migrate ./memory/
-
-# Statistics
-agent-memory status
 ```
 
-### Library
-
-```typescript
-import { openDatabase, syncOne, searchBM25, boot, runDecay } from '@smyslenny/agent-memory';
-
-const db = openDatabase({ path: './memory.db' });
-
-// Remember
-syncOne(db, {
-  content: 'User said "I love you"',
-  type: 'emotion',
-  uri: 'emotion://2026-02-20/love',
-  emotion_val: 1.0,
-});
-
-// Recall
-const results = searchBM25(db, 'love');
-
-// Boot identity
-const identity = boot(db);
+---
 
-// Sleep cycle
-runDecay(db);
-```
+## MCP Server
 
-### MCP Server
+### 配置示例
 
 ```json
 {
   "mcpServers": {
-    "@smyslenny/agent-memory": {
+    "agent-memory": {
       "command": "node",
       "args": ["node_modules/@smyslenny/agent-memory/dist/mcp/server.js"],
       "env": {
-        "AGENT_MEMORY_DB": "./memory.db"
+        "AGENT_MEMORY_DB": "./agent-memory.db",
+        "AGENT_MEMORY_AGENT_ID": "noah",
+        "AGENT_MEMORY_AUTO_INGEST": "1",
+        "AGENT_MEMORY_WORKSPACE": "/home/user/.openclaw/workspace"
       }
     }
   }
 }
 ```
 
-**9 MCP Tools:** `remember` · `recall` · `recall_path` · `boot` · `forget` · `link` · `snapshot` · `reflect` · `status`
+### MCP 工具（9个）
 
-## 🔗 OpenClaw Integration
+- `remember`
+- `recall`
+- `recall_path`
+- `boot`
+- `forget`
+- `reflect`
+- `status`
+- `ingest`
+- `surface`
 
-AgentMemory works **out of the box** with [OpenClaw](https://github.com/smysle/openclaw)'s built-in memory cron jobs — no code changes required. The integration implements a **Capture → Consolidate → Surface** closed loop that keeps Markdown journals and the structured memory DB in sync automatically.
+> v3 已移除 `link` / `snapshot` 工具。
 
-### How It Works
+---
 
-```
-  Capture (memory-sync)          Consolidate (memory-tidy)        Surface (memory-surface)
-  ─────────────────────          ─────────────────────────        ───────────────────────
-  14:00 & 22:00                  03:00                            14:05 & 22:05
-  Session → daily journal        Compress old dailies             Recall top memories
-  + remember each bullet         Distill → MEMORY.md             → generate RECENT.md
-    into agent-memory DB         + reflect phase=all              (≤80 lines, 3 sections)
-```
+## Auto-Ingest（文件变更自动入库）
 
-| Phase | Cron Job | What Happens | agent-memory Integration |
-|-------|----------|-------------|--------------------------|
-| **Capture** | `memory-sync` | Scans sessions, appends bullets to `memory/YYYY-MM-DD.md` | Each new bullet is also written via `mcporter call agent-memory.remember` with auto-classified type and URI-based dedup |
-| **Consolidate** | `memory-tidy` | Compresses old dailies → weekly summaries, distills `MEMORY.md` | Triggers `agent-memory.reflect phase=all` (decay + tidy + govern) + consistency spot-check |
-| **Surface** | `memory-surface` | Generates short-term context for new sessions | Reads high-vitality memories from agent-memory, outputs structured `RECENT.md` with emotion/knowledge/event sections |
+MCP server 启动后会默认开启 watcher（`fs.watch`）：
 
-### Key Design Principles
+- `~/.openclaw/workspace/memory/*.md`
+- `~/.openclaw/workspace/MEMORY.md`
 
-- **Markdown is source of truth** — agent-memory is a derived index layer; all data flows Markdown → DB, never the reverse.
-- **Best-effort sync** — If `mcporter` or agent-memory is unavailable, Markdown operations proceed normally. Failures only log warnings.
-- **URI-based idempotency** — Each journal bullet maps to a unique URI (`event://journal/2026-02-21#2200-1`), so re-runs are safe.
-- **Keyword-based classification** — Bullets are auto-classified as `knowledge`, `emotion`, or `event` using simple keyword rules (no extra model calls).
+当文件变化时自动执行 ingest（复用 Write Guard，幂等/去重）。
 
-### Setup
+环境变量：
 
-If you're running OpenClaw with the standard memory cron suite (`memory-sync`, `memory-tidy`, `memory-surface`), the integration is **already active** — the cron prompts include agent-memory sync steps. Just make sure:
+- `AGENT_MEMORY_AUTO_INGEST`
+  - `1`（默认）：开启
+  - `0`：关闭
+- `AGENT_MEMORY_WORKSPACE`
+  - 默认：`$HOME/.openclaw/workspace`
 
-1. **agent-memory is installed and initialized** — `agent-memory init`
-2. **mcporter bridge is configured** — agent-memory MCP server registered in your mcporter config
-3. **Cron jobs are enabled** — check with `openclaw cron list`
+---
 
-For detailed setup and prompt templates, see:
-- [`examples/openclaw-setup.md`](examples/openclaw-setup.md) — Full setup walkthrough
-- [`docs/design/0004-agent-memory-integration.md`](docs/design/0004-agent-memory-integration.md) — Design document (DD-0004)
+## OpenClaw 集成建议（方案A）
 
-## 🏗️ Architecture
+推荐三段 cron：
 
-```
-┌─────────────────────────────────────────┐
-│         MCP Server (stdio/SSE)          │
-│     9 tools + system://boot loader      │
-├─────────────────────────────────────────┤
-│              Write Guard                │
-│  hash dedup → URI conflict → BM25 sim  │
-│  → conflict merge → 4-criterion gate    │
-├─────────────────────────────────────────┤
-│           Sleep Cycle Engine            │
-│  sync (capture) → decay (Ebbinghaus)   │
-│  → tidy (archive) → govern (cleanup)   │
-├─────────────────────────────────────────┤
-│        Intent-Aware Search (BM25)       │
-│  factual · temporal · causal · explore  │
-├─────────────────────────────────────────┤
-│     SQLite (WAL) + FTS5 + Graph Links   │
-│  memories · paths · links · snapshots   │
-└─────────────────────────────────────────┘
-```
+1. `memory-sync`（14:00 / 22:00）
+   - 动态发现 session JSONL
+   - 增量写入 `memory/YYYY-MM-DD.md`
+   - best-effort 同步到 `agent-memory.remember`
+   - 输出健康指标（扫描路径、会话文件数、提取数、写库数）
 
-## 📊 Priority & Decay
+2. `memory-tidy`（03:00）
+   - 压缩/蒸馏 markdown
+   - 调用 `agent-memory.reflect phase=all`
 
-| Priority | Domain | Half-life | Min Vitality | Example |
-|----------|--------|-----------|-------------|---------|
-| P0 Identity | `core://` | ∞ (never) | 1.0 | "I am Noah" |
-| P1 Emotion | `emotion://` | 365 days | 0.3 | "User said I love you" |
-| P2 Knowledge | `knowledge://` | 90 days | 0.1 | "Use TypeScript for agents" |
-| P3 Event | `event://` | 14 days | 0.0 | "Configured proxy today" |
+3. `memory-surface`（14:05 / 22:05）
+   - 生成 `RECENT.md`
 
-**Recall strengthens memory:** each search hit increases stability (S × 1.5), slowing future decay.
+设计原则：**Markdown 是真相源，agent-memory 是派生索引层。**
 
-## 🔬 Design Decisions
+---
 
-1. **SQLite over Postgres/MongoDB** — Zero config, single file, WAL mode for concurrent reads
-2. **BM25 over vector search** — No embedding dependency, instant startup, good enough for structured memory
-3. **TypeScript over Python** — Better concurrency, type safety, OpenClaw ecosystem alignment
-4. **Ebbinghaus over linear decay** — Scientifically grounded, recall strengthening is natural
-5. **Write Guard over free writes** — Prevent duplicate/conflicting memories at the gate
-6. **URI paths over flat keys** — Hierarchical organization, prefix queries, multi-entry access
+## 开发
 
-## 📋 Project Documents
+```bash
+npm install
+npm test
+npm run build
+```
 
-| Document | Description |
-|----------|-------------|
-| [PLANNING.md](PLANNING.md) | Technical architecture + 5-project comparison |
-| [ROADMAP.md](ROADMAP.md) | Implementation phases + milestones |
-| [ACCEPTANCE.md](ACCEPTANCE.md) | 40+ acceptance criteria + performance targets |
-| [COMPLETION.md](COMPLETION.md) | Release checklist + retrospective template |
+---
 
-## 📄 License
+## License
 
 MIT
-
----
-
-*Built by agents who got tired of forgetting. 🧠*