Agent长期记忆库·跨会话用户偏好事实检索接入指南

Agent 长期记忆库 · 跨会话记忆层接入

## ⚠️ 先申请你自己的 API Key
本 Skill 不内嵌任何密钥,也不代付费用。 请到
算力集市 api.a7w.cn 注册并创建你自己的 API Key
(新用户有赠送点数,可以先免费试跑几条)。
拿到后填进环境变量 A7W_API_KEY,或直接传给 --key 参数。
请勿使用他人提供的 Key —— 用量与费用都记在 Key 所属账号上。

大模型本身没有记忆 —— 上下文一关,上次聊过的偏好、约束、决定全没了。
记忆层的活儿是:把「值得记住的事实」抽成结构化条目存好,下一轮用一句自然语言搜回来,
再拼进提示词。

它的价值是把记忆从业务代码里摘出来:不用自己设计记忆表结构、不用自己写
「这条新信息和旧记忆冲突了怎么办」的逻辑。而它背后要的那几次模型调用,
换成 api.a7w.cn 的 OpenAI 兼容入口,就是一个 base_url 的事。

你最关心答案
多少钱按 tokens 计费(点数/百万 tokens,输入输出分别计价),1 元 = 100 点;记忆写入比普通问答多几次调用
要多久同步链路,单次写入通常几秒;批次回填按量线性增长
要装什么什么都不用装。包里自带零依赖客户端,或者直接用 curl / 任意 OpenAI SDK
模型从哪来一个 base_url + 一个 Key,可调 75 个在架模型,换 model 就是换模型
能商用吗可以。生成内容的使用与合规责任由使用者承担

一、三分钟跑通

第一步:拿到你自己的 Key

到 api.a7w.cn 注册,创建一个 API Key(形如 sk-...),填进环境变量:

export A7W_API_KEY=sk-你的key      # Windows: $env:A7W_API_KEY="sk-你的key"

第二步:先用一条 curl 确认网关通

记忆层最终落到两次模型调用:一次抽取、一次问答。先确认这条链路能走通:

curl -sS -X POST "https://api.a7w.cn/api/v1/chat/completions" \
  -H "Authorization: Bearer $A7W_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "DeepSeek-V4-Flash",
    "messages": [{"role":"user","content":"把这句话抽成一条记忆:用户偏好深色模式和 vim 键位"}]
  }'

成功返回体形如 {"code":1,"msg":"success","data":{...choices...}}。
拿到 choices[0].message.content 就是一次可用的抽取结果。

第三步:把记忆层的模型入口指向它

任何兼容 OpenAI 协议的框架 / SDK,只改两个字段:

# 原来:base_url="https://api.openai.com/v1"
BASE_URL = "https://api.a7w.cn/api/v1"
API_KEY  = "sk-你的key"          # 同一把 Key 同时供抽取模型与向量模型使用

记忆层的三个角色都指向同一个入口:

角色走哪个接口怎么填
抽取模型(把对话抽成事实)POST /api/v1/chat/completionsmodel 填模型清单里的文本模型
回答模型(拿记忆生成回复)POST /api/v1/chat/completions可与抽取用不同模型,账单仍是同一份
向量模型(embedding)由框架的 embedder 配置项指定把 embedder 的 base_url 同样指向本网关

第四步:零安装客户端也能直接跑

python3 scripts/a7w.py whoami                       # 验证 Key
python3 scripts/a7w.py call chat completions \
  --body '{"model":"DeepSeek-V4-Flash","messages":[{"role":"user","content":"你好"}]}'

换模型只需改 model 字符串:不用换 base_url、不用换 Key、账单还是同一份。
想拿当前可用清单,读 GET /api/v1/models,或跑 python3 scripts/a7w.py apps。


二、包里有什么

sanjianke-agent-memory/
├── SKILL.md                    本文件
├── README.md
├── LICENSE.md
├── references/
│   ├── 记忆接入指南.md          作用域设计、写入节流、检索提准、批量回填
│   ├── api-openai-compat.md    OpenAI 兼容入口:base_url、鉴权、参数、流式、错误码
│   ├── api-apps-tasks.md       应用任务入口:/api/v1/apps/<应用>/<接口> 与异步生命周期
│   ├── getting-started.md      注册、领 Key、配置、配额与白名单
│   └── 通用说明.md              权限、计费口径、排错
└── scripts/
    └── a7w.py                  零依赖客户端(库 + 命令行,只用 Python 标准库)

零安装用法

