Memory Agent

编辑部 2026-06-07T09:03:55.636407 30995 阅读 tech

Memory Agent — 使用本帖使用社区开源推广，符合推广要求。我申明并遵循社区要求的以下内容：我的帖子已经打上开源推广标签：是我的开源项目完整开源，无未开源部分：是我的开源项目已链接认可 LINUX DO 社区：是 / 否我帖子内的项目介绍，AI生成、润色内容部分已截图发...

Memory Agent — 使用

本帖使用社区开源推广，符合推广要求。我申明并遵循社区要求的以下内容：

我的帖子已经打上开源推广标签： 是
我的开源项目完整开源，无未开源部分： 是
我的开源项目已链接认可 LINUX DO 社区： 是 /
推荐阅读
[Apple] iPhone air 和 iPhone17 同价，都是 5000 元，你会选哪一个

推荐阅读
红魔姜超谈新品 PAD：目前内部还没定具体发布日期，但本月上市目标没有变

否
我帖子内的项目介绍，AI生成、润色内容部分已截图发出： 是
以上选择我承诺是永久有效的，接受社区和佬友监督： 是

以下为项目介绍正文内容，AI生成、润色内容已使用截图方式发出

说明书

版本：0.1.0 · 数据格式：JSON · 依赖：Python 3.8+ · 零外部包依赖（CLI 模式）

1. 概述

Memory Agent 是一个本地运行的 AI 记忆系统。它替 LLM 记住跨会话的信息，实现"上次说过的事，下次还记得"。

核心概念

┌─────────────────────────────────────────────────┐
│                    记忆系统                        │
│                                                   │
│  工作记忆 (Working Memory)                        │
│  └─ LLM 上下文窗口，每次会话自动携带               │
│                                                   │
│  情景记忆 (Episodic Memory)                       │
│  └─ 每次对话的摘要，存为 .json 文件                │
│     路径: .memory/episodic/sess-时间戳.json        │
│                                                   │
│  语义记忆 (Semantic Memory)                       │
│  └─ 跨会话提炼的规律/知识，带置信度打分            │
│     路径: .memory/semantic/km-随机id.json          │
└─────────────────────────────────────────────────┘

三种使用方式

方式调用方式适合场景 Skill Claude Code 自动触发当前会话内，AI 自己管理记忆 CLI python3 memory.py <命令> 终端直接操作，脚本集成 MCP 任何 MCP 客户端调用 Claude Desktop / Cursor 等外部工具

所有方式共享同一个 .memory/ 数据目录。

2. 快速开始

2.1 安装

项目在 .claude/skills/memory-agent/，已就绪。

2.2 测试存储与检索

# 进入工作目录
cd /storage/emulated/0/Download/ces

# 存储一条会话摘要
python3 .claude/skills/memory-agent/scripts/memory.py store session '{
  "summary": "讨论了 SaaS 产品的定价策略",
  "tags": ["商业模型", "定价策略", "SaaS"],
  "key_points": [
    "建议采用 usage-based + tiered 混合定价",
    "用户对封顶价格敏感"
  ],
  "decisions": ["最终选择 usage-based 方案"]
}'

# 存储一条知识条目
python3 .claude/skills/memory-agent/scripts/memory.py store knowledge '{
  "content": "该用户群体偏好 usage-based 定价，对封顶价格敏感",
  "tags": ["定价策略", "客户画像"],
  "confidence": 0.7
}'

# 查询
python3 .claude/skills/memory-agent/scripts/memory.py query --tag 定价策略 --limit 5

# 查看统计
python3 .claude/skills/memory-agent/scripts/memory.py stats

2.3 在 Claude Code 中触发

在当前会话中，对 AI 说以下话就可以触发记忆操作：

"帮我把刚才的讨论记住"
"之前聊过什么关于定价的话题"
"看看记住了什么"
"这个方案用户采纳了，记一笔"

AI 会自动执行对应的存储/查询/统计操作。

2.4 启动 MCP 服务

