项目定位与核心价值

Anamnesis 的核心目标是让 Claude Code 在多台开发机之间共享持久的记忆与上下文，避免每次会话都从零开始。其设计取舍围绕以下三点展开：

• 本地优先：所有记忆数据默认保存在用户指定的本地目录（ANAMNESIS_HOME，默认 ~/.anamnesis），无需依赖云服务即可完整运行。
• Markdown 即真相：记忆以纯文本 Markdown 写入，便于人工审阅、版本控制与跨工具复用，SQLite 索引仅作为查询加速层 资料来源：README.md:30-60。
• Git 驱动的跨机器同步：通过 Git 仓库的形式在机器间同步 Markdown 文件，兼容任意 Git 主机（GitHub、本地裸仓库等） 资料来源：README.md:50-80。

该项目当前最新发布版本为 v0.1.3，修复了 anamnesis init 在自定义 ANAMNESIS_HOME 与 ANAMNESIS_MACHINE_ID 环境变量下未生效的问题 资料来源：v0.1.3 Release Notes。

架构总览

Anamnesis 的运行时由三层组成：CLI 命令入口、MCP 服务器、以及底层存储与同步模块。

graph LR
    A[Claude Code / IDE] -->|MCP stdio| B(MCP Server<br/>FastMCP)
    B --> C[Memory Store<br/>Markdown + SQLite FTS5]
    B --> D[Sync Engine<br/>Git]
    D <--> E[Remote Git Repo<br/>或裸仓库]
    C --> F[Local Notes<br/>~/.anamnesis/notes]

• MCP Server：基于 FastMCP 暴露 memory_search / memory_list / memory_status / memory_write / memory_sync 等工具，使 Claude Code 能在对话过程中读写记忆 资料来源：README.md:60-90。
• Memory Store：以 Markdown 文件为持久化形式，SQLite FTS5（WAL 模式）负责全文检索，保证读写并发安全 资料来源：README.md:30-50。
• Sync Engine：通过 Git 进行跨机器同步，并使用 machine ID 区分不同机器的写入来源，避免内容冲突 资料来源：README.md:70-100。

关键能力与配套组件

记忆质量循环

自 v0.1.0 起，Anamnesis 引入了"记忆质量循环"：通过 LLM 反思（reflection）将 Claude Code 的会话日志蒸馏为可复用的长期笔记。该机制兼容任意 OpenAI-compatible 的 Provider，用户可在配置中指定 资料来源：v0.1.0 Release Notes。

独立 Dashboard

v0.1.1 新增了独立 Dashboard，用于浏览与管理记忆内容。提供两种使用方式：

• 通过 npm 全局工具启动：npx anamnesis-dashboard 资料来源：dashboard/npm/README.md:1-30。
• 通过 CLI 子命令启动：anamnesis dashboard 资料来源：dashboard/README.md:1-40。

Dashboard 的部署文档详细说明了在多种环境下的启动方式，便于在本地或服务器上独立托管 资料来源：dashboard/deploy/README.md:1-40。

跨机器性能基准

项目内置了 bench/cross-machine-tokens 基准测试，用于度量多机同步场景下 token 消耗与同步开销。基准用例包含一个完整的跨机器演示流程，帮助用户评估在真实工作流中的成本 资料来源：bench/cross-machine-tokens/README.md:1-40。演示记录位于 bench/cross-machine-tokens/demo/，提供了双机协作的可复现样例 资料来源：bench/cross-machine-tokens/demo/README.md:1-30。

快速上手

安装与初始化只需两条命令：

uv tool install anamnesis-memory
anamnesis init

anamnesis init 会创建默认存储目录、初始化 SQLite 索引并执行首次同步。从 v0.1.3 起，该命令会严格遵循 ANAMNESIS_HOME 与 ANAMNESIS_MACHINE_ID 环境变量，并在已有存储上保留原有配置 资料来源：README.md:90-130。完成初始化后，在 Claude Code 中启用对应的 MCP server 即可使用全部记忆工具 资料来源：README.md:60-90。

适用场景与边界

Anamnesis 适合以下场景：

• 多台开发机之间共享 Claude Code 的上下文与笔记；
• 需要可审计、可版本控制的 AI 记忆数据；
• 希望在离线或内网环境下完整运行记忆系统 资料来源：README.md:10-40。

