FastrMemory

---

发布状态一览

声明	当前结果	证据
安装方式	已发布 [email protected]	npm view fastrmemory version -> 0.6.0；npm view fastrmemory dist-tags --json -> {"latest":"0.6.0"}；npm install [email protected]；fastr --version -> 0.6.0；GitHub Release 压缩包 SHA-256 10420ed6...；旧的带作用域 npm 条目已移除
MCP 注册表	io.github.atifjubaer/[email protected]，状态为 active，且为 isLatest	curl --get --data-urlencode "search=io.github.atifjubaer/fastrmemory" https://registry.modelcontextprotocol.io/v0.1/servers；gh run view 40262643667
合成检索（可选 MiniLM）	留出集 Hit@1 为 95.8%，Hit@5 为 100%，MRR 为 0.969	npx tsx scripts/eval-bench.ts --split all --embeddings minilm --out bench/results/minilm.json
测试套件	当前 main 分支有 61 个文件，共 388 项测试；已发布的 0.6.0 为 388 项 / 61 个文件；0.5.0 为 297 项 / 53 个文件；历史版本 0.4.0 为 293 项 / 53 个文件；0.3.1 为 282 项 / 52 个文件；v0.2.1 为 235 项 / 43 个文件	npm test；npm run check:ci
MCP 配置	fastr mcp init 会合并便携式注册表配置，或为 9 个 JSON 客户端合并活跃 CLI 的本地配置，并打印 Codex TOML 代码片段；--source local 已包含在已发布的 0.6.0 和 0.5.0 中	npm test -- tests/mcp-init.test.ts -> 15 passed；fastr mcp init --client claude --source local --dry-run --json -> node .../dist/bin/fastr.js mcp --project ...
跨引擎（MCP stdio）	总体 Hit@1 为 80/120（66.7%，95% CI 为 57.8–74.5）：精确匹配 40/40，多项匹配 40/40，释义匹配 0/40；每份文档摄入耗时 1.094 ms，召回 p50 为 1.86 ms	npm run bench:vs；bench/results/vs-engines.json
崩溃安全性	10 次运行中，0 条丢失，0 个重复 ID/标题	npm run test:crash；bench/results/crash-test.json
公开检索（0.3.0）	LongMemEval Hit@5 提升 +10.4pp / +11.0pp；LoCoMo 提升 +4.4pp / +2.3pp（未达到目标）	docs/EXTERNAL_BASELINE.md
发布评分	暂定 9.4 / 10；已达到 9.2 的目标；检索仍为部分达标	SCORECARD.md

合成测试表并非 SWE-bench 或 LongMemEval。公开数据仅针对检索，不代表问答排行榜结果。95.8% 这一行使用可选的 MiniLM；默认的离线哈希路径在同一留出集上的 Hit@1 为 77.1%，Hit@5 为 93.8%。完整的来源信息见 CLAIMS.md。

---

💡 概述

当项目记忆有损或运维负担过重时，AI 编码 Agent（Claude Code、Cursor、Windsurf、Codex、Antigravity）在长期运行的代码库中会逐渐退化。常见设计会在以下三种方案中取舍：

• 衰减并合并旧事件以缩小存储，这可能会丢失精确文件路径、堆栈跟踪和边缘情况。
• 运行守护进程或外部数据库，这会增加端口、容器和设置失败的可能性。
• 导出静态上下文文件，该文件会无限增长，且无法查询。

FastrMemory 通过单个进程内 TypeScript 引擎保留原样事件日志、双时态记忆历史和可重放的 Git 镜像（仅依赖 3 个运行时依赖；本地嵌入和守护进程均为可选）：

### ⚡ 零守护进程开销 纯 Node 22+ 内置的 `node:sqlite`，采用 WAL 模式。在包含 240 个用例的测试套件中，使用哈希嵌入时，引擎级召回耗时为 **0.95 ms p50 / 1.60 ms p95**；在训练集拆分上使用 MiniLM 时为 **3.30 ms p50 / 5.11 ms p95**（CLI 启动耗时另行测量）。可原生运行于 Windows、macOS 和 Linux（当前 CI 矩阵使用 Intel macOS；不包含 Apple Silicon）；CI 矩阵状态见 [Actions](https://github.com/atifjubaer/fastrmemory/actions)。

