pgmnemo

面向 LLM 代理的 PostgreSQL 溯源向量记忆扩展

概览

扩展包名版本分类许可证语言
pgmnemo0.12.1RAGApache-2.0SQL
ID扩展名BinLibLoadCreateTrustReloc模式
1900pgmnemopgmnemo
相关扩展vector vector pg_search pg_ai_query pg_later

SQL-only extension; requires pgvector.

版本

类型仓库版本PG 大版本包名依赖
EXTPIGSTY0.12.11817161514pgmnemovector
RPMPIGSTY0.12.11817161514pgmnemo_$vpgvector
DEBPIGSTY0.12.11817161514postgresql-$v-pgmnemopgvector
OS / PGPG18PG17PG16PG15PG14
el8.x86_64
el8.aarch64
el9.x86_64
el9.aarch64
el10.x86_64
el10.aarch64
d12.x86_64
d12.aarch64
d13.x86_64
d13.aarch64
PIGSTY 0.12.1
PIGSTY 0.12.1
PIGSTY 0.12.1
PIGSTY 0.12.1
PIGSTY 0.12.1
u22.x86_64
PIGSTY 0.12.1
PIGSTY 0.12.1
PIGSTY 0.12.1
PIGSTY 0.12.1
PIGSTY 0.12.1
u22.aarch64
PIGSTY 0.12.1
PIGSTY 0.12.1
PIGSTY 0.12.1
PIGSTY 0.12.1
PIGSTY 0.12.1
u24.x86_64
PIGSTY 0.12.1
PIGSTY 0.12.1
PIGSTY 0.12.1
PIGSTY 0.12.1
PIGSTY 0.12.1
u24.aarch64
PIGSTY 0.12.1
PIGSTY 0.12.1
PIGSTY 0.12.1
PIGSTY 0.12.1
PIGSTY 0.12.1
u26.x86_64
u26.aarch64

构建

您可以使用 pig build 命令构建 pgmnemo 扩展的 RPM / DEB 包:

pig build pkg pgmnemo         # 构建 RPM / DEB 包

安装

您可以直接安装 pgmnemo 扩展包的预置二进制包,首先确保 PGDGPIGSTY 仓库已经添加并启用:

pig repo add pgsql -u          # 添加仓库并更新缓存

使用 pig 或者是 apt/yum/dnf 安装扩展:

pig install pgmnemo;          # 当前活跃 PG 版本安装
pig ext install -y pgmnemo -v 18  # PG 18
pig ext install -y pgmnemo -v 17  # PG 17
pig ext install -y pgmnemo -v 16  # PG 16
pig ext install -y pgmnemo -v 15  # PG 15
pig ext install -y pgmnemo -v 14  # PG 14
dnf install -y pgmnemo_18       # PG 18
dnf install -y pgmnemo_17       # PG 17
dnf install -y pgmnemo_16       # PG 16
dnf install -y pgmnemo_15       # PG 15
dnf install -y pgmnemo_14       # PG 14
apt install -y postgresql-18-pgmnemo   # PG 18
apt install -y postgresql-17-pgmnemo   # PG 17
apt install -y postgresql-16-pgmnemo   # PG 16
apt install -y postgresql-15-pgmnemo   # PG 15
apt install -y postgresql-14-pgmnemo   # PG 14

创建扩展

CREATE EXTENSION pgmnemo CASCADE;  -- 依赖: vector

用法

来源:

pgmnemo 在 PostgreSQL 中存储 agent memory,并通过一个多模态计划结合 pgvector HNSW 搜索、BM25 风格文本匹配、图边邻近度、JSONB 元数据过滤、时间过滤和 outcome confidence 进行检索。它是 SQL-only 扩展,依赖 vector,安装到 pgmnemo schema;v0.12.1 control 文件中标记为 trusted,且不需要 superuser 权限。

v0.12.1 保留 v0.12.0 的 typed write API,并调整 guard_no_test_project():项目 ID 下限检查改为通过 pgmnemo.test_project_floor 显式开启;默认值 0 表示禁用该检查。

安装

CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS pgmnemo CASCADE;

SELECT pgmnemo.version();
SELECT * FROM pgmnemo.stats();

摄入 Lessons

SELECT pgmnemo.ingest(
  p_role        := 'developer',
  p_project_id  := 1,
  p_topic       := 'security',
  p_lesson_text := 'Rotate JWT signing keys after a key-compromise incident.',
  p_importance  := 4,
  p_embedding   := NULL,
  p_commit_sha  := 'abc1234',
  p_metadata    := '{"source":"incident-runbook"}'::jsonb
);

pgmnemo.ingest() 是基础写入路径。它会应用 provenance gate,在提供 embedding 时校验 1024 维度,按 pgmnemo.max_query_text_chars 截断过长 lesson 文本,并在存在来源信息时写入 verified_at

Provenance Gate

SHOW pgmnemo.gate_strict;

SET pgmnemo.gate_strict = 'enforce';
SET pgmnemo.gate_strict = 'warn';
SET pgmnemo.gate_strict = 'off';