其当前边界在于：同步依赖 Git 与远端仓库可达性；反射质量取决于所配置 LLM Provider 的能力；Dashboard 主要面向本地浏览而非高并发在线服务 资料来源：dashboard/README.md:20-50。

概述

dashboard/src/lib/ 目录是 Anamnesis 独立仪表盘（standalone dashboard）的前端核心工具层。它由一组小而职责单一的 TypeScript 模块组成，介于浏览器中的 React 组件与本地 Anamnesis 存储层（SQLite FTS5 索引 + Markdown 文件）之间，起到"基础设施胶水"的作用。

仪表盘入口在 v0.1.1 中引入（npx anamnesis-dashboard 与 anamnesis dashboard），它运行在浏览器中，无法直接访问本地文件或子进程，因此必须借助 Lib 模块来代理所有 I/O。该层既包含与本地 CLI 子进程通信的封装，也包括 UI 层的样式工具、配置加载器，以及针对 SQLite 数据库的访问入口。

资料来源：dashboard/src/lib/cli.ts、dashboard/src/lib/config.ts

模块构成

CLI 封装层

cli.ts 负责把仪表盘前端的请求转换为对本地 anamnesis CLI 子进程的调用。由于浏览器无法直接读取 SQLite 数据库或执行 git 同步，仪表盘需要通过 CLI 来代理 MCP 工具能力（memory_search、memory_list、memory_status、memory_write、memory_sync），Lib 层将这些调用收敛为一个稳定的 TypeScript 接口。

cli.test.ts 对该封装进行了单元测试，重点覆盖参数序列化、跨平台路径处理以及子进程异常时的错误传播路径。

资料来源：dashboard/src/lib/cli.ts、dashboard/src/lib/cli.test.ts

样式合并工具

cn.ts 是一个轻量级的 className 合并工具。该文件命名遵循前端社区常见约定（cn = classNames），通常在内部使用 clsx 等小型依赖对多个条件类名进行合并、去重与覆盖解析，便于 React 组件在 Tailwind CSS 体系下组合出无冲突的样式字符串。

资料来源：dashboard/src/lib/cn.ts

配置层

config.ts 在仪表盘启动时读取并解析运行时配置，包括 ANAMNESIS_HOME、ANAMNESIS_MACHINE_ID 等环境变量，以及磁盘上的 config.json。v0.1.3 修复了 anamnesis init 对这些环境变量的尊重问题，Lib 模块中的 config 层是这一修复的直接受益方——自定义存储目录与机器标识的用户可以在仪表盘 UI 与底层存储之间获得一致的路径行为。

config.test.ts 覆盖了配置解析的关键路径：默认值回退、与现有 config.json 的合并、以及用户主目录（~）展开等。

资料来源：dashboard/src/lib/config.ts、dashboard/src/lib/config.test.ts

数据库访问层

db.test.ts 的存在表明 dashboard/src/lib/ 中存在一个数据库访问模块（db.ts），用于在前端仪表盘中读取 SQLite FTS5 索引数据。该模块通常会把底层 SQL 结果投影为仪表盘友好的结构（例如按时间线、来源机器、标签等维度分组），并通过测试保证其只读语义不会破坏本地存储的事务完整性。

资料来源：dashboard/src/lib/db.test.ts

数据流概览

这一分层让上层组件只关心"调用什么"，而把子进程启动、文件 I/O 与 SQL 查询的实现细节完全隐藏在 Lib 层之下。

测试策略

*.test.ts 与主源文件一一对应，构成"代码即测试"的最小闭环：db.test.ts 一般使用临时目录下的 SQLite 文件以隔离测试环境；cli.test.ts 通过模拟子进程返回值来验证调用契约；config.test.ts 则聚焦环境变量与默认值的组合矩阵。

资料来源：dashboard/src/lib/cli.test.ts、dashboard/src/lib/config.test.ts、dashboard/src/lib/db.test.ts

社区关联

• v0.1.1（PR #3）引入了独立仪表盘入口，Lib 模块即是该入口的前端底座。
• v0.1.3 修复了 init 命令对 ANAMNESIS_HOME 与 ANAMNESIS_MACHINE_ID 的支持问题，自定义存储路径的 fleet 脚本用户可以依赖 Lib 模块中的 config 层，保证 UI 与底层存储读取到一致的环境配置。

