@bsbofmusic/openclaw-memory-layer2 0.2.1 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +45 -112
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,136 +1,69 @@
1
1
  # @bsbofmusic/openclaw-memory-layer2
2
2
 
3
- Layer2 Memory MCP Server — semantic + structured recall over memos PostgreSQL.
3
+ [![NPM Version](https://img.shields.io/npm/v/@bsbofmusic/openclaw-memory-layer2.svg)](https://www.npmjs.com/package/@bsbofmusic/openclaw-memory-layer2)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
4
5
 
5
- ## 这是什么
6
+ > [English](#english) | [中文](#中文)
6
7
 
7
- 在 OpenClaw 双层记忆架构中提供 Layer2 能力：
8
+ ---
8
9
 
9
- - **Layer 1** (File Brain): OpenClaw memorySearch — 语义主链，规则/配置/拍板结论
10
- - **Layer 2** (Raw Facts): memos PostgreSQL + 本 MCP — 原话/细节/承诺/上下文
10
+ <a name="english"></a>
11
11
 
12
- 本 MCP 将 memos PostgreSQL 封装为 stdio MCP Server，并复用 OpenClaw `agents.defaults.memorySearch` 的 embedding 配置提供语义搜索能力。
12
+ ## English
13
13
 
14
- ## 一键启用
14
+ ### Introduction
15
+ **OpenClaw Memory Layer2** is a production-grade Long-term Memory MCP (Model Context Protocol) Server designed for the OpenClaw ecosystem. It bridges the gap between raw conversation logs and high-precision retrieval by combining **Hindsight** (Semantic Recall) and **PostgreSQL Memos** (Hard Evidence Verification).
15
16
 
16
- ### npx（无需安装）
17
- ```bash
18
- npx @bsbofmusic/openclaw-memory-layer2
19
- ```
17
+ ### Core Features
18
+ - **Hindsight-First, Memos-as-Judge**: Uses Hindsight for broad semantic association while enforcing strict entity alignment via Memos to prevent "hallucinated recall".
19
+ - **Hybrid Retrieval**: Simultaneous Keyword + Vector (Cosine Similarity) search with weighted boosting for high-recall Chinese matching.
20
+ - **Production Readiness**: Built-in PM2 support, bounded timeouts for external services, and automated ingest pipelines.
21
+ - **Clean Ingest**: Intelligent filtering of tool logs, system events, and meta-noise to keep the memory bank pure.
20
22
 
21
- ### npm 本地安装
23
+ ### Quick Start
22
24
  ```bash
23
- npm install -g @bsbofmusic/openclaw-memory-layer2
24
- openclaw-memory-layer2
25
- ```
25
+ # Install
26
+ npm install @bsbofmusic/openclaw-memory-layer2
26
27
 
27
- ### Docker（TODO v0.2）
28
- ```bash
29
- docker run bsbofmusic/openclaw-memory-layer2
30
- ```
31
-
32
- ## 环境变量
33
-
34
- | 变量 | 默认值 | 说明 |
35
- |------|--------|------|
36
- | `OPENCLAW_CONFIG` | `/var/lib/openclaw/.openclaw/openclaw.json` | 默认从这里读取 OpenClaw memorySearch 配置 |
37
- | `LAYER2_EMBED_API_KEY` | *(可选 override)* | 显式覆盖 embedding API key |
38
- | `LAYER2_EMBED_BASE_URL` | *(可选 override)* | 显式覆盖 embedding endpoint |
39
- | `LAYER2_EMBED_MODEL` | *(可选 override)* | 显式覆盖 embedding model |
40
- | `MEMOS_PG_HOST` | `127.0.0.1` | PostgreSQL 主机 |
41
- | `MEMOS_PG_PORT` | `5432` | PostgreSQL 端口 |
42
- | `MEMOS_PG_DB` | `memos` | 数据库名 |
43
- | `MEMOS_PG_USER` | `memos` | 数据库用户 |
44
- | `MEMOS_PG_PASSWORD` | `memos_local_20260312` | 数据库密码 |
45
- | `LOG_LEVEL` | `info` | error / info / debug |
46
- | `WORKSPACE` | `/var/lib/openclaw/.openclaw/workspace` | 工作区路径 |
47
-
48
- ## MCP 工具列表
49
-
50
- | 工具 | 说明 |
51
- |------|------|
52
- | `semantic_search` | 复用 OpenClaw memorySearch embedding 配置 → cosine similarity 语义搜索 |
53
- | `query_memos` | 结构化 SELECT（只读），支持参数化查询 |
54
- | `get_memos_stats` | 统计：总数、private/public、24h活跃 |
55
- | `trigger_ingest` | 触发 session → memos ingest |
56
- | `memory_layer2_info` | Layer1/Layer2 分工文档 |
57
- | `layer2_ensure` | Bootstrap 自检 |
58
- | `layer2_doctor` | 完整诊断 + 修复建议 |
59
- | `hindsight_health` | 检查 Hindsight 服务是否可达 |
60
- | `layer2_answer` | Hindsight + memos 联合归纳回答入口 |
61
- | `layer2_version` | 版本信息 |
62
- | `layer2_list_commands` | 工具自发现 |
63
-
64
- ## 验证命令
28
+ # Run Diagnostics
29
+ npm run doctor
65
30
 
66
- ```bash
67
- # Doctor（独立诊断）
68
- node doctor.js
69
-
70
- # MCP 工具测试（默认复用 OpenClaw memorySearch embedding 配置）
71
- echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"layer2_ensure","arguments":{}}}' \
72
- | node index.js
73
-
74
- # PostgreSQL 连接验证
75
- PGPASSWORD='memos_local_20260312' psql -h 127.0.0.1 -U memos -d memos -Atqc "SELECT count(*) FROM memo;"
76
- ```
77
-
78
- ## 预期输出样例
79
-
80
- ### ✅ layer2_ensure 成功
81
- ```json
82
- {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"layer2_ensure:\n{\"ok\":true,\"steps\":[...]}\n"}]}}
83
- ```
84
-
85
- ### ❌ layer2_doctor 失败（OpenClaw embedding 配置缺失）
86
- ```
87
- === Layer2 Doctor v0.1.0 ===
88
-
89
- Checks:
90
- ✅ PostgreSQL: connected, memo rows: 11398
91
- ❌ embedding: OpenClaw memorySearch embedding config not found
92
- → Fix: 配置 agents.defaults.memorySearch.remote.baseUrl/apiKey/model
93
- ✅ ingest_script: /var/lib/openclaw/.openclaw/workspace/scripts/ingest_session_raw_to_memos.py
94
- ✅ runtime_dir: /var/lib/openclaw/.openclaw/workspace/.layer2-runtime
95
- ✅ pg_module: pg package available
96
-
97
- ⚠️ Some checks failed — see above
31
+ # Start with PM2
32
+ npm run pm2:start
98
33
  ```
99
34
 
100
- ## 自动更新策略
101
-
102
- - 不做自动更新（v0.1）
103
- - 每次调用前不做 ensureLatest 检查
104
- - 手动升级：npm update 或重新安装包
35
+ ---
105
36
 
106
- ## 已知限制
37
+ <a name="中文"></a>
107
38
 
108
- - semantic_search 在 v0.1 阶段为全文 embedding 逐条打分散列，未使用 pgvector 索引（v0.2 规划）
109
- - 单次 semantic_search 最多 200 条 memo 初筛
110
- - 若 OpenClaw memorySearch embedding 配置缺失，semantic_search 返回错误，其他功能正常
111
- - trigger_ingest 为同步调用，超时时间 60s
39
+ ## 中文
112
40
 
113
- ## 合规声明
41
+ ### 简介
42
+ **OpenClaw Memory Layer2** 是为 OpenClaw 生态设计的生产级长效记忆 MCP 服务。它通过结合 **Hindsight**（语义召回）与 **PostgreSQL Memos**（硬核实锤校验），解决了原始对话记录在召回时的“语义漂移”与“幻觉”问题。
114
43
 
115
- 本项目是独立开发的 MCP Server，不封装任何第三方 GitHub 项目。
116
- Layer2 默认复用 OpenClaw memorySearch 的 embedding 提供者与模型配置。
44
+ ### 核心特性
45
+ - **Hindsight 召回，Memos 裁决**：利用 Hindsight 进行广度语义联想，同时通过 Memos 进行严格的实体对齐（关键词校验），防止“张冠李戴”。
46
+ - **混合检索框架**：支持关键词 + 向量（余弦相似度）双路融合检索，针对中文场景进行了分词优化，大幅提升召回率。
47
+ - **生产级稳定性**：内置 PM2 进程管理，外部服务调用带有硬超时保护，避免阻塞主对话链。
48
+ - **净化入库 (Ingest)**：智能过滤工具日志、系统事件及元数据噪音，确保记忆库的纯净度。
117
49
 
50
+ ### 快速开始
51
+ ```bash
52
+ # 安装
53
+ npm install @bsbofmusic/openclaw-memory-layer2
118
54
 
119
- ## Hindsight
55
+ # 运行诊断
56
+ npm run doctor
120
57
 
121
- - Layer2 已完成 **Hindsight + memos** 联合验证，默认读取：
122
- - `HINDSIGHT_BASE_URL`（默认 `http://127.0.0.1:8888`）
123
- - `HINDSIGHT_BANK_ID`（默认 `openclaw-main`）
124
- - 已接入工具：`hindsight_health`、`layer2_answer`
125
- - 当前定位：`memos` 提供原始事实/原话证据，`Hindsight` 提供 recall / reflect / 聚合归纳
126
- - 当前已通过的是**架构级联合验证**；若继续推进，下一阶段才是回答质量调优与常驻化收口。
58
+ # 使用 PM2 启动
59
+ npm run pm2:start
60
+ ```
127
61
 
128
- ## 常驻运行
62
+ ### 架构分工
63
+ 1. **Layer 1 (OpenClaw Native)**: 负责稳定事实、规则、拍板结论。
64
+ 2. **Layer 2 (This Package)**: 负责原话、细节、时间点、承诺。
129
65
 
130
- 推荐用 PM2 常驻：
66
+ ---
131
67
 
132
- ```bash
133
- cd /var/lib/openclaw/.openclaw/workspace/npm-pkgs/openclaw-memory-layer2
134
- npm run pm2:start
135
- pm2 logs openclaw-memory-layer2
136
- ```
68
+ ## License
69
+ MIT © [bsbofmusic](https://github.com/bsbofmusic)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bsbofmusic/openclaw-memory-layer2",
3
- "version": "0.2.1",
3
+ "version": "0.2.2",
4
4
  "description": "Layer2 Memory MCP Server — Hindsight + memos unified validation over memos PostgreSQL, reusing OpenClaw memorySearch embedding config",
5
5
  "main": "index.js",
6
6
  "bin": {