名称： fsxmemory
版本： 1.3.1
描述： 面向 AI 智能体的结构化记忆系统。具备上下文中断恢复能力（检查点/恢复）、结构化存储、兼容 Obsidian 的 Markdown 以及本地语义搜索功能。
作者： Foresigxt
仓库： https://github.com/Foresigxt/foresigxt-cli-memory

Foresigxt Memory

面向 AI 智能体的结构化记忆系统。

安装

npm install -g @foresigxt/foresigxt-cli-memory

设置

选项 1：初始化新记忆库

# 初始化记忆库（创建文件夹结构和模板）
fsxmemory init ~/memory

选项 2：使用现有记忆库

为独立工作区配置记忆库（每个工作区拥有自己的记忆库）：

# 在工作区根目录创建 .env 文件
echo 'FSXMEMORY_PATH=/path/to/workspace/memory' > .env

# 此工作区内的所有智能体将自动使用这个独立的记忆库
fsxmemory stats  # 自动生效！

在所有工作区之间共享记忆库：

# 设置全局环境变量（在 ~/.bashrc 或 ~/.zshrc 中）
export FSXMEMORY_PATH=/path/to/shared/memory

# 所有工作区中的所有智能体将共享同一个记忆库

或者：使用 --vault 标志进行一次性覆盖：

fsxmemory stats --vault /path/to/other/vault

核心命令

按类型存储记忆

# 可用类型：fact, feeling, decision, lesson, commitment, preference, relationship, project, procedural, semantic, episodic
fsxmemory remember decision "选择 Postgres 而非 SQLite" --content "多智能体设置需要并发写入能力"
fsxmemory remember lesson "上下文中断是可以恢复的" --content "在进行繁重工作前创建检查点"
fsxmemory remember relationship "Justin Dukes" --content "Hale Pet Door 公司的客户联系人"
fsxmemory remember procedural "部署到生产环境" --content "1. 运行测试 2. 构建 3. 部署"
fsxmemory remember semantic "事件循环概念" --content "JavaScript 的并发模型..."
fsxmemory remember episodic "首次生产部署" --content "今天部署了 v2.0，团队很紧张但一切顺利"

快速捕获到收件箱

fsxmemory capture "待办：明天审查 PR"

搜索（需要安装 qmd）

# 关键词搜索（快速）
fsxmemory search "客户联系人"

# 语义搜索（较慢，更准确）
fsxmemory vsearch "我们关于数据库做了什么决定"

上下文中断恢复

检查点（频繁保存状态）

fsxmemory checkpoint --working-on "PR 审查" --focus "类型守卫" --blocked "等待 CI"

恢复（唤醒时检查）

fsxmemory recover --clear
# 显示：中断时间、最后检查点、最近的交接记录

交接（会话结束前）

fsxmemory handoff \
  --working-on "Foresigxt Memory 改进" \
  --blocked "npm token" \
  --next "发布到 npm，创建技能" \
  --feeling "高效"

回顾（启动新会话）

fsxmemory recap
# 显示：最近的交接记录、活跃项目、待办承诺、经验教训

从其他格式迁移

从 OpenClaw、Obsidian 或其他基于 Markdown 的系统迁移现有记忆库：

先分析（试运行）

# 预览将要进行的更改，但不实际修改文件
fsxmemory migrate --from openclaw --vault /path/to/vault --dry-run

带备份的迁移

# 推荐：在迁移前自动创建备份
fsxmemory migrate --from openclaw --vault /path/to/vault --backup

# 迁移过程：
# ✅ 为所有 Markdown 文件添加 YAML 前置元数据
# ✅ 重命名目录（procedural→procedures, semantic→knowledge, episodic→episodes）
# ✅ 创建 .fsxmemory.json 配置文件
# ✅ 保留所有内容和自定义分类
# ✅ 创建带时间戳的备份以便回滚

必要时回滚

# 如果出现问题，从备份恢复
fsxmemory migrate --rollback --vault /path/to/vault

迁移选项

# 可用的源格式
--from openclaw      # OpenClaw 记忆库格式
--from obsidian      # Obsidian 记忆库格式
--from generic       # 通用 Markdown 记忆库

# 迁移标志
--dry-run           # 预览更改而不修改文件
--backup            # 迁移前创建备份（推荐）
--force             # 跳过确认提示
--verbose           # 显示详细进度
--rollback          # 从最近备份恢复

示例：迁移 OpenClaw 记忆库

# 1. 先分析
fsxmemory migrate --from openclaw --vault ~/.openclaw/workspace/memory --dry-run

# 2. 运行带备份的迁移
fsxmemory migrate --from openclaw --vault ~/.openclaw/workspace/memory --backup --verbose