🔀 双时态 Git 同步 整合期间绝不删除事实（没有破坏性睡眠步骤）。以 valid_from / valid_to 时间戳取代半衰期衰减，并自动将人类可读的 .fastr/pages/*.md 文件镜像到 Git。

🎯 三流 RRF（$k=20$） 融合 FTS5 BM25、可选的本地嵌入和文件图链接。仅当查询意图是错误陷阱或查询范围限定为文件时，错误陷阱才会获得有条件的 2.0x 加权，并提供按 ID 记录的结果反馈（+0.2 / -0.5）。连续三次结果不佳后，记忆会转为休眠状态；置信度分级为 high、medium、low、dormant 和 superseded。对于计数问题（“我带领过多少个项目？”），还会额外执行聚合覆盖检查：针对问题中的内容词进行第二次词法查询，并与原始查询融合，最多返回 20 行供调用方计数。retrieval.temporalFilter 支持选择性启用日期范围（“过去两周”“今年”），并根据问题日期解析。

---

🧭 设计原则

原则	实现方式
默认无损	保留原始事件、双时态 valid_from / valid_to 和替代链。整合不会销毁任何内容。
默认零守护进程	单个 Node 22+ 进程使用内置的 node:sqlite，并运行于 WAL 模式。默认 CLI/MCP 路径不会打开端口或启动后台服务；daemon start 为可选项。
可重放	可通过 Git diff 查看变更的 Markdown 镜像，加上快照和回滚功能，确保历史记录可检查。
以测量为依据，而非空口断言	公开声明均有已提交的基准测试 JSON 支持，且使用 20% 的留出集；模拟基线会标注为模拟结果。

---

---

🤖 适用于兼容 MCP 和 HTTP 的 Agent

FastrMemory 提供一个 stdio MCP 服务和可选的本地 HTTP 服务（仪表板和守护进程）。原生安装程序可配置 Claude Code（MCP 配置和生命周期钩子）、Cursor（MCP 配置和技能），以及自 0.3.0 起支持的 Gemini CLI、GitHub Copilot CLI 和 OpenCode V2（fastrmemory hook install）；fastrmemory setup 还会为 Antigravity、Claude Desktop 和 Windsurf 写入 MCP 配置。其他客户端均通过自身的 MCP 配置或 REST API 连接。各客户端的集成深度不一——本仓库中的测试仅涵盖原生安装程序。

FastrMemory 的常用客户端包括 Codex CLI、Gemini CLI、OpenCode、GitHub Copilot CLI、Antigravity、Claude Desktop、Cline、Continue、Roo Code、Goose、Zed、Warp 和 Aider。列出客户端并不表示其原生集成经过测试。

---

🚀 快速开始

⚡ 无需全局安装即可运行

规范的软件包目标是未加作用域的 [email protected]。0.4.0 和 0.3.1 仍作为历史版本发布。旧的带作用域 npm 条目已于 2026-10-23 移除。

# Canonical one-shot (pins the exact release):
npx -y [email protected] setup

# Or launch the local Web UI:
npx -y [email protected] ui

GitHub 源码路径仍可用于开发：npx github:atifjubaer/fastrmemory setup。若要进行可复现的源码安装，请固定标签：npx github:atifjubaer/fastrmemory#v0.5.0 setup。生成的 MCP 或钩子配置中不得使用这两种 GitHub 形式；其中必须使用 npm 软件包。默认的 latest 通道会跟随新版本发布，而 --channel pinned 会记录确切版本，以确保可复现性。

---

从 npm 安装

# Canonical install (latest is 0.6.0):
npm install -g fastrmemory
fastr --version

# Exact release:
npm install -g [email protected]

如需单次运行而不进行全局安装：

npx -y [email protected] --version

官方 MCP 注册表将该服务列为 io.github.atifjubaer/fastrmemory（0.6.0，状态为 active），因此支持注册表的客户端可以按名称找到它；该条目使用相同的 npx -y [email protected] mcp 包和 stdio 传输方式。0.6.0 由 .github/workflows/release.yml 根据标签 v0.6.0 构建，该工作流会运行完整的检查流程、通过 npm provenance 发布，并将相同的 tarball 附加到 GitHub Release。使用 npm view [email protected] version 和 npm view fastrmemory dist-tags --json 验证注册表结果；最初几分钟出现 E404 是注册表传播延迟，并非发布失败。旧的带作用域 npm 条目仍处于移除状态。不要重新发布 0.3.0。0.5.0、0.4.0 和 0.3.1 仍作为历史版本发布。

更新现有安装

更改版本前，请停止所有 Agent、钩子、fastr ui 和 fastr daemon。在项目根目录运行：

# 1. Back up memory before changing versions
fastr backup fastr-backup.jsonl
fastr backup --verify fastr-backup.jsonl

# 2. Update the global CLI
npm install -g fastrmemory@latest
fastr --version

# 3. Refresh project integration (choose what you use)
fastr mcp init --client all --scope project   # portable npx configs only
fastr mcp init --client all --scope user --source local --profile core  # installed CLI
fastr setup                                   # MCP configs, AGENTS.md, and skills
fastr hook install                            # lifecycle hooks plus MCP for hook clients

# 4. Verify
fastr status
fastr hygiene

0.5.0 无需迁移架构。如果使用 --channel pinned，每次更新后都要重新运行 fastr mcp init；使用默认的 latest 通道时，重启客户端即可获取新版本。如果使用 --source local，配置会指向已安装的 CLI，因此更新全局包即可更新服务，无需重写配置。fastr setup 会刷新复制的技能、覆盖同名技能文件、移除已弃用的技能，并保留用户自有目录。fastr hook install 不会复制技能。回滚方式请参阅 MIGRATION.md。

一条命令完成 MCP 设置

fastr mcp init 是 shadcn 风格的设置方式。它只修改配置：将 fastrmemory MCP 条目合并到现有客户端配置中，保留无关键，创建一次性的 .fastr.bak 备份，并且可重复运行而不会造成重复修改。它不会安装生命周期钩子、技能或 OpenCode 插件；安装钩子和 OpenCode 插件请使用 fastr hook install，安装技能请使用 fastr setup。

# Claude Code (project-scoped .mcp.json)
npx -y fastrmemory@latest mcp init --client claude

# Cursor
npx -y fastrmemory@latest mcp init --client cursor

# VS Code (.vscode/mcp.json)
npx -y fastrmemory@latest mcp init --client vscode

# OpenCode (opencode.json)
npx -y fastrmemory@latest mcp init --client opencode

# Gemini CLI and GitHub Copilot CLI
npx -y fastrmemory@latest mcp init --client gemini,copilot

# Every project-scoped client at once
npx -y fastrmemory@latest mcp init --client all --scope project

使用其他包运行器执行相同命令：

pnpm dlx fastrmemory@latest mcp init --client claude
yarn dlx fastrmemory@latest mcp init --client claude
bunx fastrmemory@latest mcp init --client claude

默认的 --channel latest 会写入 fastrmemory@latest，重启客户端即可获取最新的 npm 版本。使用 --channel pinned 可生成包含运行命令时确切版本的可复现配置；在当前的 main 上，这会写入 [email protected]。--runner pnpm|yarn|bunx 可更改生成的运行器，--profile full 会选择包含 43 个工具的功能集（默认是包含 12 个工具的核心配置），--dry-run 会打印目标而不写入，--scope user 会写入用户级配置，并要求显式指定 --project /absolute/path，以确保服务始终打开预期的数据库。Codex 会输出一个 [mcp_servers.fastrmemory] TOML 代码块，供写入 ~/.codex/config.toml，而不会重写用户自有的 TOML 文件。

对于全局安装的 CLI，使用 --source local 写入当前 CLI 路径，而不是 npx 命令。它始终会附加绝对路径形式的 --project，因此配置与特定机器绑定，但启动时无需等待 npx 冷启动：

fastr mcp init --client all --scope user --source local --profile core

更新全局包即可更新服务；只有 CLI 路径发生变化时才需要重新运行命令。对于要提交并在不同机器间共享的可移植项目配置，请使用默认的 --source registry。

--source local 已包含在发布的 0.5.0 中；0.4.0 仍作为历史版本发布。在 0.4.0 上，请使用 fastr setup 配置已安装的 CLI。

mcp init 自 0.4.0 起提供；npx fastrmemory@latest mcp init ... 现在会解析为已发布的 0.5.0。如需使用更早的版本，请使用 fastr setup，或固定到 [email protected]。

从 GitHub 安装

若要一次性从源码运行，请固定发布标签：

npx --yes github:atifjubaer/fastrmemory#v0.5.0 --version
npx --yes github:atifjubaer/fastrmemory#v0.5.0 setup

若要在没有 npm Git 解析器的情况下安装全局 CLI，请下载发布压缩包：

curl -L -o fastrmemory-0.5.0.tgz \
  https://github.com/atifjubaer/fastrmemory/releases/download/v0.5.0/fastrmemory-0.5.0.tgz
npm install -g ./fastrmemory-0.5.0.tgz
fastr --version

在 Windows 上，使用 Invoke-WebRequest 或浏览器下载同一 URL，然后运行 npm install -g .\fastrmemory-0.5.0.tgz。若要安装到本地项目，请改用 npm install --no-save ./fastrmemory-0.5.0.tgz，而不要使用全局标志。

Git 安装会从源码构建，速度比 npm 压缩包慢；对于全局 CLI，建议优先使用 npm 包或上方的发布压缩包。由于 prepare 构建无法获取 dev 依赖，不建议在 npm 11 中使用 npm install -g git+https://...。安装后，fastrmemory 和 fastr（短别名）均可执行。规范的软件包是非作用域的 [email protected]；旧的 npm 作用域条目已移除。请使用 npm 生成 MCP 和 hook 配置，以确保安装可复现。

2. 验证数据库健康状况

fastrmemory status

输出：

=== FastrMemory Health (my-project) ===
- Project ID:          proj_1cce2a654e3a
- Active Memories:     2
- Staging Memories:    0
- Superseded History:  0
- Ingested Events:     0
- Pending Spool:       Clear (0)
- Database File:       .fastr/fastr.db

3. 记录和回忆记忆

# Record an error trap linked to an exact file:
fastrmemory remember "Never Use Date.now() Milliseconds for JWT Expiration" \
  -c "JWT exp claims expect integer seconds. Always use Math.floor(Date.now() / 1000)." \
  -m auth -k error_trap -f "src/auth/jwt.ts" --verified

# Recall with conditional 2.0x trap boost & file-graph matching:
fastrmemory recall "JWT expiration" -f "src/auth/jwt.ts"

输出：

=== Recalled Memories (1 results, ~46 tokens) ===

[mem_009e4a7d] [TRAP] [verified] Never Use Date.now() Milliseconds for JWT Expiration (Score: 0.08)
JWT exp claims expect integer seconds. Always use Math.floor(Date.now() / 1000).

开放的矛盾会在回忆结果的两侧标出，而不会被悄然混入上下文（0.3.0）：

# Inspect unresolved contradictions:
fastrmemory conflict list

# Keep the rule that matches the project and supersede the loser:
fastrmemory conflict resolve 1 --keep mem_009e4a7d --forget --reason "Seconds are the project standard"

导入现有本地规则（0.3.0）

将 AGENTS.md、CLAUDE.md 或 .cursor/rules/*.mdc 的内容导入记忆，无需手动复制每个章节。二级及以上标题会转为记忆；若无标题，则使用项目符号列表和段落作为替代。重新导入同一文件时，会跳过完全重复的内容。

# Preview the parsed sections without writing:
fastrmemory import AGENTS.md --from agents-md --module rules --dry-run

# Import as staging memories for review, or verify them immediately:
fastrmemory import AGENTS.md --from agents-md --module rules
fastrmemory import AGENTS.md --from agents-md --module rules --verified

# JSONL snapshots use the same entry point:
fastrmemory import snapshot.jsonl --from jsonl

4. 认知型 Git Blame 和记忆感知提交

# Cognitive Git Blame linking lines directly to commit, author, and governing error traps (conditional 2.0x boost):
fastrmemory blame src/auth/jwt.ts:42

# Pre-commit error trap validation & conventional commit synthesis:
fastrmemory commit

5. Git 快照、分支、回滚和后台守护进程（分支功能属于 0.3.0）

# Point-in-time memory snapshot (Git for Agent Memory):
fastrmemory snapshot create "pre-refactor-checkpoint"
fastrmemory snapshot list
fastrmemory snapshot rollback "pre-refactor-checkpoint"

# 0.3.0: Portable backup with a sidecar provenance manifest:
fastrmemory backup backups/pre-upgrade.jsonl
fastrmemory backup --verify backups/pre-upgrade.jsonl
fastrmemory backup --restore backups/pre-upgrade.jsonl --dry-run

# Immutable memory branch and one-way merge with a conflict report:
fastrmemory branch create feature/auth
fastrmemory branch list
fastrmemory merge feature/auth
fastrmemory merge feature/auth --force --strategy branch

# Hybrid Background Daemon (Optional HTTP/SSE service for cross-process tools):
fastrmemory daemon start
fastrmemory daemon status
fastrmemory daemon stop

# Auto-wire MCP + lifecycle hooks for Claude Code, Cursor, Gemini CLI, Copilot CLI, and OpenCode:
fastrmemory hook install

# Auto-wire MCP + AGENTS.md + Planetary Skills; setup also wires Antigravity, Claude Desktop, and Windsurf:
fastrmemory setup

# Mine past Git bug fixes directly into staging error traps:
fastrmemory learn -n 30 --days 90

分支是不可变的快照指针。merge 会单向合并到当前活动集合：添加仅存在于分支中的记忆，保留仅存在于目标中的记忆，并将身份相同但内容有变更的记忆报告为冲突。默认情况下，冲突会阻止写入；--force 会应用无冲突的新增内容，而 --force --strategy branch 会取代目标，同时将旧行保留在历史记录中。尚未实现分支检出或可变分支工作树。

backup 会写入可移植的 JSONL 快照以及 <file>.manifest.json，其中包含文件 SHA-256、内容哈希、记录数、工具版本、环境和源完整性信息。--restore 会在导入前验证这两个哈希；--dry-run 会报告数量但不写入。备份范围包括记忆、原始事件、文件链接和冲突，不包括 SQLite/WAL 的物理副本。完整的备份和回滚流程请参阅 MIGRATION.md。

6. Token 压缩、数据库诊断和视觉搜索

# Compress markdown docs & LLM prompt context to reduce token usage:
fastrmemory compress docs/architecture.md --dry-run

# Run deep health check across SQLite, FTS5 indices, file links, and task DAGs:
fastrmemory diagnose

# Auto-repair FTS5 indices, orphaned file links, and WAL fragmentation:
fastrmemory heal

# 0.3.0: Report orphaned records, duplicate active memories, and stale rows:
fastrmemory hygiene
fastrmemory hygiene --stale-days 30 --json --fail-on-issues

# Tag a UI screenshot or architecture diagram with OCR & 384-dim vector indexing:
fastrmemory vision tag screenshots/modal-error.png --desc "Modal error 401 alert" --ocr "HTTP 401"

# Semantic search across tagged screenshots and visual diagrams:
fastrmemory vision search "modal error 401"

# Pre-merge CI/CD gate checking PR diffs against active error traps:
fastrmemory guard --strict

# Optional 30 MB static semantic model (never downloaded implicitly):
fastrmemory model status
fastrmemory model install

fastrmemory hygiene 会报告孤立的文件链接、冲突行和反馈行；按规范化标题或完全相同的内容判定的重复活动记忆；以及过时的未固定活动记忆（默认以距离上次回忆或创建时间 90 天为准）。npm run check:hygiene 会在 check:ci 中使用确定性测试样例运行同一检查器；它不会修改项目数据库。如果脚本在发现问题时应以非零状态退出，请使用 --fail-on-issues。

fastrmemory model install 会获取 minishlab/potion-base-8M（256 维，30,236,760 字节），根据固定的 SHA-256 哈希验证这两个文件，并将其存储在 ~/.fastr/models/ 下。该层是基于 BM25 候选项的有界重排序器：在 LongMemEval 的 120 个用例切片中，它修复了 1 个用例，也导致 1 个用例失效，因此文档将其描述为不造成退化，而非准确率提升。在安装资源并通过回填生成向量之前，默认回忆仅使用 BM25。

---

🔌 一键式 Agent MCP 配置

fastr mcp init 是仅配置 MCP 的单命令方式。默认情况下，它使用 --source registry，并写入适用于平台的可移植运行器（npx、pnpm dlx、yarn dlx 或 bunx；原生 Windows 上使用 cmd /c ...）。传入 --source local 可写入当前 CLI 路径和绝对路径的 --project，这适用于全局安装的 CLI，但会使配置绑定到特定机器。它会保留无关的配置键，并且可幂等执行。fastr setup 仍是完整的安装程序，用于配置 .fastr/、AGENTS.md、MCP 配置和技能；fastr hook install 则会为 Claude Code、Cursor、Gemini CLI、Copilot CLI 和 OpenCode 添加生命周期钩子及 MCP 配置。

fastr hook install 会合并 Claude Code、Cursor、Gemini CLI、GitHub Copilot CLI 和 OpenCode 的生命周期钩子，并写入 OpenCode 上下文/压缩插件。fastr hook uninstall 会准确移除安装时写入的内容——fastrmemory MCP 条目、钩子命令、托管的 OpenCode 插件和 AGENTS.md 规范块——同时保留这些文件中的所有用户条目。两个命令均可幂等执行，接受 --client <ids|all>、--project <dir>、--no-agents-md 和 --json，相关说明见 docs/CLIENT_SUPPORT.md。Gemini CLI 要求钩子标准输出严格符合 JSON；Copilot 在陷阱处于激活状态时会返回 permissionDecision: "ask"，因为它没有面向模型的 preToolUse 建议字段。

客户端	项目配置	用户配置	JSON 键
Claude Code	.mcp.json	~/.claude.json	mcpServers
Cursor	.cursor/mcp.json	~/.cursor/mcp.json	mcpServers
VS Code	.vscode/mcp.json	VS Code User/mcp.json	servers
OpenCode	opencode.json	仅项目级	mcp.servers
Gemini CLI	.gemini/settings.json	~/.gemini/settings.json	mcpServers
GitHub Copilot CLI	.github/mcp.json	仅项目级	mcpServers
Windsurf	仅用户级	~/.codeium/windsurf/mcp_config.json	mcpServers
Antigravity	仅用户级	~/.gemini/antigravity/mcp_config.json	mcpServers
Claude Desktop	仅用户级	依平台而定	mcpServers
Codex	仅用户级	~/.codex/config.toml	输出的 TOML

fastr mcp init --client cursor 生成的 POSIX 项目配置示例（Windows 使用 cmd /c npx ...）：

{
  "mcpServers": {
    "fastrmemory": {
      "command": "npx",
      "args": ["-y", "fastrmemory@latest", "mcp"]
    }
  }
}

VS Code 使用 servers 而非 mcpServers；OpenCode 使用 mcp.servers，并采用命令数组和 "type": "local"。现有的 opencode.json(c) 设置会被保留，但对于 JSONC 配置，程序会提示手动配置，而不会改写。Codex 始终会输出 [mcp_servers.fastrmemory] TOML 区块，因为要安全地改写用户拥有的 TOML 文件，需要专用解析器。

对于用户级客户端，生成的条目会包含 --project /absolute/path/to/repo；这样可避免客户端的启动目录选中错误的数据库。fastr setup 还会写入 node 的绝对路径；当客户端无法启动包运行器垫片时，建议使用此方式。对于已安装的 CLI，--source local 是 mcp init 的对应方式：它会写入当前 CLI 路径和绝对路径的 --project；如果配置将提交或共享，请使用 --source registry（默认值）。--source local 已包含在发布版 0.5.0 中；对于 0.4.0，已安装 CLI 的配置请使用 fastr setup。在原生 Windows 上，fastr mcp init 会自动输出 "command": "cmd"、"/c" 和运行器，因此无需手动修复 npx.cmd。

--client all --scope project 涵盖表中的六个项目级客户端。--client all --scope user 涵盖八个用户级客户端；OpenCode 和 Copilot CLI 仅支持项目级，而 Codex 会输出供手动插入的 TOML 区块。用户级条目会固定使用一个 --project 数据库，因此如果每位开发者可能打开不同的工作副本，请使用项目级范围。

---

🛠️ MCP 服务：工具与资源

使用官方 v2 @modelcontextprotocol/server SDK 构建。以下工具列表适用于 0.5.0（工具范围与 0.4.0 相同）；v0.2.1 版本有 4 个资源。

43 个 MCP 工具

默认的 核心配置提供 12 个工具：日常循环（fastr_recall、fastr_remember、fastr_handoff、fastr_trap_recall、fastr_trap_log、fastr_status、fastr_get、fastr_replay、fastr_compress、fastr_diagnose），以及用于发现的 fastr_tools 和用于分发的 fastr_call。其 tools/list 负载为 8,715 字节（约 2,179 个 token）。完整配置提供全部 43 个工具；使用 fastrmemory mcp --profile full 或 FASTR_MCP_PROFILE=full 启动。完整配置中的每个工具都可以通过核心配置中的 fastr_call 调用。两种配置中的资源和提示词相同。如果主机在仓库之外启动服务，请传入 --project /absolute/path/to/repo，以便将记忆写入预期的 .fastr/fastr.db。

认知检索与记忆核心

1. fastr_recall：三路混合搜索（BM25 + 向量 + 扩散激活图），支持渐进式 L0–L3 token 预算，并提供隔离网络环境下的离线向量回退。
2. fastr_get：根据记忆 ID 获取完整记忆详情（包括状态、时间戳、奖励分数和完整内容）。
3. fastr_list：列出记忆，并按模块、类型、状态、数量上限和偏移量进行有限筛选。
4. fastr_drill：解析 source_event_ids，从 raw_events 中获取未截断的原始堆栈跟踪、差异和工具输出。
5. fastr_file_history：返回特定文件路径的有效规则、[TRAP] 警告和以往的替代记录。
6. fastr_remember：记录新规则、决策或陷阱。自动提取 NER 实体、清除机密信息，并重新生成 Markdown 镜像。支持 scope: 'project' | 'global'。
7. fastr_pin：固定关键规则，使其在 L0 组装中永久保留并优先显示，且不受时间衰减影响。
8. fastr_forget：清晰地将过时记忆标记为墓碑并停用，同时记录审计日志。
9. fastr_supersede：停用过时规则（valid_to = now），记录理由，并插入已验证的替代规则。
10. fastr_feedback：更新一个记忆 ID 的 reward_score 和置信度等级（好结果 +0.2，差结果 -0.5）。连续出现三次差结果会使记忆进入休眠状态；绝不会惩罚无关记忆。
11. fastr_handoff：保存或检索跨 Agent 会话里程碑，并将暂存记忆提升为已验证记忆。
12. fastr_status：返回有效记忆数、暂存记忆数、队列健康状况和嵌入覆盖率。
13. fastr_graph_query：探索 1 跳和 2 跳的结构化文件链接依赖、实体链接及相连的错误陷阱。
14. fastr_timeline：按时间顺序记录记忆事件、新近验证的规则、错误陷阱和历史替代记录。

版本控制与错误陷阱

15. fastr_snapshot：创建命名的时间点记忆快照，用于分支追踪和实验安全保障。
16. fastr_rollback：像 Git 一样即时回滚到任意先前的记忆快照。
17. fastr_trap_log：用一行快速记录错误陷阱和 Bug 解决方案，并在满足条件时使其检索权重提升 2.0 倍。
18. fastr_trap_recall：在编辑前，有针对性地查找保护特定目标文件的高优先级错误陷阱。

主动矛盾检测与解决

19. fastr_conflicts：使用 Jaccard token 重叠率（最低 0.35）和 50 词对立极性分析，主动检测矛盾。
20. fastr_resolve：通过保留首选规则，并替代或弱化冲突规则来解决矛盾。

卡尼曼规划谬误与基准率校准器

21. fastr_predict：记录工作量、时间和风险预测，并在获得实际经验结果后结算预测。
22. fastr_predict_baserate：计算历史参考类别统计数据（平均值、中位数 p50 比率、MAE），以校正 Agent 的估算。

多 Agent 操作 DAG 与前沿

23. fastr_action_create：创建结构化工作项操作，并设置前置条件（requires）和冲突（conflicts_with）约束。
24. fastr_action_update：更新任务生命周期（pending、active、done、blocked）、分配情况和记忆固化状态。
25. fastr_frontier：计算依赖关系已满足、未受阻且可执行的前沿操作。
26. fastr_next：以原子方式领取并返回优先级最高的前沿操作，供自主工作 Agent 使用。

有界工作记忆与 Obsidian Vault 导出

27. fastr_slot_get：检索有界工作记忆槽位（例如 current_goal、user_preferences、active_hypothesis）。
28. fastr_slot_set：更新工作记忆槽位，并强制执行字符数上限，以防上下文膨胀。
29. fastr_slot_list：列出所有工作记忆槽位及当前字符用量。
30. fastr_obsidian_export：将所有记忆、实体和关系导出为 Obsidian 兼容的 Markdown 知识库，包含 YAML frontmatter、[[wikilinks]] 和 MOC.md。

多仓库联邦与上下文组装

31. fastr_federate：通过 SQLite 原生 ATTACH DATABASE（~/.fastr/global.db）管理跨仓库、组织范围共享的规则和错误陷阱。
32. fastr_assemble：动态格式化并打包高密度结构化提示词上下文（<fastr_context>），并进行令牌预算管理。
33. fastr_risk_predict：计算目标代码库文件的历史失败概率和活动陷阱危险分数。
34. fastr_verify_provenance：以加密方式验证记录的 Agent 归属信息的 SHA-256 来源哈希。

令牌压缩与自主诊断

35. fastr_compress：压缩 Markdown 文件或提示词上下文，同时严格保留标题、URL 和代码块，并创建 .original.md 备份。
36. fastr_diagnose：深入审计 SQLite B-Tree 完整性、FTS5 BM25 搜索索引、孤立文件链接和任务 DAG。
37. fastr_heal：自动修复数据库索引、悬空边，并回收 WAL 页面。

记忆重放与差异比较

38. fastr_replay：重建指定时间戳的记忆状态，并返回活动快照，用于审计或恢复。
39. fastr_diff：比较两个快照，并报告新增、已被取代和已移除的记忆。

多模态视觉记忆

40. fastr_vision_tag：使用 OCR 和语义描述为截图、UI 示意图和线框图添加标签，并生成 384 维嵌入。
41. fastr_vision_search：在已存储的视觉素材中进行向量与关键词混合搜索，供多模态编码 Agent 使用。

工具发现与调度

42. fastr_tools：列出服务可运行的所有工具及其 JSON 输入模式，并按名称或描述筛选。属于核心配置。
43. fastr_call：按名称运行 fastr_tools 中的任意工具，并在运行前根据该工具的模式验证参数。属于核心配置。

2 个 MCP 提示词模板

• pre-edit-check：根据文件路径，指导 Agent 在编辑前检查陷阱和相关规则。
• session-wrap-up：会话结束检查清单，用于记录陷阱、取代过时规则、评估记忆并保存交接信息。

5 个 MCP 资源（0.3.0；v0.2.1 有 4 个）

• fastr://project/overview：L0 项目摘要，包含活动计数和存储位置。
• fastr://project/traps：所有活动的 [TRAP] 警告，用于立即规避错误。
• fastr://session/handoff：最新的跨 Agent 交接里程碑。
• fastr://memory/{id}（资源模板）：单条记忆的完整 JSON，包含关联文件及其有效期。
• fastr://memory/{id}/envelope（资源模板）：单条记忆的元数据、加密来源信息、文件/图链接，以及未解决/已解决的冲突状态。

---

📄 可通过 Git 差异查看的双区镜像

每次写入本地 SQLite 数据库时，都会自动将内容同步到 .fastr/pages/<module>.md 中的人类可读 Markdown 文件。这样，开发者就能直接在 GitHub Pull Request 中审阅 AI 记忆：

# Module: auth

> Auto-generated by FastrMemory. Active rules are at the top; superseded history is preserved below for Git diffs.

---

## Compiled Truth (Active Rules & Traps)

### [mem_009e4a7d] [TRAP] Never Use Date.now() Milliseconds for JWT Expiration
- **Kind**: `error_trap`
- **Status**: `verified` (Reward Score: 1)
- **Linked Files**: `src/auth/jwt.ts`
- **Active Since**: `2026-10-18T21:46:20Z`

JWT exp claims expect integer seconds. Always use Math.floor(Date.now() / 1000).

---

## Append-Only Timeline (History & Superseded)

### [EXPIRED 2026-10-18T20:00:00Z -> 2026-10-18T21:46:20Z] [mem_abc123] Token Signing
- **Superseded By**: `[mem_009e4a7d]`
- **Reason**: Standardized on integer seconds
- **Historical Status**: `superseded`

> Old implementation used milliseconds which failed expiration validation.

---

🧠 行星级 Agent Skills 套件

FastrMemory 附带 10 个 Agent Skills（位于 skills/，并镜像到 .cursor/skills/），用于告诉 Agent 何时使用各个记忆工具。将它们安装为 Claude Code 插件（.claude-plugin/），或使用 fastrmemory setup 复制：

• fastr-memory：在任务开始时和编辑文件之前，调用 fastr_trap_recall，然后调用 fastr_recall / fastr_assemble。
• fastr-trap-log：诊断出故障时，立即使用 fastr_trap_log 记录。
• fastr-session-commit：任务完成且测试通过时，更新旧记忆、评估记忆，并使用 verifyStaging 调用 fastr_handoff。
• fastr-curate：存储持久经验或修复矛盾时，执行去重、记忆、更新旧记忆、解决冲突、快照／回滚。
• fastr-setup：FastrMemory 尚未接入 Claude Code 时，运行 fastrmemory hook install、claude mcp add，并使用 fastrmemory status 验证。
• fastr-plan-estimate：估算工作量或风险时，使用基础发生率、文件风险和收尾预测。
• fastr-dag：工作包含相互依赖的步骤，或多个 Agent 共用一个待办列表时使用。
• fastr-doctor：回忆未找到记忆，或数据库看起来不健康时，先诊断，再修复。
• fastr-compress：文档或上下文块超出 token 预算时使用。
• fastr-vision：需要记住或搜索截图、图表时使用。

运行 npm run check:skills，根据 src/mcp/server.ts 验证 skills 中的每个工具调用。

更新 CLI 后，重新运行 fastr setup，以刷新复制的 skills。安装程序会覆盖同名 skill 文件、移除已弃用的 skill，并保留与之无关的用户目录。fastr hook install 不会复制 skills。设置完成后，重启客户端。如果改为安装 Claude Code 插件，请更新该插件，而不要再维护一套单独复制的 skills。

---

🏗️ 架构

flowchart TD
    subgraph Ingestion["1. Lossless Ingestion & Spool"]
        Agent["AI Coding Agent\n(Claude Code, Cursor, Antigravity)"] --> Scrubber["Secret Scrubber\n(API Keys, Bearer, PEM)"]
        Scrubber --> Spool{"SQLite Busy?"}
        Spool -- Yes --> SpoolFile[".fastr/spool/pending.jsonl\n(async fallback)"]
        Spool -- No --> DB
    end

    subgraph Storage["2. Bi-Temporal Storage & Git Mirror"]
        DB[("Node 22 node:sqlite (WAL)\nraw_events | memories\nfile_links | handoffs")]
        DB --> Mirror["Markdown Mirror Engine"]
        Mirror --> Pages[".fastr/pages/<module>.md\nTop: ## Compiled Truth\nBottom: ## Append-Only Timeline"]
    end

    subgraph Search["3. Triple-Stream Hybrid Retrieval"]
        Query["Recall / File Query"] --> FTS["Stream A: FTS5 BM25\n(Sub-millisecond)"]
        Query --> Vec["Stream B: Xenova Vectors\n(all-MiniLM-L6-v2)"]
        Query --> Graph["Stream C: file_links Graph\n(1-2 Hop Structural Match)"]
        FTS & Vec & Graph --> RRF["RRF Fusion (k=20)\n+ Conditional 2.0x Error Trap Multiplier\n+ 1.25x Verified Multiplier"]
        RRF --> Budget["Progressive Token Packer\nL0 (150t) | L1 (500t) | L2 (1500t) | L3 (4000t)"]
    end

    subgraph Protocol["4. Official MCP Protocol"]
        Budget --> MCPServer["Official MCP v2 Server\n(@modelcontextprotocol/server)"]
        MCPServer --> Tools["43 tools • 2 prompts • 5 resources"]
        Tools --> Agent
    end

---

🧪 测试与验证

运行完整的单元测试套件：

npm test

当前 main 上的 61 个测试文件共通过 388 项测试；已发布的 0.6.0 同样包含 388 / 61，0.5.0 包含 297 项测试 / 53 个文件，历史版本 0.4.0 包含 293 项测试 / 53 个文件，0.3.1 包含 282 / 52，v0.2.1 包含 235 / 43。测试覆盖数据库架构、WAL 锁定、离线暂存、双时态 supersession、密钥清理、双区域渲染、自动化基准测试、快照/回滚、分支合并冲突报告、重放/差异、记忆信封、置信度层级与 3-bad 休眠、记忆卫生检查、Memory CI、感知冲突的召回、可移植备份清单与经验证的恢复、本地规则导入、OpenCode V2、Gemini CLI 和 Copilot CLI 接入、git-learner、认知 blame、提交综合、混合后台守护进程、令牌压缩、自我修复 doctor、多模态视觉、Web 仪表板服务端、合并前陷阱守护程序、UI 环回安全边界、原子安装程序配置安全性，以及 shadcn 风格的 mcp init 客户端配置合并（包括本地来源条目）。

CI 性能门禁： check:query-plans、check:recall-latency 和 check:install-size 在 check:ci 中运行。CI 会在规范的 Ubuntu/Node 24 任务中执行这些检查；其他矩阵任务会设置 FASTR_PERF_GATE=0，因为耗时对运行器敏感，但所有矩阵条目仍会运行功能测试。

干净机器安装证据： npm run smoke:npx 会在空目录中通过 npx 下载已发布的包（没有检出副本、全局安装或 node_modules），然后运行 --version 和 status。status 会打开一个真实的 node:sqlite 数据库，因此，如果发布的包没有可用的 SQLite 路径，就会在此处失败，而不是等到在编辑器中才失败。该脚本会在注册表返回 404 时重试，最长持续十分钟；.github/workflows/npx-smoke.yml 会在 Ubuntu、Windows 和 Intel macOS 上，针对 Node 22.x 和 24.x 运行该脚本。CI 运行 40261934471（提交 b9645ef）的全部六个任务均已通过；在冷启动的 npx 安装中，每个任务均报告 "version":"0.6.0"、"statusBooted":true、"attempts":1 和 "ok":true；同一脚本也已在本地 Windows / Node 24.15.0 上通过。

崩溃安全性证据： npm run test:crash 会在 10 次运行中随机选取时间点终止写入程序，然后重新打开 WAL 数据库。已提交的报告 bench/results/crash-test.json 记录了 10,718 次已确认写入、10,727 行已提交数据、0 次丢失、0 个重复 ID/标题，以及 PRAGMA integrity_check = ok；测试方法见 docs/audit/2026-10-21-crash-test.md。npm run check:crash 会在 check:ci 期间验证该报告。这是进程崩溃测试（taskkill /F），而非断电测试；SQLite 在 WAL 模式下使用 synchronous=NORMAL。

---

检索基准测试（240 个合成案例）

根据 bench/results/minilm.json 生成，日期为 2026-10-20，基准提交为 562f461。语料是确定性的：包含 120 条记忆和 240 个查询，划分为 192 个训练案例 / 48 个留出案例（20%）。留出集在调优前固定，并单独报告。运行以下命令复现：

npx tsx scripts/eval-bench.ts --split all --embeddings minilm --out bench/results/minilm.json
npx tsx scripts/eval-bench.ts --split all --embeddings hash   --out bench/results/hash.json

配置	数据集	案例数	Hit@1	Hit@3	Hit@5	MRR	nDCG@10	上下文 token 数	p50
FastrMemory + MiniLM	训练集	192	96.4%	99.0%	100%	0.976	0.982	208	3.30 ms
FastrMemory + MiniLM	留出集	48	95.8%	97.9%	100%	0.969	0.977	209	3.41 ms
FastrMemory 仅 BM25	训练集	192	79.7%	90.6%	100%	0.868	0.900	203	0.48 ms
FastrMemory 仅 BM25	留出集	48	77.1%	77.1%	93.8%	0.804	0.835	204	0.60 ms
静态转储 - 模拟基线	训练集	192	2.1%	6.3%	8.3%	0.055	0.081	3652	0.00 ms
静态转储 - 模拟基线	留出集	48	0.0%	0.0%	8.3%	0.025	0.056	3652	0.00 ms

注意事项： 这是确定性的合成语料，并非 SWE-bench 或 LongMemEval。静态转储行是本代码库中的模拟实现，并非外部项目。单独的公开外部纯检索基线见 docs/EXTERNAL_BASELINE.md；合成表格未对其进行测量。上下文 token 数是 250-token 预算下的精简提示词文本；排名结果对象保留完整记忆内容。方法、分类别细分、消融实验和置信区间见 BENCHMARKS.md 和 docs/benchmark-report.md。

🖥️ 本地 Web 控制面板 v2 与 3D 大脑观测站

通过捆绑的 UI 资源，直接在浏览器中可视化活跃规则、错误陷阱、时间线审计和交互式 3D 记忆星座（无需外部服务或数据库）：

fastrmemory ui

• 实时 URL：http://localhost:4242
• 控制面板 v2 架构：使用 shadcn/ui、Tailwind CSS v4 和 TanStack Query 构建，支持 SSE 更新，并通过版本轮询处理跨进程写入。
• 12 个专用路由工作区（0.3.0 新增 /replay）：
  • /：实时系统状态、活跃陷阱警报、近期记忆动态和快捷操作。
  • /memories：搜索、筛选和检查记忆；提供滑出式 记忆详情面板、状态切换、置顶和一键遗忘功能。
  • /traps：专用的 错误陷阱隔离区，用于显示管理文件、条件加权条件和已验证的缓解经验。
  • /conflicts：主动检测双时态矛盾，提供并排 文字差异 和一键解决选项（Keep A、Keep B、Keep Both）。
  • /actions：实时交互式 操作 DAG 画布，跟踪任务依赖关系、工作者分配和发光的未阻塞前沿光环。
  • /graph：交互式文件与实体关系图，支持 1 跳／2 跳检查和记忆深入查看。
  • /observatory：高性能 Three.js 3D 星座星系，具有平滑的 lerp 摄像机、星际尘埃、发光的琥珀色陷阱光环和记忆检查模态框。
  • /treemap：交互式高 DPI 方形树图，可视化记忆强度区间和模块密度。
  • /search：搜索实验室，评估三路 RRF 检索，并以延迟瀑布图分解展示结果（BM25 与 Vector 与 Graph）。
  • /replay（0.3.0）：回放与差异工作区，可重建两个时间戳下的活跃集合，并查看快照指标以及新增／被取代／已更改／冲突内容。
  • /health：自主 SQLite 自修复 Doctor，支持一键完整性诊断、FTS5 重建和清理。
  • /settings：实时数据库路径、项目配置和导出控件。
• 记忆 CI：PR 差异工作流和评论生命周期说明见 docs/MEMORY_CI.md。
• 双主题支持：浅色、深色和跟随系统偏好模式。
• 默认零守护进程路径：控制面板由进程内 Node.js HTTP 服务器和嵌入式 SQLite WAL 模式提供服务；fastrmemory daemon start 是可选的本地 REST/SSE 服务。

---

🧩 原生 VS Code 与 Cursor 扩展

打包并安装适用于 VS Code 和 Cursor 的原生 FastrMemory Guardian 扩展：

# Compile and package extension
npm run build:extension
npx @vscode/vsce package --no-dependencies

# Install into Cursor or VS Code
cursor --install-extension fastrmemory-vscode-0.1.0.vsix

• ⚡ 状态栏标记：在状态栏显示活跃陷阱数量（⚡ 3 Traps Active 或 ⚡ 1 Trap on File）。点击后会打开交互式 QuickPick，列出所有活跃陷阱。
• 琥珀色下划线：陷阱文件会显示琥珀色下划线，并提供完整的悬停缓解说明和条件 2.0x 加权条件。
• 问题面板集成：活跃错误陷阱会以非阻塞警告诊断的形式显示在 IDE 问题面板中。
• 零守护进程：通过 node:sqlite 直接读取 .fastr/fastr.db。

---

📄 许可证

Apache License 2.0。由 Fastrsoft 构建。可免费用于个人和商业用途。