开源免费 · 私有化部署 · v0.1 MVP

Shared Memory.
Unified Soul.

羽忆为您的所有 AI Agent 提供一个统一的、持久化的记忆层，部署在您自己的基础架构上，数据完全由您掌控，所有工具共享。

Java 21 + Spring Boot·PostgreSQL + pgvector·MCP / CLI / REST

memory-server

# Write a memory from any agent
$ curl -X POST https://memory.local/v1/memories \
    -H "Authorization: Bearer mk-..." \
    -d '{
  "content": "All API responses follow {code, message, data}",
  "memoryType": "project_rule",
  "scope": { "projectId": "p_demo" }
}'

{
  "code": "CREATED",
  "data": {
    "id": "mem_a1b2c3d4",
    "memoryType": "project_rule",
    "importance": 0.9,
    "status": "active"
  }
}

# Recall context for a task from any other agent
$ curl -X POST https://memory.local/v1/recall \
    -d '{ "task": "Implement user registration", "maxTokens": 2000 }'

面临的问题

AI 模型运行于记忆孤岛之中

封闭的生态

ChatGPT 记忆、Claude 记忆，每一个都是孤立的。你在一个工具中建立的知识永远无法被另一个工具使用。

上下文失忆

切换模型、切换客户端或者开始新会话，你所建立的一切都会消失。Agent 每次都在从零开始。

失去数据控制权

你无法审计存储了什么，无法精细删除指定记忆，也无法迁移数据。你的知识存放在别人的服务器上。

记忆在传统上常常作为依附于应用层面的一项产品特性存在。构建独立的基础设施层，才是解决数据持久化和跨模型协同的关键。

设计理念

主导每一个架构决策的六大原则

用户数据主权绝对优先

记忆只属于你。私有化部署、自主管理、支持全量导出和物理删除。无需任何外部账号。

显式控制一切自动化行为

第一阶段只在你允许时写入。自动写入必须是选择加入的，并且永远透明、可逆转。

记忆和历史是不同的事物

Stable Memory 存储提炼后的事实，History Recall 存储过程上下文。将二者混为一谈会严重破坏召回质量。

模型和宿主隔离

不绑定任何厂商原生的记忆 API。可以接入任何 LLM 或向量模型。某个 Agent 挂了，核心基础设施依然运转。

确定性上下文装配

系统召回管线会输出受 Token 预算约束的信息块，直接供大模型注入上下文，在机制上区别于传统文档检索。

闭环优先

优先交付最小可验证的全链路闭环。在经受考验的基础上渐进增加复杂度，而不是在未经验证的地基上堆砌特性。

冲突解决优先级模型：

数据主权›显式控制›双层隔离›模型中立›召回质量›极简实现

技术架构

六层架构，三条管线，极度稳定的 API

Layer 1客户端 / 智能体层Codex · Antigravity · Claude Desktop · IDE Agent · CLI

↓

Layer 2接入适配器层技能 · 工具 · MCP 服务器 · CLI · SDK

↓

Layer 3记忆编排器层

写入管线召回管线控制管线

↓

Layer 4记忆存储平面稳定记忆库 · 历史召回库 · 控制元数据

↓

Layer 5检索与排序层词法 · 向量 (pgvector) · RRF 融合 · Tag & Scope 过滤

↓

Layer 6存储基础设施层PostgreSQL · Redis · 对象存储 · TLS · 反向代理

极致轻薄的适配器

每个适配器只负责把用户意图映射为标准 API 调用。所有业务逻辑都在服务端闭环，接入新 Agent 只需新增适配器。

编排器负责判断与调度

第三层回答的是这值不值得存、该落哪一层、召回时什么能进上下文。它是调度中心，而不是单纯的数据库代理。

搜索链路支持优雅降级

向量检索和词法检索独立容灾。没有 Embedding Provider 就回退纯词法，zhparser 不可用也不会让整条管线失效。

核心设计

两种记忆，一套统一系统

稳定记忆

长期存在的高保真事实

preferenceproject_ruledecisionfactworkflowreferencesummary

低写入频率，高读取频率
版本化管理，每次变更都可追踪
状态机：active → archived / invalid → deleted
semantic_key 去重，避免记忆碎片化
importance ≥ 0.9 时不会被 Token 预算裁剪

历史召回

面向过程上下文，允许过期

task_summarydecision_tracesession_excerptrecent_progressincident_contextmeeting_note

以追加写入为主，不强调覆盖更新
支持 TTL 策略（30d / 90d / 365d / permanent）
结构约束更弱，更适合自由文本
召回权重更低，主要用来补充稳定记忆