dashboard/src/app/api 是 Anamnesis 仪表盘的 Next.js App Router 路由层，承担本地优先（local-first）存储之上的 HTTP 接口职责。所有路由都把 SQLite FTS5 索引的 memory store 暴露为可消费的 JSON 接口，让仪表盘前端、独立仪表盘（npx anamnesis-dashboard）以及跨机器同步流程都可以复用同一套数据契约 资料来源：dashboard/src/app/api/fleet/route.ts:1-30。

目录结构与职责划分

src/app/api 下的每个子目录对应一个 REST 资源端点，遵循 Next.js 的 file-based routing 约定：

• backfill-provenance/route.ts — 用于回填历史笔记的来源（provenance）信息
• commits/[hash]/route.ts — 按 commit hash 查询某次同步的提交详情
• fleet/route.ts — 跨机器视图，列出当前 store 中所有机器及其状态
• graph/route.ts — 提供笔记之间关系的图数据，供前端可视化使用
• history/route.ts — 返回 store 的历史记录流
• notes/[id]/diff/route.ts — 计算并返回指定笔记在两次提交之间的差异

这套结构与 v0.0.2 起确立的「markdown 是真源、SQLite FTS5 是索引、git 是同步通道」的本地优先三件套保持一致 资料来源：[dashboard/src/app/api/notes/[id]/diff/route.ts:1-25]()。

核心端点行为

fleet/route.ts 汇总所有已注册机器的清单和心跳信息，是多机部署场景下观察 store 健康度的主入口 资料来源：dashboard/src/app/api/fleet/route.ts:15-45。graph/route.ts 从 memory store 中抽取笔记引用、链接和嵌入相似度，构建可视化图谱，支撑仪表盘的关系网络视图 资料来源：dashboard/src/app/api/graph/route.ts:20-60。

notes/[id]/diff/route.ts 接收笔记 ID 和可选的 base/target commit 参数，返回两份 markdown 之间的逐行差异，方便审计记忆演化过程 资料来源：[dashboard/src/app/api/notes/[id]/diff/route.ts:30-55]()。commits/[hash]/route.ts 提供单次同步提交的全量元数据，包含变更文件、影响行数和时间戳 资料来源：[dashboard/src/app/api/commits/[hash]/route.ts:10-40]()。

history/route.ts 以分页方式返回操作历史，支撑时间线 UI 资料来源：dashboard/src/app/api/history/route.ts:12-35。backfill-provenance/route.ts 是一个写操作端点，用于为历史笔记补全 provenance 字段，确保上游 LLM 反思生成的笔记都能追溯来源 资料来源：dashboard/src/app/api/backfill-provenance/route.ts:8-28。

数据流与一致性

仪表盘前端通过这些路由与本地 store 进行读写交互。由于所有路由共享同一个 SQLite 数据库连接（WAL 模式），读端点和写端点之间具备事务一致性 资料来源：dashboard/src/app/api/history/route.ts:1-15。当 LLM 反思通道写入新笔记后，history 和 fleet 端点能立即看到结果，无需额外同步步骤。

下表汇总了各路由的语义契约：

这些接口共同支撑了 v0.1.x 引入的独立仪表盘模式（anamnesis dashboard / npx anamnesis-dashboard），使得任意节点都能在浏览器中查看全网记忆状态，而无需直接访问本地文件系统 资料来源：dashboard/src/app/api/fleet/route.ts:1-30。

server 子包是 Anamnesis 的运行时核心，作为 MCP（Model Context Protocol）服务器承载整套本地优先记忆能力。它通过 FastMCP 向 Claude Code 等 MCP 客户端暴露 memory_search、memory_list、memory_status、memory_write、memory_sync 等工具，使 AI 助手能够读写跨机器同步的 Markdown 记忆库。资料来源：server/README.md:1-40

角色与定位

在仓库的整体分层中，server 负责把"以 Markdown 为事实源、SQLite FTS5 为索引"的本地存储抽象成稳定的远程过程调用接口，同时承担初始化、同步、状态查询等运维动作。其设计目标是：

• 本地优先（local-first）：所有记忆的真理源是磁盘上的 Markdown 文件，而非数据库或远端服务。资料来源：server/src/anamnesis/capture.py:1-40
• 跨机器一致：通过 Git 同步机制让多台机器共享同一份记忆。
• MCP 标准化：遵循 MCP 注册表规范，便于被各种客户端发现和接入。v0.1.2 引入了 MCP 注册表所有权标记，确立该子包在生态中的归属。资料来源：server/pyproject.toml:1-40

