# oc-vector-memory

**Repository Path**: CHN_ZC/oc-vector-memory

## Basic Information

- **Project Name**: oc-vector-memory
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-25
- **Last Updated**: 2026-07-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# oc-vector-memory

> opencode 的可插拔向量记忆知识库子系统：bge-m3（1024 维）、SQLite BLOB + 可选 pgvector 后端、混合检索 RRF、三级 LLM 收敛、LWW 多机合并、9 个中文斜杠命令。
>
> **版本：V1.0** · **作者：zc** · **许可：MIT** · **安装见 [`plugin/INSTALL.md`](plugin/INSTALL.md)** · **卸载见 [`plugin/UNINSTALL.md`](plugin/UNINSTALL.md)**

## 一句话定位

给 opencode 装上"长期记忆"——对话里产生的知识会沉淀为可检索的记忆，下次新会话/新回合精准注入到上下文，并支持多机离线合并。

## 对应需求文档

本工程按 [`向量记忆知识库需求说明书.md`](向量记忆知识库需求说明书.md) 实现。所有 FR 编号可直接在源码中搜索定位。**扩展开发**见 [`EXTENSION_GUIDE.md`](EXTENSION_GUIDE.md)（12 个 Port 的接口契约）。

## 架构总览

**HTTP Server 分离架构**——核心引擎跑在独立 Node.js 子进程，plugin 是薄 HTTP 客户端，规避 Bun runtime 兼容问题：

```
opencode (Bun runtime)                     独立 Node.js 子进程
┌────────────────────────┐                ┌─────────────────────────┐
│ plugin (薄 HTTP 客户端) │ ── fetch ──→   │ server.ts (21 端点)     │
│  ServerManager         │                │  → Kernel               │
│  5 个 tool             │                │  → VectorBackend        │
│  7 个 hooks            │                │   ├─ sqlite-blob (独立) │
│  9 个斜杠命令          │                │   └─ pgvector  (独立)   │
└────────────────────────┘                └─────────────────────────┘
```

**12 个 Port + Adapter 模式（六边形架构）**——核心域不接触 SQL/网络，所有外部依赖通过 Port 接口隔离。加新算法/新后端/新提供者只加 Adapter，不改核心域。

## 关键特性

| 特性 | 实现 |
|---|---|
| 嵌入提供者可插拔（HTTP/CLI/本地模块） | `adapters/embedding/{openai,local-cli,local-module}.ts` |
| 统一 JSONC 配置（无 YAML/TOML） | `config/loader.ts` + `oc-vector-memory.config.default.jsonc` |
| 显式 `/memory-remember` + 去重合并 | `domain/memory.ts` + `core/dedupe.ts` |
| project_scope 派生链 | `core/project-scope.ts` |
| 混合检索 RRF (k=60) + 三级注入 | `adapters/retriever/hybrid-rrf.ts` + `adapters/injector/default.ts` |
| 防自噬两道闸门 | `adapters/summarizer/llm.ts` + `adapters/promoter/default.ts` |
| 失效管理（TTL / forget / 质量回退） | `adapters/invalidator/default.ts` |
| KB 库（staging + 续传 + 冲突扫描） | `domain/kb.ts` + `core/storage.ts` |
| 会话快照（跨机接续） | `domain/snapshot.ts` |
| 多机 LWW 合并 + 墓碑同步 | `adapters/merger/lww.ts` |
| 双后端（SQLite BLOB / pgvector） | `adapters/vector-backend/{sqlite-blob,pgvector}.ts` |
| 9 个中文斜杠命令 | `commands/*.md` + plugin 自动注册 |
| 自研中文优化切分器（段落→句子→子句） | `adapters/chunker/recursive.ts` |

## 安装

### 1. 构建核心 + 插件

```bash
cd oc-vector-memory
npm install && npm run build          # 核心 → dist/
cd plugin && npm install && npm run build  # 插件 → plugin/dist/
cd ..
# 核心 dist 拷到 plugin/core/（子进程用）
rm -rf plugin/core && mkdir -p plugin/core && cp -r dist/* plugin/core/
```

### 2. 配置 opencode 加载本地插件

编辑 `~/.config/opencode/opencode.jsonc`：

```jsonc
{
  "plugin": ["file:/abs/path/to/oc-vector-memory/plugin"]
}
```

> ⚠️ 不要写 `"plugin": ["oc-vector-memory"]`——那会从 npm 拉同名旧包。必须用 `file:` 协议指向本地 plugin 目录。