# 3. 验证迁移是否成功
fsxmemory stats --vault ~/.openclaw/workspace/memory
fsxmemory doctor --vault ~/.openclaw/workspace/memory

迁移速度：约 53 个文件耗时 0.07 秒 ⚡

自动链接

为 Markdown 文件中的维基链接实体提及创建链接：

# 链接所有文件
fsxmemory link --all

# 链接单个文件
fsxmemory link memory/2024-01-15.md

模板参考

Foresigxt Memory 包含用于一致性文档的结构化模板。位置：templates/ 目录。

可用模板

模板使用

模板根据记忆类型自动选择：

fsxmemory remember decision "标题" --content "..."    # → templates/decision.md
fsxmemory remember procedural "标题" --content "..."  # → templates/procedure.md
fsxmemory remember semantic "标题" --content "..."    # → templates/knowledge.md
fsxmemory remember episodic "标题" --content "..."    # → templates/episode.md
fsxmemory remember relationship "姓名" --content "..." # → templates/person.md
fsxmemory remember lesson "标题" --content "..."      # → templates/lesson.md

查看模板结构：在创建记忆文档前，请阅读 templates/ 目录中的模板文件。

模板特性：
- 包含元数据（标题、日期、类型、状态）的 YAML 前置元数据
- 带有占位符指导的结构化章节
- 用于连接的维基链接建议
- 自动生成的标签

文件夹结构

vault/
├── .fsxmemory/           # 内部状态
│   ├── last-checkpoint.json
│   └── dirty-death.flag
├── decisions/            # 带有推理的关键决策
├── lessons/              # 洞察和模式
├── people/               # 每人一个文件
├── projects/             # 活跃工作跟踪
├── procedures/           # 操作指南和工作流
├── knowledge/            # 概念和定义
├── episodes/             # 个人经历
├── handoffs/             # 会话连续性
├── inbox/                # 快速捕获
└── templates/            # 文档模板（9 种类型）

最佳实践

1. 每 10-15 分钟创建检查点，尤其是在进行繁重工作时
2. 在会话结束前进行交接——未来的你会感谢你
3. 唤醒时执行恢复——检查上次会话是否中断
4. 使用类型——知道存储的是什么有助于确定存放位置
5. 自由使用维基链接——[[person-name]] 构建你的知识图谱

与 qmd 集成

Foresigxt Memory 使用 qmd 进行搜索：

# 安装 qmd
bun install -g github:tobi/qmd

# 将记忆库添加为集合
qmd collection add /path/to/vault --name my-memory --mask "**/*.md"

# 更新索引
qmd update && qmd embed

配置

Foresigxt Memory 支持三种设置记忆库路径的方式（按优先级顺序）：

1. 命令行标志（最高优先级）

fsxmemory stats --vault /path/to/vault

2. 环境变量

export FSXMEMORY_PATH=/path/to/memory
fsxmemory stats

3. .env 文件（用于工作区隔离的记忆库）

# 在工作区根目录创建 .env 文件
cat > .env << 'EOF'
FSXMEMORY_PATH=/home/user/.openclaw/workspace/memory
EOF

# 此工作区内的所有 fsxmemory 命令都将使用这个独立的记忆库
fsxmemory stats
fsxmemory checkpoint --working-on "任务"

何时使用 .env 文件：
- ✅ 隔离工作区记忆——每个项目拥有独立的记忆库
- ✅ 按项目配置——不同工作区中的不同智能体使用不同的记忆库
- ✅ 可移植——工作区智能体自动使用正确的记忆库
- ✅ Git 安全——将 .env 添加到 .gitignore 以保护路径

何时使用全局导出：
- ✅ 跨工作区共享记忆——所有地方的智能体都使用一个记忆库
- ✅ 集中化知识——所有项目的单一事实来源

环境变量：
- FSXMEMORY_PATH —— 记忆库路径（可在 shell 或 .env 文件中设置）

发布技能包

创建可分发的技能包（包含 SKILL.md 和 templates/）：

# 打包技能
npm run package-skill

# 输出：dist-skill/fsxmemory-skill.zip (~8KB)

包内容：
- SKILL.md - 完整的文档和参考
- templates/ - 所有 9 种记忆模板
- .env.example - 配置模板
- INSTALL.md - 快速设置指南

分发：
与其他智能体/团队共享 fsxmemory-skill.zip 文件。他们可以解压获得：
- 完整的技能文档
- 开箱即用的模板
- 配置示例

对于 OpenClaw/ClaudeHub：
打包好的技能已准备好上传到技能仓库。

链接

• npm: https://www.npmjs.com/package/@foresigxt/foresigxt-cli-memory
• GitHub: https://github.com/Foresigxt/foresigxt-cli-memory
• 问题反馈: https://github.com/Foresigxt/foresigxt-cli-memory/issues