ArkMem

ArkMem 是一个面向 AI Agent 和 LLM 应用的 Java 原生长期记忆服务。它提供持久化记忆写入、层级作用域检索、PostgreSQL/pgvector 存储、结构化变更历史，以及 OpenAI-compatible 模型 Provider 接入。

项目边界保持清晰：ArkMem 只负责稳定记忆记录、可过滤元数据、语义检索和记忆生命周期。文件解析、文档切块、ACL、文档索引、外部数据连接器等能力应放在上游服务或独立组件中。

核心能力

能力	说明
记忆写入	支持 POST /memories，可直接写入或通过模型推理抽取
作用域	一等支持 user_id、agent_id、run_id
检索	支持语义、关键词、混合检索
生命周期	支持读取、更新、软删除、批量删除、历史记录、重置
存储	使用 PostgreSQL + pgvector，schema 显式初始化
Provider	支持 local、openai、openai-compatible、aliyun-bailian、auto
可观测性	支持 X-Request-Id、结构化错误、脱敏 HTTP 日志、/configure

架构

Client
  -> MemoryController
  -> MemoryService
  -> MemoryExtractor
       -> OpenAiLlmClient | HeuristicMemoryExtractor
  -> EmbeddingClient
       -> OpenAiEmbeddingClient | LocalHashEmbeddingClient
  -> PgVectorMemoryRepository
  -> PostgreSQL + pgvector

接口

Method	Path	说明
GET	/api/health	健康检查
GET	/actuator/health	Actuator 健康检查
GET	/v3/api-docs	OpenAPI JSON
GET	/swagger-ui.html	Swagger UI
GET	/configure	脱敏后的运行时配置
GET	/configure/providers	支持的 Provider
POST	/generate-instructions	生成记忆抽取指令
POST	/memories	创建记忆
GET	/memories	按作用域列出记忆
GET / POST	/memories/query	分页查询记忆，支持元数据过滤
GET	/exact/memories	读取精确层级作用域
GET	/memories/{memoryId}	读取单条记忆
PUT	/memories/{memoryId}	更新单条记忆
DELETE	/memories/{memoryId}	软删除单条记忆
DELETE	/memories	按作用域批量软删除
GET	/memories/{memoryId}/history	读取记忆历史
POST	/search	搜索记忆
POST	/reset	清空记忆表和历史表

POST /reset 会清空记忆表和历史表，只建议在开发环境或受控维护窗口使用。

快速开始

启动 PostgreSQL：

docker compose up -d postgres

初始化 schema：

docker exec -i arkmem-postgres psql -U postgres -d arkmem < src/main/resources/db/schema.sql

检查 src/main/resources/application-dev.yml 中的数据库和模型配置，然后启动服务：

mvn spring-boot:run

最小需要确认的 YAML 字段：

spring:
  datasource:
    url: jdbc:postgresql://127.0.0.1:5432/arkmem
    username: postgres
    password: postgres

arkmem:
  llm:
    provider: aliyun-bailian
    api-key: your-api-key
    base-url: https://llm-example.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
    model: qwen3-max
  embedding:
    provider: aliyun-bailian
    api-key: your-api-key
    base-url: https://llm-example.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
    model: text-embedding-v4

配置

ArkMem 的运行配置从 YAML 文件读取。开发环境通常修改 src/main/resources/application-dev.yml，发布环境通常修改 src/main/resources/application-release.yml。启动前确认数据库连接、数据库用户名、数据库密码，以及所选模型 Provider 的 key 和 base URL 即可。

YAML 路径	说明
spring.datasource.url	PostgreSQL JDBC URL
spring.datasource.username	PostgreSQL 用户名
spring.datasource.password	PostgreSQL 密码
arkmem.llm.provider	LLM Provider，常用 openai、openai-compatible、aliyun-bailian
arkmem.llm.api-key	LLM Provider API key
arkmem.llm.base-url	OpenAI-compatible chat base URL
arkmem.llm.model	Chat model
arkmem.embedding.provider	Embedding Provider，常用 openai、openai-compatible、aliyun-bailian
arkmem.embedding.api-key	Embedding Provider API key
arkmem.embedding.base-url	OpenAI-compatible embedding base URL
arkmem.embedding.model	Embedding model
arkmem.prompt.language	en 或 zh