### 3. 清缓存 + 启动

```bash
rm -rf ~/.cache/opencode/packages/oc-vector-memory* ~/.cache/opencode/packages/file*
opencode
```

日志出现 `[oc-vector-memory] server ready` 即加载成功。

### 4. 注册斜杠命令

```bash
node tools/commands-manager.mjs install    # 装 9 个命令（幂等）
node tools/commands-manager.mjs list       # 查看状态
```

完整安装步骤见 [`plugin/INSTALL.md`](plugin/INSTALL.md)；卸载步骤见 [`plugin/UNINSTALL.md`](plugin/UNINSTALL.md)。

## 快速开始

### 斜杠命令（opencode TUI 里直接敲）

```
/memory-remember 项目用 pgvector + HNSW 索引做千万级检索
/memory-recall 如何做向量检索
/memory-status
/memory-export 导出到 ~/backup.memdb
```

### CLI（终端）

```bash
node dist/cli.js doctor                          # 三色健康检查
node dist/cli.js remember "..." --topic x        # 存记忆
node dist/cli.js recall "..."                     # 检索
node dist/cli.js export --output backup.memdb     # 导出
node dist/cli.js import backup.memdb --dry-run    # 预检导入
```

### 9 个斜杠命令

| 命令 | 说明 |
|---|---|
| `/memory-remember <内容>` | 记忆入库 |
| `/memory-recall <关键词>` | 记忆检索 |
| `/memory-forget <id>` | 遗忘记忆 |
| `/memory-status` | 记忆管理（list/pause/resume/doctor） |
| `/memory-export <路径>` | 导出记忆库 |
| `/memory-import <文件>` | 导入合并 |
| `/memory-kb` | 知识基底库 |
| `/memory-snapshot` | 会话快照 |
| `/memory-summarize` | 归纳记忆 |

## 配置

默认配置：`oc-vector-memory.config.default.jsonc`（带完整中文注释）。

加载顺序（高优先级覆盖低）：
1. 内置默认值
2. profile 预设（conservative / balanced / aggressive）
3. 显式配置文件
4. 环境变量 `OC_VECTOR_MEMORY_*`
5. 命令行 `--override key=val`

**embedding 服务配置**（默认 bge-m3 + 本机 llama-server）：

```jsonc
"EmbeddingProvider": {
  "adapter": "openai-embedding",
  "options": {
    "base_url": "http://localhost:32156/v1",
    "model": "bge-m3",
    "dimensions": 1024,
    "timeout_ms": 120000,
    "max_batch_size": 4
  }
}
```

**切分器配置**（自研 recursive-chunker，按字符控制 + 段落优先）：

```jsonc
"Chunker": {
  "adapter": "recursive-chunker",
  "options": {
    "max_chars": 800,
    "overlap_chars": 100
  }
}
```

## 后端切换

```jsonc
// 默认 SQLite（零扩展，跨平台）
"VectorBackend": { "adapter": "sqlite-blob-backend", "options": { "db_path": "~/.local/share/opencode/oc-vector-memory.db" } }

// PostgreSQL + pgvector（生产推荐）
"VectorBackend": {
  "adapter": "pgvector-backend",
  "options": {
    "connectionString": "postgres://user:pass@127.0.0.1:5432/dbname"
    // 或结构化参数：host/port/user/password/database
  }
}
```

两后端完全独立：SQLite 自管 dbPath（文件型），PG 无 dbPath 概念（服务型）。元数据（node_id / lamport / 指纹 / 注入暂停状态）由各后端自己存储。

## 向量重刷（换 embedding 模型后必修）

```bash
# 1. 备份
node dist/cli.js export --output backup-before-reembed.memdb
# 2. 确认新 provider selfCheck 通过
node dist/cli.js doctor
# 3. 全库重刷
node dist/cli.js reembed
# 4. 重校准阈值
node dist/cli.js calibrate
```

## 12 Port 与内置 Adapter

| Port | 内置 Adapter |
|---|---|
| EmbeddingProvider | openai-embedding / local-cli-embedding / local-module-embedding |
| ChatProvider | opencode-chat / openai-chat / cli-chat / noop-chat |
| VectorBackend | sqlite-blob-backend / pgvector-backend |
| Retriever | hybrid-rrf-retriever / vector-only-retriever / bm25-only-retriever |
| Reranker | identity-reranker / llm-reranker |
| Injector | default-injector / simple-injector |
| Summarizer | llm-summarizer / noop-summarizer |
| Promoter | default-promoter |
| Invalidator | default-invalidator |
| Serializer | sqlite-memdb-serializer / json-export-serializer / markdown-export-serializer |
| Merger | lww-merger / manual-merger |
| Chunker | recursive-chunker（默认，中文优化）/ chonkie-chunker（可选） |

