MemArk

MemArk 是面向 AI Agent 与大模型应用的 Java-native 记忆基础设施。它为应用提供一个持久、可检索、可审计的记忆层，可以接入个人助手、Agent Runtime、工作流引擎、客服系统和任何需要长期上下文的 AI 产品。

MemArk 将对话输入转化为结构化记忆操作，通过 PostgreSQL 与 pgvector 存储和检索语义记忆，并提供一组紧凑的 HTTP API 覆盖写入、读取、语义搜索、更新、删除、历史记录和重置。项目定位是生产级开源基础设施：API 明确、存储可控、模型 provider 可替换、数据库 schema 由 migration 管理，并且代码组织天然适配 Java 与 Spring 生态。

为什么选择 MemArk

现代 AI 产品需要的不只是把历史消息塞进 prompt，而是一个能够判断哪些信息值得保留、在合适时机检索正确上下文、并让记忆生命周期可观测的基础层。

MemArk 专注解决这个边界：

能力	说明
持久化记忆	基于 PostgreSQL 持久化用户、Agent 或运行级别的记忆
语义检索	通过 pgvector 余弦相似度进行语义检索
记忆生命周期	支持新增、列表、详情、更新、删除、重置和历史追踪
Provider 抽象	支持兼容 OpenAI 协议的大模型与向量模型 provider
本地开发路径	在没有外部模型凭证时可使用本地 fallback provider 验证流程
运维可观测性	提供脱敏运行配置、Flyway migration 和健康检查

适用场景

MemArk 适合希望把“记忆”做成独立服务，而不是散落在业务逻辑里的团队。

典型场景包括：

• 个人助手长期记住用户偏好、约束和反复出现的任务。
• 客服 Copilot 跨会话保留稳定的账号、需求和偏好上下文。
• Agent 平台按 user_id、agent_id 或 run_id 隔离和检索记忆。
• 企业 AI 服务需要可审计的记忆变更、显式删除和可控持久化。
• Java/Spring 系统希望拥有自己的记忆服务，而不是引入额外运行时。

架构路径

MemArk 的核心路径保持直接、清晰：

1. API 接收 chat messages 和可选 metadata。
2. Prompt provider 根据 MEMARK_PROMPT_LANGUAGE 选择中文或英文 prompt。
3. Memory extractor 将输入转换为候选事实。
4. Memory decision planner 根据已有记忆输出 ADD、UPDATE、DELETE 或 NONE。
5. Embedding provider 为新增或更新后的记忆生成向量。
6. PostgreSQL 存储记忆正文、metadata、embedding、软删除状态和历史记录。
7. Search 对 query 生成 embedding，并通过 pgvector cosine distance 排序返回结果。

生产存储使用 PostgreSQL + pgvector。Spring Boot 启动时会通过 Flyway 自动创建 vector 扩展、记忆表、历史表和常用过滤索引。默认配置保留本地 hash embedding 与启发式抽取 fallback，主要用于开发验证；生产部署建议显式配置 OpenAI-compatible provider。

快速开始

启动 pgvector PostgreSQL：

docker compose up -d postgres

启动服务：

export MEMARK_POSTGRES_JDBC_URL="jdbc:postgresql://localhost:5432/memark"
export MEMARK_POSTGRES_USERNAME="postgres"
export MEMARK_POSTGRES_PASSWORD="postgres"

export OPENAI_API_KEY="your-api-key"
export MEMARK_LLM_PROVIDER="openai"
export MEMARK_EMBEDDING_PROVIDER="openai"
export MEMARK_PROMPT_LANGUAGE="zh"

mvn spring-boot:run

默认端口是 8080。如果本机 8080 被占用：

mvn spring-boot:run -Dspring-boot.run.arguments="--server.port=8081"

配置

OpenAI-compatible 网关可以通过下面的变量替换：

export MEMARK_LLM_BASE_URL="https://api.openai.com/v1"
export MEMARK_EMBEDDING_BASE_URL="https://api.openai.com/v1"
export MEMARK_LLM_MODEL="gpt-4.1-nano-2025-04-14"
export MEMARK_EMBEDDING_MODEL="text-embedding-3-small"

阿里云百炼可以直接使用兼容 OpenAI 的协议。使用中国内地百炼时，aliyun-bailian 会默认解析到 https://dashscope.aliyuncs.com/compatible-mode/v1、qwen3.5-plus 和 text-embedding-v4；其他地域可以显式覆盖 base URL。

export DASHSCOPE_API_KEY="your-dashscope-api-key"
export MEMARK_LLM_PROVIDER="aliyun-bailian"
export MEMARK_EMBEDDING_PROVIDER="aliyun-bailian"

# Optional region overrides:
# export MEMARK_LLM_BASE_URL="https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
# export MEMARK_EMBEDDING_BASE_URL="https://dashscope-intl.aliyuncs.com/compatible-mode/v1"

常用运行参数：

