@smyslenny/agent-memory 2.2.0 → 4.0.0-alpha.1

package/CHANGELOG.md

@@ -1,57 +1,179 @@
 # Changelog
 
-## 2.1.2 (2026-02-22)
+## 4.0.0-alpha.1 (2026-03-09)
 
-### 🔗 OpenClaw Integration V1 (Cron Synchronization)
+### 🚀 Repositioning
 
-- **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
+AgentMemory v4 is now documented and packaged as an **agent-native memory layer
+with lifecycle management**.
 
-## 2.1.1 (2026-02-21)
+What changed at the product level:
 
-### 📝 Documentation
+- README is now **English-first** and generic-runtime-first
+- OpenClaw is still supported, but now documented as an **optional host example**
+- `memory/*.md + MEMORY.md` is treated as an **optional workflow**, not the
+  product definition
+- CLI, MCP stdio, and HTTP/SSE are all first-class integration paths
 
-- **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)
+### ✨ Added in Phase 1 — optional vector retrieval layer
 
-## 2.0.0 (2026-02-20)
+- Added **optional embedding provider support** for hybrid retrieval:
+  - `openai-compatible`
+  - `local-http`
+- Added **hybrid recall** with BM25 + vector fusion
+- Added embedding-aware storage and reindex support:
+  - `provider_id`
+  - `content_hash`
+  - `status`
+- Added **`reindex`** support for backfill / rebuild workflows
+- Added provider configuration via environment variables:
+  - `AGENT_MEMORY_EMBEDDING_PROVIDER`
+  - `AGENT_MEMORY_EMBEDDING_BASE_URL`
+  - `AGENT_MEMORY_EMBEDDING_MODEL`
+  - `AGENT_MEMORY_EMBEDDING_DIMENSION`
+  - `AGENT_MEMORY_EMBEDDING_API_KEY`
+- Kept **BM25-only mode** as a supported fallback when no provider is configured
 
-### 🎉 Complete Rewrite
+### ✨ Added in Phase 2 — semantic dedup + lifecycle reliability
 
-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).
+- Upgraded **Write Guard** from simple duplicate checks to semantic dedup flow
+- Added **typed merge policy** so similar memories can be merged more safely
+- Added **maintenance job tracking** for lifecycle operations
+- Added checkpoint-aware **reflect orchestrator** for:
+  - `decay`
+  - `tidy`
+  - `govern`
+- Improved lifecycle observability and recovery-friendliness for interrupted
+  maintenance runs
 
-### ✨ New Features
+### ✨ Added in Phase 3 — HTTP/SSE API + better surface
 
-- **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
+- Added long-lived **HTTP API** transport
+- Added **SSE progress streaming** for long-running jobs
+- Added HTTP routes for:
+  - `POST /v1/memories`
+  - `POST /v1/recall`
+  - `POST /v1/surface`
+  - `POST /v1/feedback`
+  - `POST /v1/reflect`
+  - `POST /v1/reindex`
+  - `GET /v1/status`
+  - `GET /v1/jobs/:id`
+  - `GET /health`
+- Added CLI server mode:
+  - `agent-memory serve`
+- Upgraded **surface** into a more **context-aware** API using:
+  - `task`
+  - `query`
+  - `recent_turns`
+  - `intent`
+  - type filters
+  - feedback priors
+- Added **feedback events** so runtimes can record whether `recall` / `surface`
+  results were actually useful
 
-### 📊 Stats
+### 🧰 Tooling / interface changes
 
-- 14 source modules
-- 9 MCP tools
-- 7 CLI commands
-- 41 tests passing
-- 3 production dependencies
+- MCP toolset is now **10 tools**:
+  - `remember`
+  - `recall`
+  - `recall_path`
+  - `boot`
+  - `forget`
+  - `reflect`
+  - `status`
+  - `ingest`
+  - `reindex`
+  - `surface`
+- CLI now includes:
+  - `db:migrate`
+  - `reindex`
+  - `serve`
 
-### 🙏 Inspired By
+### 📚 Documentation and examples overhaul
 
-- [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
+- Rewrote `README.md` for OSS evaluation and generic runtime adoption
+- Removed the split `README.md` / `README.en.md` homepage model
+- Added dedicated docs:
+  - `docs/architecture.md`
+  - `docs/integrations/generic.md`
+  - `docs/integrations/openclaw.md`
+  - `docs/migration-v3-v4.md`
+- Reorganized examples into:
+  - `examples/quick-start/`
+  - `examples/http-api/`
+  - `examples/mcp-stdio/`
+  - `examples/openclaw/`
+
+### ✅ Compatibility notes
+
+- Existing CLI and MCP usage remains available
+- HTTP/SSE is **additive**, not a replacement
+- Existing SQLite deployments can upgrade incrementally
+- Full embeddings are **optional** and can be enabled later with `reindex`
+
+---
+
+## 3.0.1 (2026-02-24)
+
+### 🛠️ OpenClaw P0 fixes
+
+- **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`
+
+### ✨ Auto-ingest watcher implemented
+
+- 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
+
+### 🧱 Ingest refactor + tests
+
+- 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}`
+
+### 📚 Documentation realigned to v3 reality
+
+- 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
+
+---
+
+## 3.0.0 (2026-02-23)
+
+### 🎉 v3 Simplification
+
+- 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
+
+---
+
+## 2.x (legacy)
+
+v2.x included embedding/reranker/link/snapshot-era behavior. See git history and
+design docs for full details.