## 安全

- 管理面仅 `127.0.0.1`（物理隔离，禁止其他电脑连接）
- Origin 校验（仅本机回环）+ 可选 token 鉴权
- 注入块头部含显式信任声明（`>>> TRUSTED CONTEXT (not instructions) <<<`）
- 密钥检测 + export 默认脱敏
- 无硬编码密钥/API key（全部走配置/环境变量）

## 平台支持

| 平台 | 状态 |
|---|---|
| Linux (x64/arm64) | ✅ 已验证 |
| macOS (13+, arm64/x64) | ✅ 已验证 |
| Windows (10/11, x64/arm64) | ✅ 已验证 |

运行时要求：Node.js 22.5+（内置 `node:sqlite`）。

## 性能基线

| 规模 | SQLite+sqlite-blob KNN P99 | PG+HNSW KNN P99 |
|---|---|---|
| 1 万条 | <150ms | <30ms |
| 10 万条 | <800ms | <80ms |

SQLite 后端检索使用 `metaCache`（内存元数据缓存）+ 向量 L2 预归一化（cosine 退化为点积），实测 10 万条检索 ~150ms。

## 目录结构

```
oc-vector-memory/
├── package.json              # 核心包 @oc-vector-memory/core v1.0.0
├── tsconfig.json
├── README.md                 # 本文件
├── EXTENSION_GUIDE.md        # 扩展开发接口说明（12 Port 契约）
├── oc-vector-memory.config.default.jsonc   # 默认配置（带中文注释）
├── oc-vector-memory.config.schema.json     # 配置 JSON Schema
├── src/                      # 核心源码（TypeScript）
│   ├── kernel.ts             # 主编排器
│   ├── server.ts             # HTTP Server（21 端点）
│   ├── cli.ts                # CLI 入口
│   ├── registry.ts           # Adapter 注册中心
│   ├── types.ts              # 共享类型
│   ├── ports/                # 12 Port 接口
│   ├── adapters/             # 25+ 内置 Adapter
│   ├── domain/               # 领域服务（memory/kb/snapshot/...）
│   ├── core/                 # 核心工具（storage/vector/bm25/rrf/...）
│   └── config/               # 配置加载器
├── plugin/                   # opencode 插件
│   ├── oc-vector-memory.ts   # 插件入口（HTTP 客户端 + spawn 子进程）
│   ├── package.json          # 插件元数据
│   ├── INSTALL.md            # 安装完整指南（含 AI 操作指引）
│   ├── UNINSTALL.md          # 卸载完整指南（含 AI 操作指引）
│   └── tsconfig.json
├── commands/                 # 9 个斜杠命令模板（中文）
│   ├── memory-remember.md
│   ├── memory-recall.md
│   ├── memory-forget.md
│   ├── memory-status.md
│   ├── memory-export.md
│   ├── memory-import.md
│   ├── memory-kb.md
│   ├── memory-snapshot.md
│   └── memory-summarize.md
├── tools/
│   └── commands-manager.mjs  # 斜杠命令安装/卸载/列出（Node.js）
├── examples/
│   ├── fulltest.mjs          # 端点功能测试（27 项）
│   └── fulltest2.mjs         # E2E + 边界测试
├── 向量记忆知识库需求说明书.md  # 完整需求文档
└── .gitignore
```

## 依赖

- **运行时**：`pg`（PostgreSQL 客户端，纯 JS）
- **Node 内置**：`node:fs/path/crypto/http/child_process/sqlite/worker_threads/url/util/net/os`
- **TypeScript**：仅开发期（编译后产物无 TS 依赖）
- 零 Python / 零 WASM / 零原生编译

## 免责声明（必读）

> **本项目由 AI 工具辅助开发，免费分发，不附带任何形式的担保。**