模块结构

server/
├── README.md
├── pyproject.toml
└── src/anamnesis/
    ├── __init__.py     # 包导出与版本声明
    ├── capture.py      # 会话日志捕获与结构化
    ├── cli.py          # 命令行入口（init / sync / dashboard）
    └── config.py       # 配置加载与 ANAMNESIS_HOME 解析

各文件职责清晰分层：config.py 解析环境变量与 config.json，capture.py 处理会话层数据的摄入，cli.py 提供面向用户的命令接口，__init__.py 负责对外暴露统一入口。资料来源：server/src/anamnesis/__init__.py:1-20

配置与初始化流程

server 的所有运行时行为由配置驱动。config.py 集中处理 ANAMNESIS_HOME、ANAMNESIS_MACHINE_ID 等关键环境变量，确保即便用户自定义存储位置，初始化与首次同步也能正确落地。资料来源：server/src/anamnesis/config.py:1-60

初始化与首次同步的关键路径如下：

flowchart LR
    A[anamnesis init] --> B[读取 ANAMNESIS_HOME]
    B --> C[读取 ANAMNESIS_MACHINE_ID]
    C --> D[写入 config.json]
    D --> E[触发首次 memory_sync]
    E --> F[Git 远端拉取/推送]

v0.1.3 修复了 init 命令在自定义 ANAMNESIS_HOME 下仍然写回 ~/.anamnesis 的问题，并保证对已存在存储再次执行 init 时不会破坏现有配置。该修复主要影响多机脚本与运维场景，普通本地安装不受影响。资料来源：server/src/anamnesis/cli.py:1-80

MCP 工具接口

通过 FastMCP 暴露的工具构成客户端可调用的最小操作集：

这些工具把磁盘上的 Markdown 与 FTS5 索引桥接起来，使得上层 Agent 无需关心文件级细节即可完成"读、查、写、同步"四类操作。资料来源：server/README.md:1-60

独立仪表盘

自 v0.1.1 起，server 子包可以通过 npx anamnesis-dashboard 或 anamnesis dashboard 命令启动独立 Web 仪表盘，用于可视化浏览本地记忆库。该能力与 MCP 服务器共用底层存储，但走独立的 HTTP 入口，方便非 Claude Code 场景下人工审阅记忆。资料来源：server/src/anamnesis/cli.py:80-140

小结

server 模块既是 Anamnesis 的运行时容器，也是面向 MCP 客户端的稳定 API 边界。其本地优先、文件即真理的设计哲学，配合 FTS5 索引与 Git 同步，使记忆层在保持轻量的同时具备跨机器一致性；通过标准化的 MCP 工具与独立仪表盘，又兼顾了自动化与人工可观测性两端的使用需求。

概述与定位

Api 模块是 anamnesis 仪表板（dashboard）暴露的 HTTP 路由层，位于仓库 dashboard/src/app/api/ 目录下，采用 Next.js App Router 的 route.ts 文件约定实现。它的职责是为浏览器仪表板前端提供结构化数据，本身不直接承担 markdown 笔记的读写——笔记与索引的真实来源是本地优先的 SQLite FTS5 索引层以及 git 同步层。资料来源：dashboard/src/app/api/history/route.ts:1-30

该模块与项目内的 MCP server（FastMCP 提供的 memory_search / memory_list / memory_status / memory_write / memory_sync）平行存在：MCP server 面向 Claude Code 等 AI Agent，而 Api 模块面向浏览器仪表板用户，两套接口共用同一份本地数据源和同一套环境变量（ANAMNESIS_HOME 与 ANAMNESIS_MACHINE_ID）。

路由清单

资料来源：dashboard/src/app/api/backfill-provenance/route.ts:1-40、[dashboard/src/app/api/commits/[hash]/route.ts:1-40]()、dashboard/src/app/api/fleet/route.ts:1-40、dashboard/src/app/api/graph/route.ts:1-40、[dashboard/src/app/api/notes/[id]/diff/route.ts:1-40]()

数据流与依赖

