Package Exports

opcode-pg-memory
opcode-pg-memory/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (opcode-pg-memory) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

opcode-pg-memory v3.11

OpenCode 长期记忆插件 — PostgreSQL + pgvector 跨平台记忆持久化 + 知识图谱

概览

PostgreSQL 驱动的记忆系统，通过 experimental.chat.system.transform 在每次 LLM 调用前自动注入相关历史记忆。含短时记忆层（零延迟）和长时记忆层（两路召回）。

能力	说明
短时记忆	当前会话的工具调用和消息缓存于内存 Map，30 分钟 TTL，零 PG 查询
双路召回	关键词 + 语义 pgvector ANN，混合评分，冷启动检测
21 个 MCP 工具	检索、反思、应用规则、时间线、知识语料库、会话日志
行为进化	hindsight_reflect → action_plan → apply_reflection → Active Rules 自动注入
知识图谱	从工具输出自动提取文件路径/函数/类/模块，构建 entities + relations 知识库
项目骨架	每次 LLM 调用前自动注入项目核心文件结构，Agent 零开销了解项目
记忆压缩	Observations 压缩为 output-first 叙事结构
噪声过滤	问候语/纯标点/重复字符 → 跳过入库
消息评分	`calculateMessageImportance()` 1-5 级，高价值保留更久
Agent 元认知	`<pg_memory>` 注入行为指南（>=80%/60-79%/<60% 分级）
韧性设计	PG 宕机不崩溃，内存缓冲 + 指数退避重试
跨平台	OpenCode / Claude Code / Cursor / Windsurf / Continue.dev

快速开始

bun install opcode-pg-memory@latest

配置 ~/.config/opencode/opencode.jsonc：

{
  "plugin": ["opcode-pg-memory"],
  "mcp": {
    "pg-memory": {
      "type": "local",
      "command": ["bun", "path/to/opcode-pg-memory/dist/mcp-server.js"],
      "enabled": true,
      "environment": {
        "PG_HOST": "localhost", "PG_PORT": "5432",
        "PG_DATABASE": "PGOMO", "PG_USER": "opencode",
        "PG_PASSWORD": "your_password",
        "PG_MEMORY_PLATFORM": "opencode"
      }
    }
  }
}

详细说明见 REFERENCE.md。

项目结构

opcode-pg-memory/
├── src/
│   ├── index.ts                     # 插件入口 (6 钩子)
│   ├── config.ts                    # 配置封装
│   │
│   ├── injection/                   # 注入引擎
│   │   ├── system-transform-injector.ts  # 两路召回 + 压缩 + 评分
│   │   ├── session-summary-writer.ts     # 会话摘要
│   │   ├── observation-scorer.ts         # 评分 + 经济学 + eval
│   │   └── observation-cleanup.ts        # 低价值清理
│   │
│   ├── hooks/                       # OpenCode 生命周期钩子
│   │   ├── tool-execute.ts          # 工具调用捕获 + 短时记忆
│   │   ├── message-updated.ts       # 消息捕获 + 噪声过滤 + 评分
│   │   ├── session-created.ts       # 会话创建
│   │   ├── session-completed.ts     # 会话完成
│   │   ├── session-compacting.ts    # 会话压缩
│   │   └── message-part-updated.ts  # 片段更新
│   │
│   ├── mcp/                         # 20 个 MCP 工具
│   │   ├── recall-memory.ts         # 多策略检索
│   │   ├── hindsight-reflect.ts     # 跨会话反思 + action_plan
│   │   ├── apply-reflection.ts      # [NEW] 应用规则到 rules.md
│   │   ├── import-document.ts       # [DEPRECATED] 文档导入
│   │   ├── timeline.ts              # 时间线
│   │   ├── get-memory.ts            # 单条详情
│   │   ├── delete-memory.ts         # 隐私删除
│   │   ├── knowledge-corpus.ts      # 7 工具 (build/query/list/rebuild/delete/prime/reprime)
│   │   ├── session-logger.ts        # 4 工具 (start/log/end/search)
│   │   ├── backfill-embeddings.ts   # 向量回填
│   │   └── sync-health.ts           # 健康检查
│   │
│   ├── services/                    # 服务层
│   │   ├── entity-extractor.ts      # [NEW] 从工具输出提取实体（纯正则）
│   │   ├── entity-store.ts          # [NEW] 实体/关系去重存储
│   │   ├── short-term-memory.ts     # 短时记忆 (Map, 30min TTL, 50/会话)
│   │   ├── memory-buffer.ts         # PG 不可用时内存队列
│   │   ├── async-embedder.ts        # 异步 embedding
│   │   ├── logger.ts                # 日志
│   │   └── ...
│   │
│   ├── config.ts                     # 配置入口 (process.env 单例)
│   │
│   └── utils/
│       ├── embedding.ts             # Embedding 服务 (Ollama/OpenAI/DeepSeek)
│       └── token-budget.ts          # Token 预算
│
├── mcp-server.ts                    # MCP 服务器 (stdio + SSE + /health)
├── index.ts                         # 插件导出入口
├── tests/                           # 测试 (15 套, 121 个)
├── skills/                          # 3 Agent 技能
├── platform-templates/              # 5 平台 MCP 模板
└── docs/
    ├── REFERENCE.md                 # 完全参考手册
    ├── MAINTENANCE.md               # [NEW] 维护手册 (可调参数清单)
    ├── PLUGIN_DOCUMENTATION.md      # 架构详解
    └── USAGE_GUIDE.md               # 使用指南

配置

4 层优先级

process.env → ~/.opencode-pg-memory/.env
  → ~/.opencode-pg-memory/settings.json
  → ~/.config/opencode/pg-memory.jsonc
  → Zod 默认值

关键环境变量

PG_HOST=localhost           # PostgreSQL
PG_PORT=5432
PG_DATABASE=PGOMO
PG_PASSWORD=your_password
PG_MEMORY_PLATFORM=opencode # 平台标识
PG_MEMORY_LOG_LEVEL=info    # 日志级别

嵌入模型

EMBEDDING_PROVIDER=ollama   # 或 deepseek/openai
EMBEDDING_MODEL=qwen3-embedding:0.6b

数据流

用户消息
  → message-updated (噪声过滤 → 重要性评分 → 入库 + 短时记忆)

工具调用
  → tool.execute.before (记录入参)
  → tool.execute.after (记录出参 + 短时记忆)
  → PG 不可用 → enqueueObservation (内存队列, 30s 重试)

下次 LLM 调用
  → experimental.chat.system.transform
     短时记忆有数据? → 直接注入 (零 PG 查询)
     短时记忆空?     → 两路召回 (关键词 + 语义 pgvector)
     混合评分 → 压缩 → 元认知注入 → output.system[0]

MCP 服务器

# stdio (默认)
node dist/mcp-server.js

# SSE (独立进程)
node dist/mcp-server.js --transport sse --port 37777

# 健康检查
curl http://localhost:37777/health

开发

bun run typecheck     # strict:true 类型检查
bun run test          # 172 tests
bun run build         # 生产构建

License

GPL-3.0