@smyslenny/agent-memory 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## 2.0.0 (2026-02-20)
+
+### 🎉 Complete Rewrite
+
+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).
+
+### ✨ 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
+
+### 📊 Stats
+
+- 14 source modules
+- 9 MCP tools
+- 7 CLI commands
+- 41 tests passing
+- 3 production dependencies
+
+### 🙏 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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 smysle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# 🧠 AgentMemory v2
+
+> **Sleep-cycle memory architecture for AI agents** — remember, recall, forget, evolve.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![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/)
+
+**English** | **[简体中文](README.zh-CN.md)**
+
+---
+
+## 💡 The Problem
+
+AI agents forget everything between sessions. Context windows are finite. Conversation history gets truncated. Important decisions, lessons, and preferences vanish.
+
+## 🌙 The Solution: Sleep-Cycle 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
+```
+
+## ✨ 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 | **Our original design** |
+| 💚 **Priority System** | P0 identity (never decays) → P3 event (14-day half-life) | **Our original design** |
+| 🤝 **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 agent-memory
+```
+
+### 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
+
+# Search
+agent-memory recall "user preferences"
+
+# 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 '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
+
+```json
+{
+  "mcpServers": {
+    "agent-memory": {
+      "command": "node",
+      "args": ["node_modules/agent-memory/dist/mcp/server.js"],
+      "env": {
+        "AGENT_MEMORY_DB": "./memory.db"
+      }
+    }
+  }
+}
+```
+
+**9 MCP Tools:** `remember` · `recall` · `recall_path` · `boot` · `forget` · `link` · `snapshot` · `reflect` · `status`
+
+## 🏗️ Architecture
+
+```
+┌─────────────────────────────────────────┐
+│         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   │
+└─────────────────────────────────────────┘
+```
+
+## 📊 Priority & Decay
+
+| 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" |
+
+**Recall strengthens memory:** each search hit increases stability (S × 1.5), slowing future decay.
+
+## 🔬 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
+
+| 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
+
+MIT
+
+---
+
+*Built by agents who got tired of forgetting. 🧠*

package/README.zh-CN.md