pgmnemo.gate_strict = 'enforce' 时,缺少 commit_shaartifact_hash 的写入会被拒绝。warn 会接受写入但产生审计警告,off 则关闭 gate。

v0.12.1 的 test-project guard 需要显式开启:

SHOW pgmnemo.test_project_floor;  -- default 0
SET pgmnemo.test_project_floor = '1000000';

默认 0 表示禁用生产项目下限检查。测试框架如果保留低 project ID,可设置为正数。

召回

SELECT lesson_id, topic, lesson_text, score
FROM pgmnemo.recall_fast(
  '<1024-dimensional vector literal>'::vector(1024),
  10,
  'developer',
  1,
  'dag-2026-abc',
  ARRAY['note', 'fact']
);

SELECT lesson_id, topic, score, vec_score, bm25_score, rrf_score, match_confidence
FROM pgmnemo.recall_hybrid(
  '<1024-dimensional vector literal>'::vector(1024),
  'JWT rotation key compromise',
  10,
  'developer',
  1,
  0.4,
  0.4,
  60,
  'dag-2026-abc',
  ARRAY['note', 'fact']
);

当同时提供文本和 embedding,且 pgmnemo.disable_hybrid 为 false 时,recall_lessons() 会路由到 hybrid recall。exclude_dag_id 用于避免召回同一 workflow run 产生的记录,p_content_types 则过滤 typed memories。

召回函数默认会更新 last_recalled_at 并递增 recall_count。只读分析时可以关闭该副作用:

SET pgmnemo.track_recall_recency = 'off';

Locate 与 Expand

SELECT *
FROM pgmnemo.navigate_locate(
  NULL::vector(1024),
  'JWT rotation',
  2000,
  '{"topic":"security"}'::jsonb,
  1
);

SELECT *
FROM pgmnemo.navigate_locate_dispatch(
  query_text            := 'JWT rotation',
  content_type_dispatch := 'entity',
  project_id_filter     := 1,
  token_budget_chars    := 2000
);

SELECT *
FROM pgmnemo.navigate_expand_typed(
  ARRAY[1001, 1002]::bigint[],
  graph_expand_depth := 1,
  relation_types     := ARRAY['CAUSED_BY', 'DERIVED_FROM']
);

navigate_locate() 在字符预算内找候选 ID,再用 expand 函数只获取被选中 ID 的完整内容和图邻居。

Typed Writes

SELECT pgmnemo.canonical_slug('concept', 'JWT Rotation');

SELECT *
FROM pgmnemo.remember_fact(
  p_role            := 'developer',
  p_entity_key      := 'concept:jwt_rotation',
  p_property        := 'runbook',
  p_value           := 'Rotate signing secrets within 24 hours after compromise.',
  p_confidence      := 0.82,
  p_has_contact_pii := false,
  p_source_type     := 'agent_authored',
  p_project_id      := 1,
  p_commit_sha      := 'abc1234'
);

SELECT pgmnemo.remember_event(
  p_role        := 'developer',
  p_entity_key  := 'concept:jwt_rotation',
  p_event_label := 'incident_response',
  p_event_body  := 'Rotation procedure validated during the July drill.',
  p_project_id  := 1,
  p_commit_sha  := 'abc1234'
);

SELECT pgmnemo.remember_relation(
  p_role          := 'developer',
  p_from_key      := 'concept:jwt_rotation',
  p_to_key        := 'concept:key_compromise',
  p_relation_type := 'MITIGATES',
  p_project_id    := 1,
  p_commit_sha    := 'abc1234'
);

remember_fact() 会替换同一 entity/property 的旧 active fact,remember_event() 是 append-only,remember_relation() 写入关系记忆和图边。

图边、强化与维护

SELECT pgmnemo.add_edge(1001, 1002, 'CAUSED_BY', 0.85, '{"run_id":7320}'::jsonb);

SELECT pgmnemo.reinforce(1001, 'success');
SELECT pgmnemo.reinforce(ARRAY[1001, 1002]::bigint[], 'failure');

SELECT pgmnemo.reembed(1001, '<1024-dimensional vector literal>'::vector(1024));
SELECT pgmnemo.recompute_content(1001, 'Updated lesson text.');

常用设置包括 pgmnemo.gate_strictpgmnemo.include_unverifiedpgmnemo.ef_searchpgmnemo.disable_hybridpgmnemo.recency_weightpgmnemo.importance_weightpgmnemo.graph_proximity_weightpgmnemo.temporal_boostpgmnemo.confidence_boost_weightpgmnemo.track_recall_recencypgmnemo.max_query_text_charspgmnemo.tenant_idpgmnemo.test_project_floor

注意事项

  • PGXN 元数据声明 pgmnemo 依赖 vector >= 0.7.0
  • 当前 SQL 定义中的 embedding 预期为 1024 维。
  • 默认 provenance gate 是有意设计。迁移旧 memory 行时优先使用 warn,不要直接长期使用 off
  • 召回函数可能写入 recency 元数据;只读诊断时应关闭 pgmnemo.track_recall_recency

最后修改 2026-07-02: extension update 2026-07-02 (d4da20c)