memories-off

name	memories-off
description	管理基于 Markdown 实体的本地知识库。提供库观察、实体检索、按需加载章节、精确编辑及显式关系管理能力。支持长期记忆与持续学习。
author	github/cafe3310
license	Apache-2.0

Agent Skill: memories-off (技能说明)

1. 概述 (Overview)

memories-off 是一个专门用于管理本地结构化知识库的 Agent Skill。它允许 LLM 将非结构化的对话、笔记、项目文档等，转化为由实体、关系和观察组成的知识图谱，并提供高效的检索和编辑能力。

该 Skill 旨在支持 LLM 实现“长期记忆”和“持续学习”，并基于 Markdown 文件提供本地优先的数据存储方案。

---

2. Agent 工作流与命令探索 (Agent Workflow)

作为 Agent，你不需要去阅读冗长的底层工具实现细节或规格文档。本 Skill 提供了自包含的命令行包装器 memocli。

2.1 任务初始化 (Explore First)

在处理任何与本知识库相关的任务前，必须首先运行以下命令获取全局上下文：

memocli explore

该命令会返回结构化的 XML 报告，包括：

• 知识库的全局描述和手册 (meta.md)。
• 架构实体预览。
• 当前所有可用的 memocli 子命令列表及简要说明。

2.2 了解命令用法 (Help System)

当你需要使用某个具体的子命令（如 search-entities, append-update）但不确定其参数时，请直接在终端运行该命令的帮助：

memocli <subcommand> --help

终端输出会告诉你最新的参数、选项以及调用示例，请严格按照 --help 提示的格式调用。

2.3 全局配置与多仓库管理 (Global Config & List Libraries)

如果您在多知识库场景下工作，可以通过在全局配置文件 ~/.config/memocli/config.yaml 中配置 libraries 来为各个库定义别名与描述。 配置文件示例如下：

libraries:
  test_work:
    path: /absolute/path/to/mock_kb_work
    desc: 这是工作相关的知识库，包含任务跟踪和项目设计。
  test_life:
    path: /absolute/path/to/mock_kb_life
    desc: 这是生活相关的知识库，包含日常琐事和健康记录。

配置完成后，您可以在执行任何子命令时使用 -l <alias>（或 --library <alias>）代替绝对路径，系统会自动进行别名展开。 此外，您也可以运行以下命令一键查询全局配置的所有知识库：

memocli list-libraries

---

3. Agent 最佳实践与约束 (Best Practices)

在使用 memocli 时，请严格遵守以下实践，以确保图谱的健康和数据的安全：

1. 缓冲编辑优先: 在编辑已有实体内容时，严禁使用 Agent 自带的行定位编辑工具、也尤其禁止使用整体文件 Write。必须优先通过 memocli append-update 以追加更新块的形式进行非破坏性修改。
2. 多行写入使用 STDIN 模式: 当你需要通过 create-entity 或 append-update 写入包含多行、引号、特殊符号、WikiLinks 等复杂内容时，不建议使用 -c "..." 传参，这极易导致 Shell 转义失败。建议使用管道（STDIN）模式。例如：

   echo "## 章节标题
   - 内容1
   - 内容2 [[链接]]" | memocli append-update --entity "实体名" --content-stdin --reason "更新理由"
   

3. 模糊检索优先 (Content-Grep First): 了解细节信息时，应使用 memocli search-entities。建议配合 --type (过滤类型) 和 --rel (过滤关系) 提升检索精度。
4. 标题层级规范: 实体正文必须遵循严格的标题层级：文件顶部第一行固定为 H1 (# 实体名)，正文内部所有的业务章节标题必须统一标准化为 H2 (## 章节名)。禁止使用 H3 及更深层级。
5. 优先用 Plain Text: 实体正文应当简洁。避免使用 Markdown 加粗 (**)、斜体 (*) 等修饰性格式。允许使用 H2 标题、无序列表 (-) 和 WikiLinks ([[ ]])。
6. 强制审计 (Audit): 所有修改操作必须提供简短的 --reason 参数以供 Git 记录。
7. 本地优先: 所有操作均基于本地文件系统，且当前路径若为知识库根目录，memocli 会自动推断 --path .。

---

4. 核心概念与术语 (Core Concepts & Glossary)

为了与用户和其他系统保持语义对齐，并理解你所操作的数据模型（如实体结构、元数据关系、WikiLinks 等），请务必参阅以下文档：

1. 核心概念与数据模型 (Core Concepts): 解释了你在使用 memocli 时必须理解的 H1/H2 规则、别名机制、双向链接原理及缓冲编辑机制。
2. 批量操作与 Token 节约指南 (Batch Operations): 总结了如何通过合并指令、合理使用参数来大幅减少 Token 消耗与执行时间的最佳实践。
3. 项目术语表 (Glossary): 提供关键名词和动词的精确定义。

---

5. 底层设计文档 (Design Documents)

design-doc/ 是此 Agent 的底层设计文档。你一般不需要阅读。仅当用户要求你修改本 Skill 的底层实现细节时，才需要参考其中的内容。