Api 模块的请求流程可以概括为：浏览器发起请求 → Next.js 路由处理器读取 ANAMNESIS_HOME 指向的本地存储 → 查询 SQLite 索引或执行 git 命令 → 返回 JSON 给前端。fleet 与 commits 路由都需要结合 git 历史来回答，因此对底层仓库的完整同步状态有依赖；如果 memory_sync 尚未在该机器上执行过，相关端点可能返回空集或仅展示本地结果。资料来源：dashboard/src/app/api/fleet/route.ts:1-50、[dashboard/src/app/api/commits/[hash]/route.ts:1-50]()

flowchart LR
  Browser[浏览器仪表板] -->|HTTP 请求| Route[route.ts 处理器]
  Route --> Env[ANAMNESIS_HOME / ANAMNESIS_MACHINE_ID]
  Route --> SQLite[(SQLite FTS5 索引)]
  Route --> Git[git log / git diff]
  SQLite --> Markdown[(markdown 源文件)]
  Git --> Markdown
  Route -->|JSON 响应| Browser

backfill-provenance 是少数带副作用的端点，它会向存量笔记补充 provenance 元数据，避免早期版本中笔记缺失追溯信息。该路由通常在升级或迁移后被调用一次，属于运维型接口而非日常查询接口。资料来源：dashboard/src/app/api/backfill-provenance/route.ts:1-60

与其他组件的关系

v0.1.3 修复了 anamnesis init 忽略 ANAMNESIS_HOME 与 ANAMNESIS_MACHINE_ID 的问题——之前在自定义存储目录下首次初始化时会写入默认的 ~/.anamnesis。这意味着 Api 模块在初始化完成后读取的环境变量与 CLI/MCP server 完全一致，从而保证仪表板展示的存储位置和实际写入位置不会出现错位。资料来源：dashboard/src/app/api/history/route.ts:1-30、dashboard/src/app/api/fleet/route.ts:1-50

仪表板的 /api/graph 与 /api/history 通常成对使用：前者用于绘制记忆关系图，后者用于时间线视图，两者共享相同的底层索引，渲染逻辑也常放在同一页面。/api/notes/[id]/diff 则强依赖 git 历史，必须在已执行过 memory_sync 的存储上才能返回非空的差异结果，因此与 commits/[hash] 端点在数据准备条件上是耦合的。资料来源：[dashboard/src/app/api/notes/[id]/diff/route.ts:1-50]()、dashboard/src/app/api/graph/route.ts:1-40

Pitfall Log / 踩坑日志

项目：oscardvs/anamnesis

摘要：发现 12 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: v0.0.2。

1. 安装坑 · 失败模式：installation: v0.0.2

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.0.2
• 对用户的影响：Upgrade or migration may change expected behavior: v0.0.2
• 证据：failure_mode_cluster:github_release | https://github.com/oscardvs/anamnesis/releases/tag/v0.0.2 | v0.0.2

2. 安装坑 · 失败模式：installation: v0.1.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.1.0
• 对用户的影响：Upgrade or migration may change expected behavior: v0.1.0
• 证据：failure_mode_cluster:github_release | https://github.com/oscardvs/anamnesis/releases/tag/v0.1.0 | v0.1.0

3. 安装坑 · 失败模式：installation: v0.1.1

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.1.1
• 对用户的影响：Upgrade or migration may change expected behavior: v0.1.1
• 证据：failure_mode_cluster:github_release | https://github.com/oscardvs/anamnesis/releases/tag/v0.1.1 | v0.1.1

4. 安装坑 · 失败模式：installation: v0.1.3

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.1.3
• 对用户的影响：Upgrade or migration may change expected behavior: v0.1.3
• 证据：failure_mode_cluster:github_release | https://github.com/oscardvs/anamnesis/releases/tag/v0.1.3 | v0.1.3

5. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/oscardvs/anamnesis | host_targets=mcp_host, claude_code, claude, chatgpt

6. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/oscardvs/anamnesis | README/documentation is current enough for a first validation pass.

7. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/oscardvs/anamnesis | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/oscardvs/anamnesis | no_demo; severity=medium

9. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/oscardvs/anamnesis | no_demo; severity=medium

10. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/oscardvs/anamnesis | issue_or_pr_quality=unknown

11. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/oscardvs/anamnesis | release_recency=unknown

12. 维护坑 · 失败模式：maintenance: v0.1.2

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v0.1.2
• 对用户的影响：Upgrade or migration may change expected behavior: v0.1.2
• 证据：failure_mode_cluster:github_release | https://github.com/oscardvs/anamnesis/releases/tag/v0.1.2 | v0.1.2