Foresigxt Memory

面向 AI 代理的结构化记忆系统。

安装

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

配置

选项 1：初始化新保险库（Vault）

# 初始化保险库（创建目录结构 + 模板）
fsxmemory init ~/memory

选项 2：使用已有保险库

用于隔离的工作区记忆（每个工作区拥有独立保险库）：

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

# 该工作区中的所有 agent 均使用此隔离保险库
fsxmemory stats  # 自动生效！

用于跨所有工作区共享记忆：

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

# 所有工作区中的所有 agent 共享同一保险库

或者：使用 --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 "多 agent 场景需支持并发写入"
fsxmemory remember lesson "上下文死亡（Context death）是可恢复的" --content "繁重任务前务必保存检查点（checkpoint）"
fsxmemory remember relationship "Justin Dukes" --content "Hale Pet Door 客户联系人"
fsxmemory remember procedural "部署至生产环境" --content "1. 运行测试 2. 构建 3. 部署"
fsxmemory remember semantic "事件循环（Event Loop）概念" --content "JavaScript 的并发模型..."
fsxmemory remember episodic "首次生产部署" --content "今日上线 v2.0，团队虽紧张但一切顺利"

快速捕获至收件箱（inbox）

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

搜索（需已安装 qmd）

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

# 语义搜索（速度较慢，但更精准）
fsxmemory vsearch "关于数据库我们做了什么决策"

上下文死亡（Context Death）韧性机制

检查点（Checkpoint，频繁保存状态）

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

恢复（Recover，在唤醒时检查）

fsxmemory recover --clear
# 输出：死亡时间、最近检查点、最近交接记录

交接（Handoff，在会话结束前执行）

fsxmemory handoff 
  --working-on "Foresigxt Memory 功能改进" 
  --blocked "npm token" 
  --next "发布至 npm、创建 skill" 
  --feeling "高效"

回顾（Recap，启动新会话时引导）

fsxmemory recap
# 输出：近期交接记录、活跃项目、待履行承诺、已归纳经验

从其他格式迁移

支持将 OpenClaw、Obsidian 或其他基于 Markdown 的保险库迁移至 Foresigxt Memory：

先分析（试运行）

# 查看迁移影响，不实际修改文件
fsxmemory migrate --from openclaw --vault /path/to/vault --dry-run

带备份迁移

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

# 迁移操作包括：
# ✅ 为所有 Markdown 文件添加 YAML frontmatter
# ✅ 重命名目录（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 秒 ⚡

自动链接（Auto-linking）

在 Markdown 文件中自动为实体提及添加 Wiki 链接：

# 为全部文件建立链接
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 frontmatter（标题、日期、类型、状态）
• 结构化章节，含占位符与撰写指引
• 提供 Wiki 链接建议，便于知识关联
• 自动生成标签

目录结构

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. 充分使用 Wiki 链接——[[person-name]] 是构建知识图谱的基础

与 qmd 集成

Foresigxt Memory 使用 qmd 实现搜索功能：

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

# 将保险库添加为 qmd collection
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 "task"

建议使用 .env 的场景：

• ✅ 隔离工作区记忆 —— 每个项目拥有独立保险库
• ✅ 按项目配置 —— 不同工作区中的 agent 使用不同保险库
• ✅ 可移植性强 —— 工作区内的 agent 自动选用对应保险库
• ✅ 对 Git 友好 —— 将 .env 加入 .gitignore 以保护路径信息

建议使用全局 export 的场景：

• ✅ 跨工作区共享记忆 —— 所有 agent 统一使用一个保险库
• ✅ 集中式知识管理 —— 所有项目共用单一可信源

支持的环境变量：

• FSXMEMORY_PATH —— 保险库路径（可在 shell 或 .env 文件中设置）

发布 Skill 包

生成可分发的 skill 包（含 SKILL.md 与 templates/ 目录）：

# 打包 skill
npm run package-skill

# 输出：dist-skill/fsxmemory-skill.zip（约 8KB）

包内内容：

• SKILL.md —— 完整文档与参考手册
• templates/ —— 全部 9 类记忆模板
• .env.example —— 配置模板
• INSTALL.md —— 快速搭建指南

分发方式：
将 fsxmemory-skill.zip 文件分享给其他 agent 或团队。接收方可解压获得：

• 完整的 skill 文档
• 即开即用的模板
• 配置示例

对接 OpenClaw/ClaudeHub：
打包后的 skill 可直接上传至 skill 仓库。

相关链接

• npm：https://www.npmjs.com/package/@foresigxt/foresigxt-cli-memory
• GitHub：https://github.com/Foresigxt/foresigxt-cli-memory
• Issues：https://github.com/Foresigxt/foresigxt-cli-memory/issues