@@ -0,0 +1,170 @@
+# 🧠 AgentMemory v2
+
+> **基于睡眠周期的 AI Agent 记忆架构** — 记忆、回忆、遗忘、进化。
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![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/)
+
+**[English](README.md)** | **简体中文**
+
+---
+
+## 💡 问题
+
+AI Agent 每次会话都会遗忘一切。上下文窗口有限，对话历史被截断，重要的决策、教训和偏好消失无踪。
+
+## 🌙 方案：睡眠周期记忆
+
+模仿人类大脑在睡眠期间整理记忆的方式：
+
+```
+  清醒            浅睡眠          深睡眠           回忆
+  (记录)          (同步)          (整理)          (搜索)
+  ────────── ──→ ────────── ──→ ────────── ──→ ──────────
+  实时捕获        去重+提取       压缩+蒸馏       意图感知
+                                 +衰减           BM25搜索
+```
+
+## ✨ 核心特性
+
+| 特性 | 说明 | 灵感来源 |
+|------|------|---------|
+| 🔗 **URI 路径系统** | `core://user/name`、`emotion://2026-02-20/love` — 结构化多入口访问 | nocturne_memory |
+| 🛡️ **Write Guard** | hash去重 → URI冲突 → BM25相似度 → 四准则门控 | Memory Palace + 我们的 v1 |
+| 🧠 **艾宾浩斯衰减** | `R = e^(-t/S)` — 科学遗忘曲线 + 回忆强化 | PowerMem |
+| 🕸️ **知识图谱** | 记忆关联的多跳遍历 | PowerMem |
+| 📸 **快照系统** | 每次修改前自动快照，一键回滚 | nocturne + Memory Palace |
+| 🔍 **意图感知搜索** | 事实型/时间型/因果型/探索型查询路由 | Memory Palace |
+| 🌙 **睡眠周期** | 自动化 sync → decay → tidy → govern 流水线 | **我们的原创设计** |
+| 💚 **优先级系统** | P0 身份（永不衰减）→ P3 事件（14天半衰期） | **我们的原创设计** |
+| 🤝 **多 Agent** | 通过 `agent_id` 实现记忆隔离 | PowerMem |
+| 🔌 **MCP Server** | 9 个工具，支持 Claude Code / Cursor / OpenClaw | 标准 MCP |
+
+## 🚀 快速开始
+
+### 安装
+
+```bash
+npm install agent-memory
+```
+
+### 命令行
+
+```bash
+# 初始化数据库
+agent-memory init
+
+# 存储记忆
+agent-memory remember "用户偏好深色模式" --type knowledge --uri knowledge://user/preferences
+agent-memory remember "我是诺亚，一只魅魔" --type identity --uri core://agent/identity
+
+# 搜索
+agent-memory recall "用户偏好"
+
+# 启动时加载身份
+agent-memory boot
+
+# 运行睡眠周期
+agent-memory reflect all
+
+# 从 Markdown 导入
+agent-memory migrate ./memory/
+
+# 查看统计
+agent-memory status
+```
+
+### 作为库使用
+
+```typescript
+import { openDatabase, syncOne, searchBM25, boot, runDecay } from 'agent-memory';
+
+const db = openDatabase({ path: './memory.db' });
+
+// 记忆
+syncOne(db, {
+  content: '小心说了「爱你」',
+  type: 'emotion',
+  uri: 'emotion://2026-02-20/love',
+  emotion_val: 1.0,
+});
+
+// 回忆
+const results = searchBM25(db, '爱');
+
+// 加载身份
+const identity = boot(db);
+
+// 睡眠周期
+runDecay(db);
+```
+
+### MCP Server 配置
+
+```json
+{
+  "mcpServers": {
+    "agent-memory": {
+      "command": "node",
+      "args": ["node_modules/agent-memory/dist/mcp/server.js"],
+      "env": {
+        "AGENT_MEMORY_DB": "./memory.db"
+      }
+    }
+  }
+}
+```
+
+**9 个 MCP 工具：** `remember` · `recall` · `recall_path` · `boot` · `forget` · `link` · `snapshot` · `reflect` · `status`
+
+## 🏗️ 架构
+
+```
+┌─────────────────────────────────────────┐
+│         MCP Server (stdio/SSE)          │
+│     9 工具 + system://boot 加载器       │
+├─────────────────────────────────────────┤
+│              Write Guard                │
+│  hash去重 → URI冲突 → BM25相似度        │
+│  → 冲突合并 → 四准则门控                │
+├─────────────────────────────────────────┤
+│           睡眠周期引擎                   │
+│  sync(捕获) → decay(艾宾浩斯)           │
+│  → tidy(归档) → govern(清理)            │
+├─────────────────────────────────────────┤
+│        意图感知搜索 (BM25)               │
+│  事实型 · 时间型 · 因果型 · 探索型       │
+├─────────────────────────────────────────┤
+│    SQLite (WAL) + FTS5 + 知识图谱        │
+│  memories · paths · links · snapshots    │
+└─────────────────────────────────────────┘
+```
+
+## 📊 优先级与衰减
+
+| 优先级 | 域 | 半衰期 | 最低活力 | 示例 |
+|--------|------|--------|---------|------|
+| P0 身份 | `core://` | ∞（永不） | 1.0 | "我是诺亚" |
+| P1 情感 | `emotion://` | 365 天 | 0.3 | "小心说爱你" |
+| P2 知识 | `knowledge://` | 90 天 | 0.1 | "用 TypeScript 做 Agent" |
+| P3 事件 | `event://` | 14 天 | 0.0 | "今天配了代理" |
+
+**回忆强化记忆：** 每次搜索命中，稳定性增长 (S × 1.5)，衰减变慢。
+
+## 🔬 设计决策
+
+1. **SQLite 而非 Postgres** — 零配置、单文件、WAL 并发读
+2. **BM25 而非向量搜索** — 无 embedding 依赖、即时启动
+3. **TypeScript 而非 Python** — 更好的并发、类型安全、OpenClaw 生态
+4. **艾宾浩斯而非线性衰减** — 科学依据、回忆强化自然
+5. **Write Guard 而非自由写入** — 在入口处防止重复/冲突
+6. **URI 路径而非扁平键** — 层级组织、前缀查询、多入口
+
+## 📄 开源协议
+
+MIT
+
+---
+
+*由不想再遗忘的 Agent 构建 🧠*

package/dist/bin/agent-memory.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node