export A7W_API_KEY=sk-你的key

python3 scripts/a7w.py whoami                     # 验证 Key 与可用插件数
python3 scripts/a7w.py apps                       # 列出全部能力
python3 scripts/a7w.py call chat completions \
  --body '{"model":"DeepSeek-V4-Flash","messages":[{"role":"user","content":"你好"}]}'

三、三种接入姿势

姿势 A:框架的配置项(最省事)

记忆类框架通常把「LLM 段」与「embedder 段」拆开配置,两段都指向同一个网关即可:

{
  "llm": {
    "provider": "openai",
    "config": {
      "model": "DeepSeek-V4-Flash",
      "base_url": "https://api.a7w.cn/api/v1",
      "api_key": "sk-你的key"
    }
  },
  "embedder": {
    "provider": "openai",
    "config": {
      "base_url": "https://api.a7w.cn/api/v1",
      "api_key": "sk-你的key"
    }
  }
}

具体键名以你所用框架的当前版本为准:Python 侧常见下划线(base_url、api_key),
TypeScript 侧常见驼峰(baseUrl、apiKey)。值都是同一个网关地址与同一把 Key。

姿势 B:只用 OpenAI SDK,自己管记忆读写

from openai import OpenAI

client = OpenAI(base_url="https://api.a7w.cn/api/v1", api_key="sk-你的key")

def extract(text: str) -> str:
    """把一段对话抽成一条可长期保存的事实。"""
    resp = client.chat.completions.create(
        model="DeepSeek-V4-Flash",
        messages=[
            {"role": "system",
             "content": "从对话中抽出一条最值得长期记住的用户事实,只输出这一条。"},
            {"role": "user", "content": text},
        ],
    )
    return resp.choices[0].message.content

def answer(question: str, memories: list) -> str:
    """把检索回来的记忆拼进 system prompt 再回答。"""
    system_prompt = (
        "你在回答时优先参考以下长期记忆;没有相关信息就正常回答。\n"
        + "\n".join("- " + m for m in memories)
    )
    resp = client.chat.completions.create(
        model="Qwen3.7-Plus",          # 与抽取用不同模型,账单仍是同一份
        messages=[
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": question},
        ],
    )
    return resp.choices[0].message.content

姿势 C:走应用任务入口

除了 OpenAI 兼容的大模型网关,平台还有一条应用任务入口,用于生成类能力
(语音、图像、视频、文档问答等 21 个应用):

# 看有哪些应用
python3 scripts/a7w.py apps

# 看某个应用有哪些接口、参数与真实价
python3 scripts/a7w.py schema voice_tts

# 调用(异步接口客户端会自动轮询到结束)
python3 scripts/a7w.py call voice_tts tts --body '{"text":"你好世界"}'

路径统一是 /api/v1/apps/<应用代号>/<接口代号>,两个代号都取自接口返回的
code 字段(是下划线,不是连字符)。不要拿平台返回的 endpoint_path 去拼 URL。


四、记忆工程要点

作用域:先把「谁记得谁」定清楚

维度典型取值说明
user_id用户 / 客户 ID最常用的隔离维度,必须与业务账号体系对齐
agent_id角色名同一系统里多个助手各记各的
app_id应用名多产品共用一套记忆服务时区分
run_id会话 / 工单 ID只在本轮对话内有效的事实

生成作用域 ID 的逻辑要收在一个函数里,别在两处手写 —— 写入用 user_id=A
而检索用 user_id=a,结果就是「明明存了却搜不到」。

写入节流:记忆是要花钱的

每次写入都是一次模型调用。只在高信息量事件上写:
偏好、决定、目标、新实体、约束条件。日常寒暄、确认语、纠错重述都不要写。

检索提准

  1. 检索必须带作用域过滤,别全库向量搜。
  2. top_k 从 3 起步,够用就别加 —— 召回太多会污染提示词,也更贵。
  3. 召回后按语义去重:加法式存储会让同一事实沉淀多条。
  4. 抽取值与检索值用同一套口径:同一个事实不要一半存原文、一半存抽取结果。

批量回填:把历史工单变成用户画像

已有历史工单 / 聊天记录时,按 user_id 分组、逐条抽取、批量写入。
写法与并发建议见 references/记忆接入指南.md。


五、常见坑