设置 ARKMEM_API_INTERNAL_TOKEN 后，受保护接口接受以下任一认证方式：

Authorization: Bearer <token>
X-API-Key: <token>

请求示例

创建记忆：

curl -X POST http://localhost:19028/memories \
  -H 'Content-Type: application/json' \
  -d '{
    "messages": [
      {"role": "user", "content": "I prefer concise implementation-focused answers."}
    ],
    "user_id": "user-1",
    "metadata": {"source": "manual-curl"},
    "infer": false
  }'

读取记忆：

curl 'http://localhost:19028/memories?user_id=user-1'
curl 'http://localhost:19028/exact/memories?user_id=user-1&agent_id=chat-agent'
curl 'http://localhost:19028/memories/query?user_id=user-1&agent_id=chat-agent&source=manual-curl&limit=10&offset=0'

搜索记忆：

curl -X POST http://localhost:19028/search \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "runnable curl examples",
    "user_id": "user-1",
    "search_mode": "hybrid",
    "top_k": 5
  }'

元数据过滤

类型	操作符
等值	eq、ne
集合	in、nin
数值	gt、gte、lt、lte
文本	contains、icontains
存在性	exists、*
逻辑	AND、OR、NOT

Provider 解析

Provider	行为
local	使用启发式抽取和本地哈希向量
openai	使用 OpenAI chat completions 和 embeddings
openai-compatible	使用自定义 OpenAI-compatible 网关
aliyun-bailian	使用阿里云百炼 / MaaS OpenAI-compatible endpoint
auto	根据 YAML 中配置的 key 选择远程 Provider；没有 key 时回退到本地模式

OpenAI 配置示例：

arkmem:
  llm:
    provider: openai
    api-key: your-openai-api-key
    base-url: https://api.openai.com/v1
    model: gpt-4.1-nano-2025-04-14
  embedding:
    provider: openai
    api-key: your-openai-api-key
    base-url: https://api.openai.com/v1
    model: text-embedding-3-small

阿里云百炼 / MaaS 配置示例：

arkmem:
  llm:
    provider: aliyun-bailian
    api-key: your-bailian-api-key
    base-url: https://llm-example.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
    model: qwen3-max
  embedding:
    provider: aliyun-bailian
    api-key: your-bailian-api-key
    base-url: https://llm-example.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
    model: text-embedding-v4

验证

mvn test
mvn test -Darkmem.integration-tests=true -Dtest=PgVectorMemoryRepositoryIntegrationTest
bash scripts/smoke-test.sh

使用自定义服务地址运行 smoke test：

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

Docker

docker build -t arkmem:local .

docker run --rm \
  -p 19028:19028 \
  -v "$PWD/src/main/resources/application-dev.yml:/app/config/application.yml:ro" \
  arkmem:local

代码结构

路径	职责
src/main/java/io/arkmem/memory	记忆领域模型、服务、仓库、搜索和过滤
src/main/java/io/arkmem/memory/controller	记忆 HTTP API
src/main/java/io/arkmem/memory/llm	Prompt、LLM 抽取、本地降级抽取
src/main/java/io/arkmem/memory/embedding	Embedding clients
src/main/java/io/arkmem/api	OpenAPI、错误处理、HTTP 日志
src/main/resources/db/schema.sql	增量 schema
scripts/recreate-arkmem-schema.sql	破坏性 schema 重建脚本
src/main/resources/prompts	英文和中文 prompt 模板
scripts/smoke-test.sh	HTTP smoke test

项目来源

ArkMem 受到 mem0 长期记忆设计启发，并将核心思路适配为 Java 与 Spring Boot 服务。