ai-workspace-services/qmd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
236c83a5f3
qmd/docs/plan/pg-memory-bridge-changelog.md
Haitao Pan 47bd3ded44 feat(pg): add switchable PostgreSQL backend + OpenClaw/Hermes memory bridge 
Add an optional PostgreSQL backend (QMD_BACKEND=pg) alongside the
unchanged default SQLite path. PG store uses pgvector (HNSW) for vectors
and pg_jieba + pg_trgm for full-text/Chinese tokenization, with a
namespace column isolating multi-agent memory (openclaw/hermes).

- src/pg/: config, db-pg, schema bootstrap, memory store
- MCP memory_add/memory_search/memory_get tools; qmd pg status + memory CLI
- connection via QMD_PG_URL/DATABASE_URL/qmd config, stunnel TLS 5443
- tests: pg-config (unit) + pg-memory integration (gated on QMD_PG_URL) + pg-compose
- docs/plan: plan, usage, test report, changelog; track docs/**/*.md

SQLite path: zero regression (typecheck clean, 249 passed / 6 skipped).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-23 19:13:04 +08:00

2.3 KiB
Raw Blame History

变更日志：PostgreSQL 记忆桥梁

关联：规划 · 使用说明 · 测试报告

本文件为该特性的聚焦式变更记录；面向用户的总览见仓库根 CHANGELOG.md 的 [Unreleased]。

[Unreleased] — PostgreSQL 可切换后端 + OpenClaw/Hermes 记忆桥梁

新增 (Added)

  • 可切换 PG 后端：QMD_BACKEND=pg 时改用 PostgreSQL，SQLite 仍为默认且行为不变。后端工厂集中在 src/pg/。
  • PG 记忆存储（src/pg/）：
    • schema 引导（content / documents / content_vectors / llm_cache / store_collections / store_config，均带 namespace 列）。
    • pgvector 向量列 + HNSW vector_cosine_ops 索引（替代 sqlite-vec vec0）。
    • pg_jieba + pg_trgm 的 tsvector 全文/中文分词与模糊匹配（替代 FTS5）。
  • 命名空间隔离：所有读写按 namespace（openclaw / hermes / …）过滤，使多 agent 共用同一 PG 记忆库而互不串扰。
  • MCP 记忆工具：memory_add / memory_search / memory_get（src/mcp/server.ts），让 OpenClaw、Hermes 通过 qmd MCP 写入与检索记忆。
  • CLI：qmd pg status（连接/扩展/健康探测）与 memory 子命令（src/cli/pg-commands.ts、src/cli/qmd.ts）。
  • 连接配置：QMD_PG_URL / DATABASE_URL / qmd config，支持 postgresql.svc.plus 的 stunnel TLS（5443 / sslmode）。
  • 测试：test/pg-config.test.ts（配置解析）、test/pg-memory.integration.test.ts（门控 QMD_PG_URL 的集成用例）、test/pg-compose.yml（本地 PG 编排）。
  • 文档：docs/plan/ 下规划、使用说明、测试报告与本变更日志。

变更 (Changed)

  • package.json：新增 pg 运行时依赖（Bun 与 Node 均可用）。
  • CLAUDE.md：补充 PG 后端与记忆桥梁说明。
  • .gitignore：放开 docs/**/*.md，纳入嵌套文档目录。

不变 (Unchanged)

  • 默认 SQLite 路径（~/.cache/qmd/index.sqlite）的索引、检索与所有 CLI/MCP 行为零回归。

已知限制 (Known limitations)

  • PG ts_rank 与 FTS5 BM25 打分语义不同，排序存在差异（RRF + reranker 缓解）。
  • 集成测试需外部 PostgreSQL；尚未对接真实实例常态化执行（见测试报告 §5）。