lily-memory

OpenClaw 代理的持久内存插件。混合 SQLite FTS5 关键字 + Ollama 矢量语义搜索，具有自动捕获、自动调用、卡住检测和内存整合功能。零 npm 依赖。

# Lily Memory

Persistent memory plugin for OpenClaw agents. Gives your agent long-term memory that survives session resets, compaction, and restarts.

## What It Does

- **Auto-recall**: Injects relevant memories as context before each LLM turn
- **Auto-capture**: Extracts facts from conversations and stores them automatically
- **Hybrid search**: SQLite FTS5 keyword search + Ollama vector cosine similarity
- **Stuck detection**: Detects topic repetition and nudges the agent to break loops
- **Memory consolidation**: Deduplicates entries on startup
- **Dynamic entities**: Config-driven allowlist + runtime tool to add entities
- **Graceful degradation**: Works without Ollama (keyword-only mode)
- **Zero npm dependencies**: Uses sqlite3 CLI + native fetch

## Requirements

- Node.js 18+ (for native `fetch`)
- SQLite 3.33+ with FTS5 (ships with macOS; `apt install sqlite3` on Linux)
- Optional: Ollama with `nomic-embed-text` model for semantic search

## Quick Start

1. Install the plugin to your extensions directory
2. Add to your `openclaw.json`:

```json
{
  "plugins": {
    "slots": { "memory": "lily-memory" },
    "entries": {
      "lily-memory": {
        "enabled": true,
        "config": {
          "dbPath": "~/.openclaw/memory/decisions.db",
          "entities": ["config", "system"]
        }
      }
    }
  }
}
```

3. Restart the gateway: `openclaw gateway restart`

## Tools

| Tool | Description |
|------|-------------|
| `memory_search` | FTS5 keyword search across all facts |
| `memory_entity` | Look up all facts for a specific entity |
| `memory_store` | Save a fact to persistent memory |
| `memory_semantic_search` | Vector similarity search via Ollama |
| `memory_add_entity` | Register a new entity at runtime |

## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `dbPath` | string | `~/.openclaw/memory/decisions.db` | SQLite database path |
| `autoRecall` | boolean | `true` | Inject memories before each turn |
| `autoCapture` | boolean | `true` | Extract facts from responses |
| `maxRecallResults` | number | `10` | Max memories per turn |
| `maxCapturePerTurn` | number | `5` | Max facts per response |
| `stuckDetection` | boolean | `true` | Topic repetition detection |
| `vectorSearch` | boolean | `true` | Ollama semantic search |
| `ollamaUrl` | string | `http://localhost:11434` | Ollama endpoint |
| `embeddingModel` | string | `nomic-embed-text` | Embedding model |
| `consolidation` | boolean | `true` | Dedup on startup |
| `vectorSimilarityThreshold` | number | `0.5` | Min cosine similarity |
| `entities` | array | `[]` | Additional entity names |

## Architecture

**Recall flow**: Extract keywords from message -> FTS5 + vector search -> merge and deduplicate -> inject as context

**Capture flow**: Regex scan for `entity: key = value` patterns -> validate entity against allowlist -> store to SQLite -> async embed via Ollama

**Stuck detection**: Track top 5 content words per response -> Jaccard similarity -> if 3+ consecutive >60% overlap, inject Reflexion nudge

## License

MIT

---

## 中文说明

# Lily Memory

OpenClaw 代理的持久内存插件。为你的代理提供能够在会话重置、压缩和重启后存续的长期记忆。

## 功能说明

- **自动回忆**：在每次 LLM 轮次之前注入相关记忆作为上下文
- **自动捕获**：从对话中提取事实并自动存储
- **混合搜索**：SQLite FTS5 关键字搜索 + Ollama 向量余弦相似度
- **卡顿检测**：检测话题重复并促使代理打破循环
- **记忆整合**：在启动时去重条目
- **动态实体**：配置驱动的允许列表 + 运行时工具以添加实体
- **优雅降级**：无需 Ollama 也能工作（仅关键字模式）
- **零 npm 依赖**：使用 sqlite3 CLI + 原生 fetch

## 要求

- Node.js 18+（用于原生 `fetch`）
- 带 FTS5 的 SQLite 3.33+（macOS 自带；Linux 上 `apt install sqlite3`）
- 可选：带 `nomic-embed-text` 模型的 Ollama，用于语义搜索

## 快速开始

1. 将插件安装到你的扩展目录
2. 添加到你的 `openclaw.json`：

```json
{
  "plugins": {
    "slots": { "memory": "lily-memory" },
    "entries": {
      "lily-memory": {
        "enabled": true,
        "config": {
          "dbPath": "~/.openclaw/memory/decisions.db",
          "entities": ["config", "system"]
        }
      }
    }
  }
}
```

3. 重启网关：`openclaw gateway restart`

## 工具

| 工具 | 说明 |
|------|-------------|
| `memory_search` | 跨所有事实的 FTS5 关键字搜索 |
| `memory_entity` | 查找特定实体的所有事实 |
| `memory_store` | 将一条事实保存到持久内存 |
| `memory_semantic_search` | 通过 Ollama 进行向量相似度搜索 |
| `memory_add_entity` | 在运行时注册一个新实体 |

## 配置

| 选项 | 类型 | 默认值 | 说明 |
|--------|------|---------|-------------|
| `dbPath` | string | `~/.openclaw/memory/decisions.db` | SQLite 数据库路径 |
| `autoRecall` | boolean | `true` | 在每轮之前注入记忆 |
| `autoCapture` | boolean | `true` | 从响应中提取事实 |
| `maxRecallResults` | number | `10` | 每轮最大记忆数 |
| `maxCapturePerTurn` | number | `5` | 每个响应最大事实数 |
| `stuckDetection` | boolean | `true` | 话题重复检测 |
| `vectorSearch` | boolean | `true` | Ollama 语义搜索 |
| `ollamaUrl` | string | `http://localhost:11434` | Ollama 端点 |
| `embeddingModel` | string | `nomic-embed-text` | 嵌入模型 |
| `consolidation` | boolean | `true` | 启动时去重 |
| `vectorSimilarityThreshold` | number | `0.5` | 最小余弦相似度 |
| `entities` | array | `[]` | 额外的实体名称 |

## 架构

**回忆流程**：从消息中提取关键字 -> FTS5 + 向量搜索 -> 合并并去重 -> 作为上下文注入

**捕获流程**：用正则扫描 `entity: key = value` 模式 -> 根据允许列表校验实体 -> 存储到 SQLite -> 通过 Ollama 异步嵌入

**卡顿检测**：跟踪每个响应的前 5 个内容词 -> Jaccard 相似度 -> 若连续 3 次以上重叠 >60%，则注入 Reflexion 提示

## 许可证

MIT