Agent Memory Skill

Agent Memory Skill

管理 5 个 SQLite 数据库，提供记忆的读写和六种检索策略。

数据库目录可通过 AGENT_MEMORY_DB_DIR 覆盖。未设置时，Windows 使用 C:\llwwds_file\memory\，macOS/Linux 使用 ~/Documents/memory/。

数据库路径

/
├── conversations.db   原始对话记录
├── events.db          事件（每个事件标签一条记录）
├── persona.db         用户画像（身份/偏好/目标/项目）
├── tools.db           工具链（设备/部署方式/手册）
└── pitfalls.db        踩坑记录（实验/规划任务中的设计缺陷与接缝问题）

核心规则

不支持物理删除

任何删除操作仅将 status 改为 不存在，原始数据永久保留。

标签多值规则

除 status 和时间戳外，所有标签列支持多值（JSON 数组）：

• device: ["win10pc", "macbook"]
• event: ["agentsqlmemory", "工具链搭建"]

增删改查前先查标签池

每个 db 有 tagpool 表维护可用标签值。操作前先用 --list-tags 查看。

---

检索策略（A-F，6 个独立脚本）

鼓励在一次搜索中综合使用多个方案。

A — 事件标签过滤

python scripts/search_event.py --event  [--db conversations] [--limit 50]

B — 内容关键词搜索

python scripts/search_content.py --q  [--db conversations] [--limit 50]

C — 跨层搜索（事件→对话）

python scripts/search_cross.py --q  [--limit 50]

D — 事件+内容联合搜索

python scripts/search_hybrid.py --event  --q  [--limit 50]

E — 多标签交叉搜索

python scripts/search_tags.py --db  [--event X] [--device Y] [--status Z] [--q 词] [--limit 50]

F — 反向关联检索

python scripts/search_related.py --id  [--limit 30]

---

pitfalls 踩坑记录

pitfalls 表专门存放在执行实验或规划好的工作任务过程中，发现的设计缺陷与接缝问题。它与 conversations/events 记的“做了什么、进展到哪”互补——pitfalls 记的是“哪里设计错了、下次别再踩”。

何时记（触发边界，防噪声）

只在满足以下条件时额外记一条 pitfalls，其余记录照旧写：

• 在跑实验或执行已规划任务的过程中，发现了设计缺陷或非平凡的接缝（上下游衔接）问题。
• 日常小 bug、语法错、一次就过的操作不记，否则记忆库会被噪声淹没。

六字段结构

| 列 | 含义 | |----|------| | scene | 场景：在哪个实验/任务里 | | stage | 具体环节，必须含上下游：出问题模块的输入来自谁、输出给到谁（多数缺陷在接缝处，不在模块内部） | | problem | 问题描述 | | root_cause | 归因，分两层：表层原因 + 根因（很多坑表层是 bug，根因是设计假设错了） | | solution | 解决方案 | | recur_signal | 复发信号：下次遇到什么特征就该想起这条（召回钩子） |

标签维度沿用其他表：event（关联事件名，多值）、device（多值）、status。

写入

python scripts/db_write.py --db pitfalls --action insert --data '{
  "scene":"...","stage":"上游X->本模块->下游Y","problem":"...",
  "root_cause":"表层:...;根因:...","solution":"...","recur_signal":"...",
  "event":["事件名"],"device":"macbook"}'

G — 强制读踩坑记录（召回规则）

pitfalls 表和其他表一样正常参与 A-F 检索（B 内容搜索、E 多标签、A 事件过滤都支持 --db pitfalls）。在此之上额外有一条强制召回规则：

> 当本轮任务命中/关联某个 event 时，动手前先用该事件名跑 search_pitfalls.py，把该事件下已知的坑读完，再开始操作。

# 默认：按事件名关联触发（已启用）
python scripts/search_pitfalls.py --event  [--limit 50]
# 备选设计（保留供后期对比测试）：任务开始全扫整张 pitfalls 表
python scripts/search_pitfalls.py --all [--limit 50]

两种触发方式的设计对比（后期可都实现再对比召回质量）：

• 按事件名关联触发（默认）：针对性强、噪声小；依赖 event 标签写对。
• 任务开始全扫（--all）：覆盖广、不漏；但可能读到与当前任务无关的条目。

---

综合搜索策略

| 用户意图 | 推荐方案 | |----------|----------| | 查某个项目的所有对话 | A（事件过滤） | | 不记得属于哪个项目 | C（跨层）→ D（精确命中） | | 搜项目内的特定话题 | D（事件+内容联合） | | 精准交叉过滤 | E（多标签） | | 找关联对话 | F（反向检索） | | 探索性搜索 | B（内容搜索） |

写入操作

# 插入
python scripts/db_write.py --db tools --action insert --data JSON
# 精确更新
python scripts/db_write.py --db tools --action update --id 3 --set JSON
# 软删除
python scripts/db_write.py --db tools --action delete --id 3

其他操作

python scripts/db_query.py --db tools --list-tags --column device
python scripts/db_init.py
python scripts/db_migrate.py --target persona [--dry-run]

工作流

对话开始时

1. 查询标签池：python scripts/db_query.py --db events --list-tags --column name
2. 拉取画像：python scripts/db_query.py --db persona --limit 50
3. 按需拉上下文：根据场景选择 A-F 搜索
4. 若本轮涉及实验/规划任务且命中某 event：先跑 search_pitfalls.py --event 读完已知坑再动手

对话结束时

1. 写 L0：python scripts/db_write.py --db conversations --action insert --data JSON
2. 更新事件：更新 events 的 overview/milestones
3. 工具链变更：更新 tools 表 status
4. 若本轮发现了设计缺陷/接缝问题：额外写一条 pitfalls（六字段），其余记录照旧

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: llwwds
• Source: llwwds/agent-memory-skill
• License: MIT

Install and usage instructions live in the source repository linked above.