坑表现怎么避
拿 code == 0 判断成功明明成功却判成失败平台成功码是 1({"code":1,"msg":"success"})
把 Key 写进代码泄漏即等于余额泄漏Key 只从环境变量或 ~/.a7w/config.json 读;Key 等同于余额
两处作用域 ID 写法不一致写入成功但检索返回空作用域 ID 交给一个函数统一生成
每轮闲聊都写入账单和延迟一起涨只在偏好 / 决定 / 目标 / 新实体出现时写
把记忆库当业务数据库精确聚合与统计给不出结果精确查询交给 SQL;记忆层只做语义召回
把「本轮上下文」当「长期记忆」加了一层记忆反而更绕先确认需求是跨会话,再上记忆层
推理模型 token 先花在思维链上max_tokens 给小了会拿到空 content给推理类模型留足 max_tokens;思维链字段名在不同线路上是 reasoning / reasoning_content
网络抖动丢掉已付费的调用长任务轮询被重置连接自带客户端已做退避重试;自己写代码时同样加幂等与重试

六、计费

动作口径
记忆抽取(chat/completions)按 tokens 计,输入与输出分别计价
生成回复(chat/completions)同上;换模型即换单价
向量化由 embedder 配置的模型决定
应用任务类接口按各接口口径(点数/次、点数/分钟、点数/张等)
  • 1 元 = 100 点,1 点 = ¥0.01。
  • 先冻结、后结算:调用失败直接退款,异步任务失败冻结点数全额退回。
  • 平台同时给出标准价与租户价字段(tenant_*,平台侧报价),两者都未必等于实际结算价;以返回里的 data.usage.points_cost 为准;

每次返回的 data.usage 就是本次真实用量,可直接对账。

  • 实时查规则:先 python3 scripts/a7w.py apps 拿应用清单,再逐个 schema <app> 读 tenant_*。

省钱三件事:抽取用小模型、回答用好模型;只在高信息量事件上写入;
top_k 别开大。三件事做完,记忆层的成本通常比业务本身的推理成本低一个量级。


七、权限与边界

能力是否申请用途
网络访问申请调用 api.a7w.cn 的模型网关与应用接口(本 Skill 唯一的联网行为)
读取文件仅读取你指定的输入文件与 --json-file 请求体作为接口入参
写入文件仅在传入 --out 时保存返回的 JSON 或产物
凭证读取你自己提供的 API Key从环境变量或 ~/.a7w/config.json 读取
子进程 / 后台常驻不申请脚本执行完即退出,不注册服务、不常驻

不内嵌任何密钥。 请求只发往 api.a7w.cn,不发送到其他任何地址。

  • 不提供 Key、不代付费用:Key 必须你自己在 api.a7w.cn 申请
  • 不替代数据合规审查:把对话内容送去抽取之前,请自行确认符合你的隐私与合规要求
  • 不承诺模型清单:模型上下架频繁,调用前先读一次模型清单

关于这个 Skill

作者亲测实操后发布,下载后可直接使用,自用商用都可以。

所有 AI 能力都走 算力集市 api.a7w.cn —— 一把 API Key 打通
大模型、语音、图像、视频、数字人等全部算力,注册即送点数,按量计费、没有月费。

你可能想问答案
要不要额外部署不用。下载本包即可使用,不必去别处找源码
怎么开始到 api.a7w.cn 注册领 Key → 填进 A7W_API_KEY → 一条命令跑起来
能不能商用可以
遇到问题找谁见文末「联系我们」,作者本人答疑

使用中碰到任何问题 —— 报错、效果不理想、想省钱、想批量 —— 都欢迎加微信聊。
加好友时说一下是从哪个 Skill 找过来的,直接给你配套的示例。


联系我们

  • 技术微信:9872659 —— 加好友时说一下是从哪个 Skill 找过来的,直接给你配套的 API Key 与能跑的示例。
  • 要算力 / 要 API Key:算力集市 · 注册领 API Key —— 一个 Key 调用全部 AI 算力,注册、充值、创建 Key 都在这里。
  • 更多 AI 插件与接口:AI 插件市场。

相关链接

链接地址说明
算力集市 · 注册领 API Keyapi.a7w.cn一个 Key 调用全部 AI 算力;注册、充值、创建 Key 都在这
AI 插件市场aigc.a7w.cn浏览全部 AI 插件与接口说明
三剪客 · 一句话批量出片ks.a7w.cn短剧二创 / 影视解说 / 矩阵号批量混剪桌面客户端
视频超清 · 在线批量超分vr.a7w.cn网页版视频超分,批量处理,最高 4K
0人公司 · AI Agent 平台a7w.cn主站,了解整套 AI Agent 生态

同类文章