上一篇我们说，长记忆让智能体从”函数”变成”有经历的主体”。这篇把那句话翻译成接口：你需要调用哪几个 API、数据怎么流、耗时操作交给谁。目标很具体——十分钟内，让你的 Agent 第一次”记住”一件事。

01先看清地图：五个核心 API

MemNet 把”模拟真实人类记忆”拆成五个动词，对应五个核心 API。它们覆盖了一条记忆从诞生到被想起的完整动作，命名即语义：

直觉上可以这样记：记忆 是写，回忆 是读，思考 与 做梦 是”在后台消化”，添加常识 是给记忆一张底图。前两个是同步的、面向每次对话的；后三个往往更重，适合异步调度——这就引出了下一组接口。

02核心之外：任务管理 API

“做梦”和”思考”不是毫秒级的事——它们要遍历、重组、调用模型去消化记忆。如果同步阻塞在一次对话里，延迟和成本都不可接受。因此平台在五个核心 API 之外，另提供一组任务管理 API，把这类耗时操作以异步任务的形式提交、查询与追踪：你提交一个”对该用户做一次梦境整合”的作业，拿到任务句柄，稍后查询状态与结果，而不让在线请求干等。

这也天然服务于可溯源：每一次后台整合本身就是一条带状态、带时间戳、可回查的任务记录，记忆”为什么变成现在这样”因此有据可依。

分工原则：核心 API 管”记忆本身”的读写，任务管理 API 管”记忆之上”的异步作业。在线链路只调前者，离线巩固交给后者。

说明：五个核心 API 的名称取自官方文档；任务管理类接口的最新端点与参数，请以 docs.memnetai.com 的 API 参考为准。下文代码为概念示意，方法签名同此。

0310 分钟最小闭环

一个能跑通的闭环只需要四步：初始化客户端 → 记忆 写入 → 回忆 检索 → 把检索结果喂回你的大模型。下面是 Python 与 Java 两种写法。

# pip install memnet  （包名以官方文档为准）
from memnet import MemNet

client = MemNet(api_key="sk-...", agent_id="my-companion")

# 1) 记忆：把这段对话写进长期记忆
client.memory(
    user_id="u_42",
    content="我家楼下开了家早餐店，还没去过，最近有点忙",
)

# 2) 回忆：在新一轮对话前，按当前语境联想检索
hits = client.recall(user_id="u_42", query="最近不知道早饭该吃什么", top_k=3)

# 3) 把记忆拼进提示，再交给你的 LLM
prompt = build_prompt(turn="最近不知道早饭该吃什么", memories=hits)
reply = your_llm.chat(prompt)   # → "你家楼下不是有家早餐店吗？"

// 引入官方 Java SDK（坐标以文档为准）
MemNet client = MemNet.builder()
    .apiKey("sk-...")
    .agentId("my-companion")
    .build();

// 记忆写入
client.memory("u_42",
    "我家楼下开了家早餐店，还没去过，最近有点忙");

// 回忆检索
List<Memory> hits = client.recall("u_42",
    "最近不知道早饭该吃什么", 3);

// 拼提示 → 调用你的模型
String prompt = PromptBuilder.with(turn, hits);
String reply = yourLlm.chat(prompt);

注意 recall 的 query 是”早饭吃什么”，而命中记忆的原文是”早餐店”——字面无重叠却被召回，这正是联想推理在接口层的体现，你不需要自己做关键词扩展。

04用早餐店把生命周期跑一遍

把上一篇的故事，对应到调用序列，整条记忆生命周期就清楚了：

1. 写入　memory(...) 记下”楼下开了早餐店，尚未尝试”。
2. 演变　后续交互与原记忆冲突时，平台标注“与源记忆冲突 · 已更正”，记忆版本随之更新。
3. 联想　recall("早饭吃什么") 在语义相关时刻主动命中该记忆。
4. 消化　通过任务管理 API 提交一次 做梦 作业，离线巩固这条偏好、衰减无关噪声。
5. 底座　必要时用 添加常识 注入”早餐时段/饮食偏好”等先验，让推理更稳。

05查询记忆演化路径

可溯源不是一句口号，而是一个能调用的能力。通过任务管理 API 查询某条记忆的演化路径，你会拿到一条带时间戳的时间线——它何时被写入、何时因冲突被更正、被哪次 recall 命中、又被哪次 做梦 巩固：

{
  "memory_id": "mem_8f2c",
  "summary": "用户家楼下新开早餐店，尚未尝试",
  "timeline": [
    { "t": "06-22 22:02", "op": "memory",  "note": "首次写入" },
    { "t": "08-02 20:18", "op": "update",  "note": "与源记忆冲突，已更正" },
    { "t": "08-09 08:11", "op": "recall",  "note": "由\"早饭吃什么\"联想命中" },
    { "t": "08-10 03:00", "op": "dream",   "note": "离线巩固为饮食偏好" }
  ]
}

当某次回答”凭记忆”出了错，你不必猜——沿着这条时间线往回走，就能定位是哪一步写入或联想引入了偏差。记忆可被使用，也可被解释，这是把它放进生产系统的前提。

06几条架构建议

1. ⇅

   同步 vs 异步，别混

   在线对话只调 记忆/回忆，保持低延迟；思考/做梦 一律走任务管理 API 异步跑，按用户活跃度或定时触发，别堵在请求里。

2. ▤

   先设计记忆域

   用 agent_id + user_id 划分记忆边界：多租户隔离、同一用户跨 Agent 共享、还是按场景分域，先想清楚再写，比事后迁移便宜得多。

3. ⊕

   它不替代 RAG，它在 RAG 之上

   RAG 管”知识查得到”，MemNet 管”这个用户/智能体记得住”。两者互补：文档检索交给 RAG，个性化长期记忆交给 MemNet，添加常识 还能给两边补一层先验。

4. ◉

   把演化日志当一等公民

   上线即开启路径记录，并接进你的可观测体系。记忆是会”生长”的状态，没有日志，调试和合规都无从谈起。

07结语

五个核心 API 给了记忆一套完整的动词，任务管理 API 让”消化记忆”这件重活退到后台，演化日志则把整个过程摊在阳光下。集成它不需要重写你的 Agent——只是在每次对话前后，加上一次 回忆 与一次 记忆，再把巩固交给离线任务。

从这一刻起，你的智能体不再每次都被重新初始化。它会记得那家早餐店，记得用户没去吃的原因，记得在恰当的时刻主动提起——而这，仅仅是它”持续进化”的第一步。