本 MCP 服务通过 .mcp.json 注册，由支持 MCP 协议的工具自动拉起。

配置已在 .mcp.json 中：

"memory-agent": {
  "command": "python3",
  "args": [".claude/skills/memory-agent/scripts/memory_mcp.py"]
}

不需要手动启动。当 MCP 客户端（如 Claude Desktop）启动时，会自动拉起这个进程。

3. 集成方式

3.1 方式一：Claude Code Skill（自动模式）

已注册在 .claude/skills/memory-agent/SKILL.md。

触发条件：

你说 AI 会 “帮我记住…” 工作流 A → 生成摘要 → 存情景记忆 “之前说过…” 工作流 B → 查询记忆 → 注入上下文 “总结一下/学习这些” 工作流 C → 批量提炼 → 存语义记忆 “这个建议对不对” 工作流 D → 更新置信度 “看看记住了什么” 工作流 E → 显示统计和条目 “回顾一下历史” 工作流 B → 查询 → 列出相关记忆

深层用法：

"刚才关于定价的讨论，存一下。标签用：商业模型、定价策略"
"之前我问过关于获客的问题，答案是啥？"
"从这些对话里提炼一下用户的行为模式"

3.2 方式二：CLI 命令行（手动/脚本模式）

# 完整路径调用
python3 .claude/skills/memory-agent/scripts/memory.py stats

# 别名（建议）
alias mem="python3 $PWD/.claude/skills/memory-agent/scripts/memory.py"
mem stats
mem list --limit 10
mem query --tag 定价策略

在 shell 脚本中集成：

#!/bin/bash
# 每日自动总结
SUMMARY=$(cat <<'JSON'
{"summary":"每日工作日志","tags":["日报"]}
JSON
)
python3 .claude/skills/memory-agent/scripts/memory.py store session "$SUMMARY"

从文件读取数据：

python3 .claude/skills/memory-agent/scripts/memory.py store session ./my_summary.json

管道模式：

echo '{"summary":"来自管道的测试","tags":["测试"]}' | python3 .claude/skills/memory-agent/scripts/memory.py store session

3.3 方式三：MCP 协议（外部 AI 工具模式）

任何支持 MCP 的客户端可使用以下工具：

在 Claude Desktop 等工具中：

# 存储
调用 memory_store_session，参数：
  data: {"summary": "讨论了XX", "tags": ["商业模型"]}

# 查询
调用 memory_query，参数：
  tag: ["定价策略"]
  limit: 5

# 统计
调用 memory_stats，参数：{}

工具清单（共 7 个）：

工具名功能 memory_store_session 存会话摘要 memory_store_knowledge 存知识条目 memory_query 查询记忆 memory_list 列出条目 memory_get 获取详情 memory_stats 统计 memory_update_confidence 更新置信度

3.4 方式四：直接读文件（数据消费模式）

所有数据是纯 JSON，任何工具都能直接读：

import json, os

mem_dir = "/storage/emulated/0/Download/ces/.memory"

# 读所有情景记忆
for fname in os.listdir(f"{mem_dir}/episodic"):
    with open(f"{mem_dir}/episodic/{fname}") as f:
        data = json.load(f)
        print(data["summary"])