变量	默认值	用途
MEMARK_POSTGRES_JDBC_URL	jdbc:postgresql://localhost:5432/memark	PostgreSQL JDBC 连接地址
MEMARK_POSTGRES_USERNAME	postgres	PostgreSQL 用户名
MEMARK_POSTGRES_PASSWORD	postgres	PostgreSQL 密码
MEMARK_LLM_PROVIDER	auto	大模型 provider 选择
MEMARK_EMBEDDING_PROVIDER	auto	向量模型 provider 选择
MEMARK_LLM_API_KEY	OPENAI_API_KEY / DASHSCOPE_API_KEY	大模型 provider API key
MEMARK_EMBEDDING_API_KEY	OPENAI_API_KEY / DASHSCOPE_API_KEY	向量模型 provider API key
MEMARK_LLM_BASE_URL	https://api.openai.com/v1	兼容 OpenAI 协议的大模型 base URL
MEMARK_EMBEDDING_BASE_URL	https://api.openai.com/v1	兼容 OpenAI 协议的向量模型 base URL
MEMARK_LLM_MODEL	gpt-4.1-nano-2025-04-14	大模型名称
MEMARK_EMBEDDING_MODEL	text-embedding-3-small	向量模型名称
MEMARK_PROMPT_LANGUAGE	en	Prompt 语言，支持 en 和 zh
MEMARK_DEFAULT_TOP_K	10	默认搜索结果数量
MEMARK_DEFAULT_THRESHOLD	0.0	默认搜索分数阈值
MEMARK_DUPLICATE_THRESHOLD	0.985	语义去重阈值

数据库

Flyway migration 位于 src/main/resources/db/migration。

核心表：

表	用途
memark_memories	存储记忆正文、元数据、pgvector 向量、时间戳和软删除状态
memark_memory_history	存储新增、更新和删除历史

当前 pgvector 查询使用 cosine distance：

order by embedding <=> cast(:embedding as vector)

API 示例

健康检查：

curl http://localhost:8080/api/health
curl http://localhost:8080/actuator/health

OpenAPI 文档：

curl http://localhost:8080/v3/api-docs
open http://localhost:8080/swagger-ui.html

写入记忆：

curl -X POST http://localhost:8080/memories \
  -H 'Content-Type: application/json' \
  -d '{
    "messages": [
      {"role": "user", "content": "I prefer concise technical summaries."}
    ],
    "user_id": "user-1",
    "metadata": {"source": "demo"},
    "infer": true
  }'

搜索记忆：

curl -X POST http://localhost:8080/search \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "concise summaries",
    "user_id": "user-1",
    "search_mode": "semantic",
    "top_k": 5
  }'

search_mode 支持 semantic、keyword 和 hybrid。默认是 semantic，保持向后兼容；hybrid 会融合 pgvector 语义分和 PostgreSQL full-text keyword 分数。

搜索支持高级 metadata filters。基础条件和逻辑组合可以混用，当前支持 eq、ne、in、nin、gt、gte、lt、lte、contains、icontains、AND、OR、NOT 和 wildcard *：

curl -X POST http://localhost:8080/search \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "technical summaries",
    "user_id": "user-1",
    "filters": {
      "source": {"eq": "demo"},
      "priority": {"gte": 5},
      "OR": [
        {"topic": {"icontains": "spring"}},
        {"topic": {"icontains": "postgres"}}
      ],
      "NOT": [
        {"status": {"eq": "archived"}}
      ]
    },
    "search_mode": "hybrid",
    "top_k": 5
  }'

读取、更新和删除：

curl 'http://localhost:8080/memories?user_id=user-1'

curl -X PUT http://localhost:8080/memories/<memory-id> \
  -H 'Content-Type: application/json' \
  -d '{"text": "I prefer concise, implementation-focused technical summaries."}'

curl http://localhost:8080/memories/<memory-id>/history

curl -X DELETE http://localhost:8080/memories/<memory-id>

主要端点

方法	路径	用途
GET	/api/health	健康检查
GET	/configure	查看脱敏后的运行配置
GET	/configure/providers	查看内置 provider 列表
POST	/generate-instructions	生成记忆抽取指令
POST	/memories	写入记忆
GET	/memories	按 user_id、agent_id 或 run_id 查询记忆列表
GET	/memories/{memory_id}	查询单条记忆
POST	/search	语义、关键词或混合记忆搜索
PUT	/memories/{memory_id}	更新单条记忆
GET	/memories/{memory_id}/history	查询记忆历史
DELETE	/memories/{memory_id}	删除单条记忆
DELETE	/memories	按标识符批量删除记忆
POST	/reset	重置 PostgreSQL 表

验证

运行测试：

mvn test

运行真实 pgvector 集成测试需要本机 Docker 可用：

mvn test -Dmemark.integration-tests=true -Dtest=PgVectorMemoryRepositoryIntegrationTest

服务启动后可以跑端到端 smoke test：

bash scripts/smoke-test.sh

如果服务不在默认端口：

BASE_URL=http://localhost:8081 bash scripts/smoke-test.sh

部署

复制环境变量样例：

cp .env.example .env

构建应用镜像：

docker build -t memark:local .

启动 PostgreSQL：

docker compose up -d postgres

本地运行服务：

mvn spring-boot:run

容器运行服务示例：

docker run --rm -p 8080:8080 \
  --env-file .env \
  --network host \
  memark:local

项目来源

MemArk 项目来源于 mem0。