Memory Judge 决定内容该去哪里

每次写入都会先过一条三阶段决策链。硬规则会最先执行，而且不能被 LLM 覆盖。模型只负责辅助判断，规则兜底永远存在。

硬规则防线

敏感内容、空输入、长度越界等规则先执行，而且不能被后续判断覆盖。

→

LLM Judge

输出结构化 JSON，校验置信度阈值；模型失败时会自动回退，不把主流程绑死在模型上。

→

规则兜底

管理员可配置规则表，补足关键词分类、importance 默认值和 semantic_key 推断。

召回编排器

召回不是搜索，而是上下文工程

Recall Orchestrator 会经过八个步骤，最终生成 RecallContextBlock。它不是简单的检索结果列表，而是已经压缩、去重、受 Token 预算约束、可以直接注入 Agent 上下文的记忆块。

1候选召回稳定记忆与历史材料都走词法 + 向量混合召回

2统一打分综合 hybridScore、importance 与 recency 进行排序

3主序排序按综合分值降序处理候选集

4semantic_key 去重同一语义键只保留分值更高的版本

5冲突识别把 hasConflict 标记的结果前置暴露

6Token 预算分配根据 prefer 策略在稳定记忆和历史材料之间切分预算

7时效性提示超过 30/90/365 天的内容会附带新鲜度提示

8上下文块装配最终生成可直接注入模型上下文的 RecallContextBlock

按 prefer 模式分配 Token 预算：

ModeStableHistory

stable_first

70%

30%

history_first

30%

70%

balanced

50%

stable_only

100%—

API 参考

稳定、版本化的 REST 接口表面

所有接口统一返回 { code, message, data, httpStatus, timestamp } 结构。错误响应使用稳定的 MEM-* 业务码，而不是直接把 HTTP 状态文本暴露给接入层。

POST/v1/memories写入一条稳定记忆

// Request body
{
  "content": "All backend APIs return {code, message, data}",
  "title": "Response format convention",
  "memoryType": "project_rule",
  "scope": { "projectId": "p_demo" },
  "semanticKey": "p_demo:rule:api_response_format",
  "importance": 0.9
}

// Response 201
{
  "code": "CREATED",
  "data": { "id": "mem_a1b2c3d4", "status": "active", "version": 1 }
}

POST/v1/history-records写入一条历史材料

{
  "content": "Completed user auth module. MailCodeService handles TTL.",
  "recordKind": "task_summary",
  "scope": { "projectId": "p_demo" },
  "ttlPolicy": "365d"
}

错误码结构

MEM-AUTH*认证与授权错误

MEM-MEM*记忆读写错误

MEM-RECALL*召回管线错误

MEM-JUDGE*Judge / LLM Provider 错误

MEM-SEARCH*Embedding 与检索错误

MEM-SYS*系统与参数校验错误

部署

五分钟内跑通完整闭环

克隆部署仓库

git clone https://github.com/plumememory/memory-deploy
cd memory-deploy

配置环境变量

cp .env.example .env
# Set required variables:
MEMORY_BOOTSTRAP_ADMIN_USERNAME=admin
MEMORY_BOOTSTRAP_ADMIN_PASSWORD=change-me-now
POSTGRES_PASSWORD=your-db-password

启动整套服务

# Development
docker compose -f docker-compose.dev.yml up -d

# Production (with TLS via Caddy/Nginx)
docker compose -f docker-compose.prod.yml up -d

验证 MVP

bash verify-mvp.sh
# ✓ Write stable memory
# ✓ Write history record
# ✓ Task recall
# ✓ Cross-agent read
# ✓ Delete & temporary mode

包含内容

memory-server：Java Spring Boot 核心服务
memory-web：React 管理控制台
PostgreSQL 16 + pgvector + zhparser
Caddy / Nginx 反向代理示例

启用向量检索

MEMORY_EMBEDDING_ENABLED=true
MEMORY_EMBEDDING_API_KEY=sk-...
MEMORY_EMBEDDING_MODEL=text-embedding-3-small

启用 LLM Judge

MEMORY_JUDGE_LLM_ENABLED=true
MEMORY_LLM_API_KEY=sk-...
MEMORY_LLM_MODEL=gpt-4o-mini
MEMORY_LLM_BASE_URL=https://api.openai.com/v1

四仓库结构

Javamemory-server核心业务逻辑与 API

TSclient-sharedCLI + MCP Server 适配层

Reactmemory-web管理台与调试控制台

🐳memory-deployCompose 与代理配置

Shared Memory.Unified Soul.