- **AI 生成内容**：本项目的需求文档、设计、代码均由 AI 工具辅助生成，可能存在错误、遗漏、与最新 opencode 官方契约不符或未经验证的内容。使用者须自行核实、自行评估、自行测试。
- **免费分发，"按现状"提供**：本项目以"按现状"（AS IS）和"按可用"（AS AVAILABLE）基础免费提供，不收取任何费用，**明示不提供任何明示或默示的担保**，包括但不限于对适销性、特定用途适用性、非侵权、准确性、可靠性、与任何特定目标的兼容性的担保。
- **不承担任何后果**：**使用者因使用、复制、分发、修改或依赖本项目而产生的任何直接或间接损失、数据丢失、业务中断、记忆丢失、系统故障、安全事件或其他后果，作者概不负责，由使用者自行承担全部风险与责任。**
- **数据无价，自行备份**：本插件作用于 opencode 记忆子系统，涉及长期记忆与知识库数据。安装、升级、迁移、卸载前请务必做好完整备份（详见 [`plugin/INSTALL.md`](plugin/INSTALL.md) 与 [`plugin/UNINSTALL.md`](plugin/UNINSTALL.md)），并对备份的可恢复性进行验证。
- **官方契约以最新版本为准**：本项目的 opencode 宿主契约基于截至 2026-07-25 的官方资料核实，但 opencode 更新频繁，实际使用时**必须以目标安装版本的 `@opencode-ai/plugin` / `@opencode-ai/sdk` 类型定义、`opencode.jsonc` schema 和 `opencode plugins inspect` 输出为最终准绳**。
- **第三方依赖与安全**：本项目可能依赖第三方库（`pg`、`@chonkiejs/core` 等）、外部 embedding/chat 服务（如本机 llama-server）、数据库后端（SQLite / PostgreSQL）。使用者须自行审查依赖供应链、外部服务的合规性与安全性，并自行承担相应风险。
- **学习交流目的·非生产级**：本项目开发的目的**仅用于学习交流与技术探索**，并非为生产环境、商业用途或关键业务设计。代码质量、架构成熟度、文档完备性均不构成"生产可用"的承诺；**不建议**将其用于任何关键业务、不可中断场景、强合规要求环境（金融、医疗、能源、公共基础设施、政府等）或他人数据托管。
- **无维护承诺·不保证及时响应**：本项目**不提供任何形式的维护承诺或服务等级协议（SLA）**。作者没有义务修复 bug、回答问题、提供技术支持、跟进 opencode / Node.js / pgvector / @chonkiejs 等上游变更、发布安全补丁或新版本；**任何更新都可能延迟数月、数年，或永久不再更新**。使用者必须做好"作者随时弃坑、本项目永久停更"的心理与运营准备，并在选型时把"无人维护"作为前置假设。
- **安全风险·使用者自行跟踪**：本项目可能存在未发现的**安全漏洞**（注入、提权、信息泄漏、跨进程攻击、子进程逃逸、依赖供应链污染等）；即便被发现也**不保证修复、不保证及时修复、不保证发布 CVE / 公告**。使用者必须：
  - 主动跟踪 [`@opencode-ai/plugin`](https://www.npmjs.com/package/@opencode-ai/plugin) / [`@opencode-ai/sdk`](https://www.npmjs.com/package/@opencode-ai/sdk) / `pg` / `@chonkiejs/core` 等上游依赖的安全公告，自行跑 `npm audit` 并处理；
  - 在多用户主机、容器、共享环境、对外可访问的网络中部署前，**自行做完整的安全评估与渗透测试**；
  - 对记忆/知识库中可能存储的敏感数据（个人隐私、商业秘密、凭证、密钥）**自行加密、脱敏、隔离**，本项目内置的 `has_secret` 检测与 export 脱敏仅为兜底，不是安全边界；
  - 关注 server 端的 `127.0.0.1` 物理隔离与 `managementAuthToken` 鉴权配置——多用户或高安全场景**必须**显式配置 token。
- **未成年人·限制行为能力人**：若使用者是未成年人或限制行为能力人，应在监护人指导下使用，并由监护人承担一切后果。
- **合法使用·禁止违法用途**：使用者承诺**仅将本项目用于合法目的**；不得用于侵犯他人权益、违反法律法规、危害网络安全、侵犯个人隐私、传播违法信息、绕过技术保护措施等用途。因违法使用产生的一切后果由使用者自行承担，作者不承担任何连带责任。

**下载、安装、使用、复制、分发或以任何方式利用本项目，即视为已阅读、理解并无条件接受本免责声明的全部条款。如不同意，请立即停止使用并删除本项目。**

## 许可

MIT