# Agent Memory Skill

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-llwwds-agent-memory-skill-agent-memory-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [llwwds](https://agentstack.voostack.com/s/llwwds)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [llwwds](https://github.com/llwwds)
- **Source:** https://github.com/llwwds/agent-memory-skill

## Install

```sh
agentstack add skill-llwwds-agent-memory-skill-agent-memory-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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: ["agent_sql_memory", "工具链搭建"]

### 增删改查前先查标签池
每个 db 有 _tag_pool 表维护可用标签值。操作前先用 --list-tags 查看。

***

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

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

### A — 事件标签过滤
```bash
python scripts/search_event.py --event  [--db conversations] [--limit 50]
```

### B — 内容关键词搜索
```bash
python scripts/search_content.py --q  [--db conversations] [--limit 50]
```

### C — 跨层搜索（事件→对话）
```bash
python scripts/search_cross.py --q  [--limit 50]
```

### D — 事件+内容联合搜索
```bash
python scripts/search_hybrid.py --event  --q  [--limit 50]
```

### E — 多标签交叉搜索
```bash
python scripts/search_tags.py --db  [--event X] [--device Y] [--status Z] [--q 词] [--limit 50]
```

### F — 反向关联检索
```bash
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`。

### 写入
```bash
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`，把该事件下已知的坑读完，再开始操作。

```bash
# 默认：按事件名关联触发（已启用）
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（内容搜索） |

## 写入操作

```bash
# 插入
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
```

## 其他操作

```bash
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](https://github.com/llwwds)
- **Source:** [llwwds/agent-memory-skill](https://github.com/llwwds/agent-memory-skill)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-llwwds-agent-memory-skill-agent-memory-skill
- Seller: https://agentstack.voostack.com/s/llwwds
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.