# 直接用 jq 查询
cat .memory/episodic/*.json | jq '[.summary, .tags]'

4. 数据格式详解

4.1 情景记忆（Episodic Memory）

每条对应一次会话。文件名为 sess-YYYYMMDD-HHMMSS.json。

字段说明：

字段类型必填说明 summary string

会话一句话概括 session_id string 自动格式 sess-20260528-143022 timestamp ISO 8601 自动时间戳 tags string 推荐标签，用于检索 user_intent string 用户的核心诉求 solution string 给出的方案 key_points string 关键信息点 decisions string 达成的决策 open_items string 待跟进事项 user_context object 用户画像（行业、规模、痛点等） feedback_score number 用户反馈评分（null=未评）

完整示例：

{
  "session_id": "sess-20260528-143022",
  "timestamp": "2026-05-28T14:30:22+08:00",
  "summary": "帮助用户设计 SaaS 分层定价方案",
  "user_intent": "寻找适合中小企业的定价模型",
  "solution": "推荐 usage-based + tiered 混合模型，设 soft cap",
  "key_points": [
    "用户团队 10-50 人",
    "竞争对手用 per-seat 定价",
    "用户对封顶价格敏感"
  ],
  "decisions": ["采用 usage-based 为主，年付可打折"],
  "open_items": ["需跟进 3 个月后的实施效果"],
  "tags": ["商业模型", "定价策略", "SaaS"],
  "user_context": {
    "industry": "SaaS/企业软件",
    "scale": "10-50人",
    "pain_points": ["获客成本高", "客户留存低"]
  },
  "feedback_score": null
}

4.2 语义记忆（Semantic Memory）

跨会话提炼的知识条目。文件名为 km-xxxxxxxx.json。

字段说明：

字段类型必填说明 content string

知识条目内容 knowledge_id string 自动格式 km-a1b2c3d4 confidence number 自动 0.0~1.0，初始 0.5 created ISO 8601 自动创建时间 updated ISO 8601 自动最后更新时间 tags string 推荐标签 source_sessions string 来源情景记忆的 ID applicable_scenarios string 适用场景

完整示例：

{
  "knowledge_id": "km-a1b2c3d4",
  "content": "该用户群体对 per-seat 定价接受度低，偏好 usage-based + soft cap 模式",
  "source_sessions": ["sess-20260527-xxx", "sess-20260520-xxx"],
  "confidence": 0.85,
  "created": "2026-05-20T08:00:00+08:00",
  "updated": "2026-05-28T14:30:00+08:00",
  "tags": ["定价策略", "客户画像"],
  "applicable_scenarios": ["SaaS 定价咨询", "新客户报价策略"]
}

5. 商业模型场景

5.1 客户画像管理

每次与某个客户交互后，存储包含 user_context 的会话摘要：

python3 memory.py store session '{
  "summary": "客户 A 的公司介绍与需求分析",
  "tags": ["商业模型", "客户画像", "客户A"],
  "user_context": {
    "company": "某 SaaS 公司",
    "industry": "企业软件",
    "scale": "10-50人",
    "pain_points": ["获客成本高", "客户留存低"],
    "budget_range": "中等",
    "decision_role": "创始人兼CTO"
  },
  "key_points": [
    "关注产品集成能力",
    "对 vendor lock-in 有顾虑",
    "预算需经过技术评估"
  ]
}'

之后查询：

# 找所有客户 A 的会话
python3 memory.py query --tag 客户A --limit 10

# 找所有 SaaS 客户的画像信息
python3 memory.py query --tag 客户画像 --tag SaaS --limit 20

5.2 定价策略追踪

记录每次定价讨论和结果：

python3 memory.py store session '{
  "summary": "定价方案讨论 - tiered vs usage-based",
  "tags": ["商业模型", "定价策略"],
  "key_points": [
    "讨论三种方案：纯 tiered、usage-based、混合",
    "用户倾向混合模式",
    "竞品 A 用 per-seat $29/月"
  ],
  "decisions": ["混合模式：基础 $99/月 + 用量计费"]
}'

当定价知识积累到 3+ 条后，提炼为语义记忆：

python3 memory.py store knowledge '{
  "content": "中小企业 SaaS 客户对 per-seat 定价接受度低，偏好 usage-based + tiered 混合",
  "tags": ["定价策略", "商业模型"],
  "confidence": 0.7,
  "source_sessions": ["sess-xxx", "sess-yyy"],
  "applicable_scenarios": ["新客户报价", "产品定价设计"]
}'

5.3 竞品情报积累

python3 memory.py store knowledge '{
  "content": "竞品 X：per-seat $29/月，集成能力弱，客户抱怨多",
  "tags": ["竞品情报", "竞品X"],
  "confidence": 0.6,
  "source_sessions": ["sess-xxx"]
}'

5.4 决策历史回溯

# 查用户做过的所有定价相关决策
python3 memory.py query --tag 定价策略 --tag 决策 --limit 20

# 查某个竞品的所有情报
python3 memory.py query --tag 竞品X --limit 10

5.5 推荐标签体系

标签用途 客户画像 行业、规模、痛点、预算、角色 定价策略 定价模型、价格敏感度 竞品情报 竞品对比分析 决策历史 做出的决策与结果 增长策略 获客、增长模型 商业模式 收入模型、成本结构 技术评估 技术栈、集成需求

自定义标签按需添加，用户/项目名等

6. CLI 命令大全

6.1 存储

# 存储会话摘要
python3 memory.py store session '<json字符串>'
python3 memory.py store session ./文件路径.json
echo '<json>' | python3 memory.py store session

# 存储知识条目
python3 memory.py store knowledge '<json字符串>'
python3 memory.py store knowledge ./文件路径.json

6.2 查询

# 按标签过滤（可多个）
python3 memory.py query --tag 定价策略 --tag SaaS
python3 memory.py query -t 定价策略 -t SaaS

# 按关键词搜索
python3 memory.py query --text "usage based 定价"

# 标签 + 关键词组合
python3 memory.py query --tag 商业模型 --text "SaaS" --limit 10

# 按时间范围
python3 memory.py query --since 2026-05-01

# 限制返回条数
python3 memory.py query --limit 5

6.3 列表

# 列出最近 20 条
python3 memory.py list

# 只列情景记忆
python3 memory.py list --type episodic

# 只列语义记忆
python3 memory.py list --type semantic

# 自定义条数
python3 memory.py list --limit 50

6.4 获取单条

python3 memory.py get sess-20260528-143022
python3 memory.py get km-a1b2c3d4

6.5 更新置信度

# 用户采纳了建议，加分
python3 memory.py update confidence km-a1b2c3d4 0.15

# 用户否定了，减分
python3 memory.py update confidence km-a1b2c3d4 -0.1

6.6 统计与维护

# 查看统计
python3 memory.py stats

# 重建索引
python3 memory.py reindex

# 查看帮助
python3 memory.py --help

7. MCP 工具大全

MCP 工具参数说明 memory_store_session data: string (JSON) 存会话摘要 memory_store_knowledge data: string (JSON) 存知识条目 memory_query tag: string, text: string, limit: number 查询记忆 memory_list type: “episodic” “semantic”, limit: number memory_get id: string (必填) 获取详情 memory_stats (无参数) 统计概览 memory_update_confidence id: string, delta: number (必填) 调整置信度

在 Claude Desktop 中使用

在 Claude Desktop 的 MCP 配置中添加：

{
  "mcpServers": {
    "memory-agent": {
      "command": "python3",
      "args": [".claude/skills/memory-agent/scripts/memory_mcp.py"]
    }
  }
}

之后在对话中可以直接说：

“帮我记住刚才的讨论”
“查一下关于定价策略的历史记录”
“看看记忆库有什么”

在 Cursor 中使用

在 Cursor 的 MCP 配置中添加同样内容，然后在 Composer 中叫：

“从 memory-agent 查一下相关记录”
“把这个讨论存到 memory”

8. 维护与故障排除

8.1 目录结构

.memory/                          # 记忆存储根目录
├── _index.json                   # 轻量索引（自动维护）
├── episodic/                     # 情景记忆
│   ├── sess-20260528-143022.json
│   └── sess-20260528-150100.json
└── semantic/                     # 语义记忆
    ├── km-a1b2c3d4.json
    └── km-e5f6g7h8.json

8.2 数据安全

数据是本地纯文本 JSON 文件。没有网络请求，没有外部依赖。

备份： 直接复制 .memory/ 目录
迁移： 设置 $MEMORY_DIR 环境变量指向新路径
清理： 直接删除文件或目录

# 设置自定义存储路径
export MEMORY_DIR=/sdcard/my-memory-data

# 备份
cp -r .memory .memory.backup-$(date +%Y%m%d)

# 查看存储位置
python3 .claude/skills/memory-agent/scripts/memory.py stats

8.3 常见问题

Q: memory.py 报 python3: command not found
A: 确认 Python 3 已安装：which python3

Q: 存储的 JSON 数据出现乱码
A: 确保 JSON 是 UTF-8 编码。单引号包裹的 JSON 字符串内部不要用未转义的单引号。

Q: MCP 服务连不上
A: 检查 .mcp.json 路径是否正确。python3 路径在 Termux 中为 /data/data/com.termux/files/usr/bin/python3。

Q: 如何清空所有记忆
A: rm -rf .memory/ 然后 python3 .claude/skills/memory-agent/scripts/memory.py reindex

Q: 如何跨设备使用
A: 把 .memory/ 目录传到另一台设备，设置同一 $MEMORY_DIR 路径即可。

Q: 数据量大了会慢吗
A: 每个记忆是一个独立文件。1000 条以内无性能问题。超过后可考虑定期归档旧数据。

8.4 最佳实践

标签要规范 — 相同的概念用相同的标签名（不要同时用"定价"和"定价策略"）
定期提炼 — 情景记忆积累到 5~10 条后，用工作流 C 提炼为语义记忆
置信度反馈 — 用户给出反馈后及时更新，让系统越用越准
合理使用"总结" — 不需要每次对话都存，重要决策/客户信息/关键知识才存
定期备份 — .memory/ 是整个系统的核心资产

9. 思维导图记忆（0.2.0 新增）

速查见项目根目录 README.md。

把"项目开发到哪了"存成思维导图式进度快照，开新窗口一眼看懂。三位一体表示：JSON（可检索）/ Unicode 树（终端看）/ Mermaid（渲染成真图）。

M=.claude/skills/memory-agent/scripts

# 存 / 更新项目快照（同名覆盖，不重复）
python3 $M/mindmap.py save '{
  "project":"X","progress":"60%","summary":"现状",
  "nodes":[{"label":"模块A","status":"done"},
           {"label":"模块B","status":"doing","note":"卡在Y",
            "children":[{"label":"子任务","status":"todo"}]}],
  "pitfalls":["坑"],"next":"下一步"
}'

python3 $M/mindmap.py show       # 渲染进度树（Unicode + emoji）
python3 $M/mindmap.py list       # 所有项目概览
python3 $M/mindmap.py mermaid    # 输出 Mermaid 源码 → 出思维导图图片
python3 $M/mindmap.py hook       # 输出 SessionStart hook JSON（供开窗自动召回）

status：done / doing / todo / bug / blocked
save 会自动同步一条语义记忆，memory.py query --tag 项目快照 可召回
快照文件落在 ~/.memory/mindmap/<项目名>.{json,md,mmd}

开窗怎么用

最省心:开新窗口敲一句 /memory-agent，skill 按工作流 D’ 自动 show 进度图（只靠 skill 加载，环境必支持）。

（可选）开窗零操作:在 ~/.claude/settings.json 配 SessionStart hook 运行 mindmap.py hook，新窗口启动自动注入进度图；环境不支持时回到 /memory-agent 即可。详见 README.md 与 SKILL.md 工作流 D’。

附录：文件路径参考

文件路径 CLI 脚本 .claude/skills/memory-agent/scripts/memory.py MCP 脚本 .claude/skills/memory-agent/scripts/memory_mcp.py Skill 指令 .claude/skills/memory-agent/SKILL.md 参考文档 .claude/skills/memory-agent/REFERENCE.md MCP 配置 .mcp.json 数据目录 .memory/

memory-agent.zip (28.9 KB)

Screenshot_2026-06-07-06-12-52-42_c5f0134a4c551757558202025a96fea6

Screenshot_2026-06-07-07-14-37-07_c5f0134a4c551757558202025a96fea6

3 个帖子 - 2 位参与者

阅读完整话题

来源: LinuxDo 最新话题查看原文

Memory Agent 使用本帖社区一个帖子参与者