pgmemrest

为 AI Agent / 应用提供基于 PostgreSQL RESTful API（PostgREST）的长期记忆服务。无需本地数据库部署，通过云上 PostgREST 端点即可实现记忆的存储、语义召回与管理。

准备

依赖	用途
Python 3.8+	本地部署 mem 服务
或 Docker	容器化部署 mem 服务
CloudBase PG 实例	PostgreSQL + PostgREST 远端端点

快速开始

第 1 步完成后，后续步骤可直接让 AI 根据本 README 自动完成。

1. 创建 CloudBase PG 实例

1. 购买云开发 CloudBase，开通 PG 实例。
2. 在 CloudBase 控制台获取 Env ID（envid） 和 API Key。
3. 进入 PG 控制台，创建数据库账号（如 root）。
4. 使用 DMC 登录，执行初始化建表 SQL：

begin;
create extension if not exists pgcrypto;
create extension if not exists vector;
createtableif not exists public.memories (
id uuid primary key default gen_random_uuid(),
user_id textnot null default 'default',
memory textnot null,
embedding vector,
created_at timestamptznot null default now(),
updated_at timestamptznot null default now()
);
createindexif not exists memories_user_id_created_at_idx
onpublic.memories (user_id, created_at desc);
create or replacefunctionpublic.add_memory(
p_user_id text,
p_text text
)
returns uuid
language plpgsql
security definer
set search_path = public
as $$
declare
v_id uuid;
begininsert intopublic.memories (
user_id,
memory
)
values (
coalesce(nullif(p_user_id, ''), 'default'),
p_text
)
returning id into v_id;
return v_id;
end;
$$;
create or replacefunctionpublic.add_memory_with_embedding(
p_user_id text,
p_text text,
p_embedding vector
)
returns uuid
language plpgsql
security definer
set search_path = public
as $$
declare
v_id uuid;
begininsert intopublic.memories (
user_id,
memory,
embedding
)
values (
coalesce(nullif(p_user_id, ''), 'default'),
p_text,
p_embedding
)
returning id into v_id;
return v_id;
end;
$$;
create or replacefunctionpublic.search_memories(
query_embedding vector,
match_user_id text,
match_count integer default 5
)
returns table (
id uuid,
memory text,
user_id text,
created_at timestamptz,
updated_at timestamptz,
score double precision
)
language sql
stable
security definer
set search_path = public
as $$
selectm.id,
m.memory,
m.user_id,
m.created_at,
m.updated_at,
1- (m.embedding<=> query_embedding) as score
frompublic.memories m
wherem.user_id= match_user_id
andm.embeddingis not nullorder bym.embedding<=> query_embedding
limit greatest(match_count, 1);
$$;
create or replacefunctionpublic.delete_memory(
p_memory_id uuid
)
returns boolean
language plpgsql
security definer
set search_path = public
as $$
begindeletefrompublic.memorieswhere id = p_memory_id;
return found;
end;
$$;
altertablepublic.memories enable row level security;
do $$
begin
if not exists (
select1from pg_policies
where schemaname ='public'and tablename ='memories'and policyname ='memories_select_service_role'
) then
create policy memories_select_service_role
onpublic.memories
for select
to service_role
using (true);
end if;
end;
$$;
-- 最小权限说明：PostgREST 需要以 db-service_role-role 解析 public.memories 和 public.* RPC，-- 因此 schema usage 是命名空间访问权限，不是表读写权限；没有它对象级 grant 仍可能不可用。grant usage on schema public to service_role;
-- GET /memories 只需要 SELECT；不授予 INSERT/UPDATE/DELETE 表权限。grantselectonpublic.memories to service_role;
-- POST /rpc/* 只需要对应函数 EXECUTE；写入/删除由 SECURITY DEFINER 函数内部完成。grant execute on function public.add_memory(text, text) to service_role;
grant execute on function public.add_memory_with_embedding(text, text, vector) to service_role;
grant execute on function public.search_memories(vector, text, integer) to service_role;
grant execute on function public.delete_memory(uuid) to service_role;
notify pgrst, 'reload schema';
commit;

初始化 SQL 执行完成后，CloudBase 会自动生成 PostgREST RESTful API 端点。

2. 安装插件

npx pg-memory-rest

安装过程中会交互式询问:

• CloudBase Env ID
• CloudBase API Key

插件会自动完成:

1. 拷贝插件到 ~/.pg/extensions/memory-postgrest/
2. 写入 ~/.pg/pg.json 配置
3. 部署 mem 服务（默认 pip + 本地启动，Docker 用户加 --docker）

Docker 部署（可选）

npx pg-memory-rest --docker

要求 Docker 已安装且正常运行。

3. 重启 gateway

pg gateway restart

4. 验证

# 检查插件状态
pg plugins list | grep memory-postgrest
# 查看 mem 统计
pg pgmem stats
# 测试搜索
pg pgmem search "test"

配置

安装后可通过 pg config 调整配置：

# CloudBase 认证
pg config set plugins.entries.memory-postgrest.config.apiKey "<API_KEY>"
pg config set plugins.entries.memory-postgrest.config.envId "<ENV_ID>"# PostgREST 地址（默认由 envId 自动拼接，可覆盖）
pg config set plugins.entries.memory-postgrest.config.postgrestUrl "<URL>"# 自动召回
pg config set plugins.entries.memory-postgrest.config.autoRecall true# 自动捕获
pg config set plugins.entries.memory-postgrest.config.autoCapture true

架构

Agent / 应用
│
├── memory_store / memory_recall / memory_forget (工具调用)
│
▼
pg-memory-rest 插件
│
├── 本地 mem (pip 或 Docker)
│ │
│ ▼
└── PostgREST ──→ CloudBase PostgreSQL

• mem 服务：本地 HTTP API，负责记忆语义搜索与增删
• PostgREST：CloudBase 自动生成的 RESTful API，转发 SQL 操作
• Embedding：由 pg 运行时通过请求头传入，无需手动配置

卸载

pg plugins uninstall memory-postgrest

License

MIT