gh-dwsy-ai-runtime-ai-runtime-memory/skills/memory/references/guides/tools.md

记忆系统工具详解

memory_cli.py - 命令行查询工具

核心功能

提供SQL风格的命令行接口，支持复杂条件查询情景记忆事件。

命令语法

python3 memory_cli.py query [选项...]

查询选项详解

--select 字段选择

# 选择特定字段
--select "id,timestamp,title"

# 默认选择（不指定时）
--select "id,timestamp,title"

--where 条件过滤

支持SQL风格WHERE条件，字段包括：

• id, type, level, title, date, timestamp
• tags (支持 CONTAINS 操作)

# 基础条件
--where "type='decision'"
--where "date>='2025-11-14'"
--where "tags CONTAINS 'architecture'"

# 组合条件
--where "date>='2025-11-14' AND tags CONTAINS 'decision'"
--where "type='meeting' OR type='decision'"

--order-by 排序

# 单个字段排序
--order-by "timestamp desc"
--order-by "date asc"

# 多个字段排序（暂不支持）

--limit / --offset 分页

--limit 20 --offset 0    # 第一页，20条
--limit 20 --offset 20   # 第二页，20条

--format 输出格式

--format table   # 表格格式（默认）
--format json    # JSON格式

使用示例

基础查询

# 查看所有事件
python3 memory_cli.py query

# 查看今天的事件
python3 memory_cli.py query --where "date='2025-11-14'"

高级查询

# 查找架构决策
python3 memory_cli.py query \
    --where "type='decision' AND tags CONTAINS 'architecture'" \
    --order-by "timestamp desc" \
    --limit 10

# 搜索错误事件
python3 memory_cli.py query \
    --where "type='error'" \
    --select "timestamp,title,tags" \
    --format table

时间范围查询

# 本周事件
python3 memory_cli.py query \
    --where "date>='2025-11-10' AND date<='2025-11-16'"

# 最近7天
python3 memory_cli.py query \
    --where "timestamp >= '2025-11-07T00:00:00'" \
    --order-by "timestamp desc"

memory_discovery.py - 编程接口

类概述

MemoryDiscovery 类

核心记忆发现和查询引擎。

MemoryEvent 类

单个记忆事件的索引信息数据类。

编程接口

初始化

from memory_discovery import MemoryDiscovery

# 初始化发现器
discovery = MemoryDiscovery("path/to/memory/root")

刷新索引

# 重新扫描episodic目录
discovery.refresh()

SQL风格查询

# 基础查询
events = discovery.query()

# 条件查询
events = discovery.query(
    where="date>='2025-11-14' AND tags CONTAINS 'architecture'",
    order_by="timestamp desc",
    limit=20,
    offset=0
)

格式化输出

# 表格格式
output = discovery.format_events(events, format_type="table")

# JSON格式
output = discovery.format_events(events, format_type="json")

# 自定义字段选择
output = discovery.format_events(
    events,
    select=["id", "title", "date"],
    format_type="table"
)

事件解析协议

时间推断顺序

1. YAML front matter timestamp/time 字段
2. 正文 ## 时间 段落第一行
3. 文件名模式 YYYYMMDD-HHMM.md
4. 文件名模式 YYYYMMDD.md
5. 文件修改时间 (mtime)

标签解析顺序

1. YAML front matter tags 数组
2. 正文 ## 标签 段落（逗号分隔）
3. 空数组（无标签）

标题解析顺序

1. YAML front matter title
2. 正文第一个 # 标题
3. 文件名（去除扩展名）

高级用法

自定义查询条件

# 复杂的标签组合查询
events = discovery.query(
    where="tags CONTAINS 'architecture' AND (tags CONTAINS 'decision' OR tags CONTAINS 'design')"
)

批量处理

# 分页处理大量事件
page_size = 50
all_events = []

for offset in range(0, 1000, page_size):  # 最多1000条
    batch = discovery.query(limit=page_size, offset=offset)
    if not batch:
        break
    all_events.extend(batch)

事件对象操作

# 访问事件属性
for event in events:
    print(f"ID: {event.id}")
    print(f"标题: {event.title}")
    print(f"时间: {event.timestamp}")
    print(f"标签: {event.tags}")
    print(f"类型: {event.type}")

    # 转换为字典
    event_dict = event.to_dict()

工具集成

Shell脚本集成

# 创建查询别名
alias memory-query="python3 .ai-runtime/memory/memory_cli.py query"

# 快速查看今天事件
memory-query --where "date='$(date +%Y-%m-%d)'"

Python脚本集成

#!/usr/bin/env python3
import sys
sys.path.insert(0, '.ai-runtime/memory')

from memory_discovery import MemoryDiscovery

def get_recent_decisions(days=7):
    import datetime
    cutoff = datetime.datetime.now() - datetime.timedelta(days=days)

    discovery = MemoryDiscovery('.ai-runtime/memory')
    return discovery.query(
        where=f"type='decision' AND timestamp >= '{cutoff.isoformat()}'",
        order_by="timestamp desc"
    )

故障排除

常见问题

查询无结果

• 检查WHERE条件语法
• 验证字段名称拼写
• 确认时间格式（YYYY-MM-DD）

事件不显示

• 检查文件路径结构（episodic/YYYY/MM/DD/）
• 验证YAML front matter格式
• 确认时间戳有效性

性能问题

• 使用LIMIT限制结果数量
• 优化WHERE条件（先过滤时间范围）
• 考虑分页查询大量数据

调试技巧

# 查看所有已解析事件
discovery = MemoryDiscovery('.ai-runtime/memory')
for event in discovery.events:
    print(f"{event.id}: {event.title} ({event.date}) - {event.tags}")