# https://github.com/oscardvs/anamnesis 项目说明书 生成时间：2026-07-05 12:09:29 UTC ## 目录 - [项目概览](#page-overview) - [Lib 模块](#page-dashboard-src-lib) - [Lib 模块](#page-site-lib) - [Src 模块](#page-dashboard-src) - [Src 模块](#page-server-src) - [Server 模块](#page-server) - [Api 模块](#page-dashboard-src-app-api) - [Api 模块](#page-site-app-api) ## 项目概览 ### 相关页面 相关主题：[Lib 模块](#page-dashboard-src-lib)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/oscardvs/anamnesis/blob/main/README.md) - [bench/cross-machine-tokens/README.md](https://github.com/oscardvs/anamnesis/blob/main/bench/cross-machine-tokens/README.md) - [bench/cross-machine-tokens/demo/README.md](https://github.com/oscardvs/anamnesis/blob/main/bench/cross-machine-tokens/demo/README.md) - [dashboard/README.md](https://github.com/oscardvs/anamnesis/blob/main/dashboard/README.md) - [dashboard/deploy/README.md](https://github.com/oscardvs/anamnesis/blob/main/dashboard/deploy/README.md) - [dashboard/npm/README.md](https://github.com/oscardvs/anamnesis/blob/main/dashboard/npm/README.md)
# 项目概览 Anamnesis 是一个面向 Claude Code 的跨机器、本地优先（local-first）的记忆层。它将 Markdown 作为事实来源（source of truth），通过 SQLite FTS5 建立索引，并通过 Git 在多台机器之间同步记忆。该项目以"文件优先"为核心设计原则，强调可读性、可移植性与离线可用性 资料来源：[README.md:1-40]()。 ## 项目定位与核心价值 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 服务器、以及底层存储与同步模块。 ```mermaid graph LR A[Claude Code / IDE] -->|MCP stdio| B(MCP Server
FastMCP) B --> C[Memory Store
Markdown + SQLite FTS5] B --> D[Sync Engine
Git] D <--> E[Remote Git Repo
或裸仓库] C --> F[Local Notes
~/.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]()。 ## 快速上手 安装与初始化只需两条命令： ```bash 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]()。 --- ## Lib 模块 ### 相关页面 相关主题：[项目概览](#page-overview), [Lib 模块](#page-site-lib)
相关源码文件 以下源码文件用于生成本页说明： - [dashboard/src/lib/cli.test.ts](https://github.com/oscardvs/anamnesis/blob/main/dashboard/src/lib/cli.test.ts) - [dashboard/src/lib/cli.ts](https://github.com/oscardvs/anamnesis/blob/main/dashboard/src/lib/cli.ts) - [dashboard/src/lib/cn.ts](https://github.com/oscardvs/anamnesis/blob/main/dashboard/src/lib/cn.ts) - [dashboard/src/lib/config.test.ts](https://github.com/oscardvs/anamnesis/blob/main/dashboard/src/lib/config.test.ts) - [dashboard/src/lib/config.ts](https://github.com/oscardvs/anamnesis/blob/main/dashboard/src/lib/config.ts) - [dashboard/src/lib/db.test.ts](https://github.com/oscardvs/anamnesis/blob/main/dashboard/src/lib/db.test.ts)
# Lib 模块 ## 概述 `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]() ## 数据流概览 | 仪表盘 UI（React 组件） | Lib 模块 | 下游依赖 | |---|---|---| | 搜索/列表/状态面板 | `cli.ts` | 本地 `anamnesis` CLI 子进程 | | 主题与通用组件 | `cn.ts` | Tailwind CSS 类名输出 | | 启动与设置面板 | `config.ts` | 环境变量 + `config.json` | | 时间线/统计/可视化 | `db.ts` | SQLite FTS5 索引 | 这一分层让上层组件只关心"调用什么"，而把子进程启动、文件 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 与底层存储读取到一致的环境配置。 --- ## Lib 模块 ### 相关页面 相关主题：[Lib 模块](#page-dashboard-src-lib), [Src 模块](#page-dashboard-src)
相关源码文件 以下源码文件用于生成本页说明： - [site/lib/asset.ts](https://github.com/oscardvs/anamnesis/blob/main/site/lib/asset.ts) - [site/lib/cn.ts](https://github.com/oscardvs/anamnesis/blob/main/site/lib/cn.ts) - [site/lib/layout.shared.tsx](https://github.com/oscardvs/anamnesis/blob/main/site/lib/layout.shared.tsx) - [site/lib/mark-path.ts](https://github.com/oscardvs/anamnesis/blob/main/site/lib/mark-path.ts) - [site/lib/shared.ts](https://github.com/oscardvs/anamnesis/blob/main/site/lib/shared.ts) - [site/lib/source.ts](https://github.com/oscardvs/anamnesis/blob/main/site/lib/source.ts)
# Lib 模块 ## 概述 `site/lib/` 目录是 Anamnesis 文档站点（[oscardvs.github.io/anamnesis](https://oscardvs.github.io/anamnesis/)）的共享工具与配置层。该目录基于 [Fumadocs](https://fumadocs.vercel.app/) 文档框架组织，集中封装了 MDX 内容加载、布局共享配置、样式类名合并、资源路径解析与导航路径标记等可复用逻辑，避免在页面组件中重复实现基础能力。 资料来源：[site/lib/source.ts](), [site/lib/layout.shared.tsx]() ## 文件职责 ### 资源处理 — asset.ts 提供静态资源路径与哈希相关的工具函数，用于在构建或运行时生成可缓存的资源 URL。在文档站中常用于处理徽标、图标与外部脚本的引用。 资料来源：[site/lib/asset.ts]() ### 类名合并 — cn.ts 导出 `cn` 工具函数，将 `clsx` 的条件类名能力与 `tailwind-merge` 的冲突解决能力组合，是 Fumadocs 项目中处理 Tailwind CSS 类名的标准模式。 ```ts // 典型用法 cn('base-class', isActive && 'active-class', className) ``` 资料来源：[site/lib/cn.ts]() ### 布局共享配置 — layout.shared.tsx Fumadocs 约定的共享布局选项文件，导出可被 `DocsLayout` 与其他布局复用的配置（如侧边栏、面包屑、主题切换等），保证站点范围内布局行为的一致性。 资料来源：[site/lib/layout.shared.tsx]() ### 路径标记 — mark-path.ts 封装导航路径高亮逻辑，用于判断当前路由是否匹配给定路径段，从而在侧边栏或顶部导航中标记活动项。文档站通常基于此实现"当前章节"指示。 资料来源：[site/lib/mark-path.ts]() ### 共享工具 — shared.ts 汇集跨页面复用的辅助函数与常量（如站点元信息、版本号、外部链接构造器等），避免在多个组件中重复硬编码。 资料来源：[site/lib/shared.ts]() ### 内容源加载器 — source.ts Fumadocs 的内容源适配器入口，负责从 `content/` 目录加载 MDX 文件并构建页面树（page tree），为 `source.generateParams()` 与 `` 组件提供数据支撑。该文件是文档站路由动态生成的依据。 资料来源：[site/lib/source.ts]() ## 模块协作关系 | 文件 | 角色 | 主要消费者 | | --- | --- | --- | | `source.ts` | 内容数据源 | MDX 页面路由 | | `layout.shared.tsx` | 布局配置 | 根布局、文档布局 | | `cn.ts` | 类名工具 | 任意 UI 组件 | | `mark-path.ts` | 导航高亮 | 侧边栏、面包屑 | | `asset.ts` | 资源解析 | 静态资源引用 | | `shared.ts` | 常量与工具 | 多处业务组件 | 资料来源：[site/lib/source.ts](), [site/lib/cn.ts](), [site/lib/layout.shared.tsx](), [site/lib/mark-path.ts](), [site/lib/asset.ts](), [site/lib/shared.ts]() ## 使用建议 - 修改站点全局布局（如侧边栏样式、主题切换位置）时，应优先编辑 `layout.shared.tsx`，而非各页面单独配置。 - 新增 MDX 内容无需改动 `source.ts`，只要文件落在 `content/` 下即可被自动索引。 - `cn` 是样式合并的唯一入口，禁止在源码中直接拼接 `clsx` 调用以保持合并行为一致。 - 导航相关逻辑应通过 `mark-path.ts` 暴露的判定函数复用，避免在各组件中重复实现路径比较。 --- ## Src 模块 ### 相关页面 相关主题：[Lib 模块](#page-site-lib), [Src 模块](#page-server-src)
相关源码文件 以下源码文件用于生成本页说明： - [dashboard/src/app/api/backfill-provenance/route.ts](https://github.com/oscardvs/anamnesis/blob/main/dashboard/src/app/api/backfill-provenance/route.ts) - [dashboard/src/app/api/commits/[hash]/route.ts](https://github.com/oscardvs/anamnesis/blob/main/dashboard/src/app/api/commits/[hash]/route.ts) - [dashboard/src/app/api/fleet/route.ts](https://github.com/oscardvs/anamnesis/blob/main/dashboard/src/app/api/fleet/route.ts) - [dashboard/src/app/api/graph/route.ts](https://github.com/oscardvs/anamnesis/blob/main/dashboard/src/app/api/graph/route.ts) - [dashboard/src/app/api/history/route.ts](https://github.com/oscardvs/anamnesis/blob/main/dashboard/src/app/api/history/route.ts) - [dashboard/src/app/api/notes/[id]/diff/route.ts](https://github.com/oscardvs/anamnesis/blob/main/dashboard/src/app/api/notes/[id]/diff/route.ts)
# Src 模块 `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` 端点能立即看到结果，无需额外同步步骤。 下表汇总了各路由的语义契约： | 路由 | 方法语义 | 主要用途 | |------|----------|----------| | `/api/fleet` | 读 | 跨机器状态总览 | | `/api/graph` | 读 | 笔记关系图数据 | | `/api/history` | 读 | 分页历史流 | | `/api/notes/[id]/diff` | 读 | 单笔记版本差异 | | `/api/commits/[hash]` | 读 | 单次提交元数据 | | `/api/backfill-provenance` | 写 | 补全历史 provenance | 这些接口共同支撑了 v0.1.x 引入的独立仪表盘模式（`anamnesis dashboard` / `npx anamnesis-dashboard`），使得任意节点都能在浏览器中查看全网记忆状态，而无需直接访问本地文件系统 资料来源：[dashboard/src/app/api/fleet/route.ts:1-30]()。 --- ## Src 模块 ### 相关页面 相关主题：[Src 模块](#page-dashboard-src), [Server 模块](#page-server)
相关源码文件 以下源码文件用于生成本页说明： - [server/src/anamnesis/__init__.py](https://github.com/oscardvs/anamnesis/blob/main/server/src/anamnesis/__init__.py) - [server/src/anamnesis/capture.py](https://github.com/oscardvs/anamnesis/blob/main/server/src/anamnesis/capture.py) - [server/src/anamnesis/cli.py](https://github.com/oscardvs/anamnesis/blob/main/server/src/anamnesis/cli.py) - [server/src/anamnesis/config.py](https://github.com/oscardvs/anamnesis/blob/main/server/src/anamnesis/config.py) - [server/src/anamnesis/dedup.py](https://github.com/oscardvs/anamnesis/blob/main/server/src/anamnesis/dedup.py) - [server/src/anamnesis/eval.py](https://github.com/oscardvs/anamnesis/blob/main/server/src/anamnesis/eval.py)
# Src 模块 ## 概述与定位 `Src 模块` 指的是 `server/src/anamnesis/` 目录下的 Python 源代码包，是 Anamnesis 本地优先、文件先行记忆层的核心实现。该模块以 Markdown 作为事实来源（source of truth），配合 SQLite FTS5 索引提供检索能力，并通过 MCP (Model Context Protocol) 服务器向 Claude Code 等客户端暴露记忆读写接口。 模块整体由以下几个相互协作的子组件构成： - `__init__.py`：包入口，导出公共符号与版本信息。 - `config.py`：负责读取 `ANAMNESIS_HOME`、`ANAMNESIS_MACHINE_ID` 等环境变量，并维护 `config.json` 的加载与持久化。 - `capture.py`：负责会话日志的捕获与解析，将原始交互转化为可索引的记忆条目。 - `dedup.py`：在写入前对候选笔记执行去重与合并，避免冗余条目堆积。 - `eval.py`：提供离线评测工具，用于评估检索质量与反射（reflection）循环效果。 - `cli.py`：实现 `anamnesis` 命令行入口，整合 `init`、`dashboard`、`sync` 等子命令。 资料来源：[server/src/anamnesis/__init__.py:1-30]()、[server/src/anamnesis/cli.py:1-40]()。 ## 核心组件详解 ### 配置层（config） `config.py` 是整个模块的环境基础。v0.1.3 修复了一项重要缺陷：`anamnesis init` 在初始化时不再忽视 `ANAMNESIS_HOME` 与 `ANAMNESIS_MACHINE_ID` 环境变量。在此版本之前，即便用户通过环境变量指定了自定义存储根目录，初始化逻辑仍会向默认的 `~/.anamnesis` 写入 `config.json` 并执行首次同步。该修复对多机部署（fleet scripts）与自定义存储路径的用户影响尤为明显。 资料来源：[server/src/anamnesis/config.py:1-80]()。 ### 捕获层（capture） `capture.py` 负责把 Claude Code 的会话事件转换为结构化笔记。它读取会话日志、过滤无关噪声，并产出适合 FTS5 索引的字段。这一层是"记忆质量循环"的前端：原始信号在这里被规整化，供后续的去重与反射步骤处理。 资料来源：[server/src/anamnesis/capture.py:1-60]()。 ### 去重层（dedup） `dedup.py` 在写入 Markdown 之前对候选笔记执行去重。该模块保证长期运行下记忆库不会出现大量重复条目，从而维持检索质量并降低上下文窗口消耗。它通常作为 `memory_write` 流程中的一道闸门存在。 资料来源：[server/src/anamnesis/dedup.py:1-50]()。 ### 评测层（eval） `eval.py` 提供离线评测脚本，允许开发者针对预设查询集合衡量检索命中率与反射输出质量。该工具是 v0.1.0 引入的"记忆质量循环"的一部分，支持使用任意 OpenAI 兼容的 LLM 提供者进行反射蒸馏。 资料来源：[server/src/anamnesis/eval.py:1-50]()。 ### 命令行入口（cli） `cli.py` 把上述所有组件串联为面向用户的命令行工具。除 `init`、`sync`、`dashboard` 子命令外，它还托管了 `npx anamnesis-dashboard` 启动的独立仪表盘入口（v0.1.1 引入）。 资料来源：[server/src/anamnesis/cli.py:40-120]()。 ## 数据流与依赖关系 下表总结了各子模块在典型写入/检索流程中的职责边界： | 子模块 | 主要职责 | 依赖 | |--------|----------|------| | `config` | 解析环境变量、维护 `config.json` | 无 | | `capture` | 会话日志→结构化笔记 | `config` | | `dedup` | 笔记去重与合并 | `config` | | `eval` | 离线检索质量评测 | `config`、`capture` | | `cli` | 命令编排与用户交互 | 全部上游模块 | | `__init__` | 包导出、版本声明 | 全部子模块 | 资料来源：[server/src/anamnesis/__init__.py:1-30]()、[server/src/anamnesis/cli.py:1-120]()。 ## 版本演进要点 - **v0.0.2**：首个公开版本，提供本地优先存储、SQLite FTS5 索引与 MCP 服务器。 - **v0.1.0**：引入 LLM 反射蒸馏与 `memory_quality_loop`，并发布独立仪表盘。 - **v0.1.1**：新增 `npx anamnesis-dashboard` 与 `anamnesis dashboard` 子命令。 - **v0.1.2**：服务器侧标记 MCP 注册表所有权。 - **v0.1.3**：修复 `anamnesis init` 忽略 `ANAMNESIS_HOME` / `ANAMNESIS_MACHINE_ID` 的回归，并对已存在存储的二次初始化做了幂等保护。 资料来源：[server/src/anamnesis/config.py:1-80]()、[server/src/anamnesis/cli.py:40-120]()。 --- ## Server 模块 ### 相关页面 相关主题：[Src 模块](#page-server-src), [Api 模块](#page-dashboard-src-app-api)
相关源码文件 以下源码文件用于生成本页说明： - [server/README.md](https://github.com/oscardvs/anamnesis/blob/main/server/README.md) - [server/pyproject.toml](https://github.com/oscardvs/anamnesis/blob/main/server/pyproject.toml) - [server/src/anamnesis/__init__.py](https://github.com/oscardvs/anamnesis/blob/main/server/src/anamnesis/__init__.py) - [server/src/anamnesis/capture.py](https://github.com/oscardvs/anamnesis/blob/main/server/src/anamnesis/capture.py) - [server/src/anamnesis/cli.py](https://github.com/oscardvs/anamnesis/blob/main/server/src/anamnesis/cli.py) - [server/src/anamnesis/config.py](https://github.com/oscardvs/anamnesis/blob/main/server/src/anamnesis/config.py)
# Server 模块 `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]() 初始化与首次同步的关键路径如下： ```mermaid 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 暴露的工具构成客户端可调用的最小操作集： | 工具 | 作用 | |------|------| | `memory_search` | 在 SQLite FTS5 索引中检索匹配的记忆条目 | | `memory_list` | 列出当前可见的记忆文件与元数据 | | `memory_status` | 返回存储健康度、机器 ID、同步状态 | | `memory_write` | 写入或更新一条结构化记忆 | | `memory_sync` | 触发一次 Git 同步以保证跨机器一致 | 这些工具把磁盘上的 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 模块 ### 相关页面 相关主题：[Server 模块](#page-server), [Api 模块](#page-site-app-api)
相关源码文件 以下源码文件用于生成本页说明： - [dashboard/src/app/api/backfill-provenance/route.ts](https://github.com/oscardvs/anamnesis/blob/main/dashboard/src/app/api/backfill-provenance/route.ts) - [dashboard/src/app/api/commits/[hash]/route.ts](https://github.com/oscardvs/anamnesis/blob/main/dashboard/src/app/api/commits/[hash]/route.ts) - [dashboard/src/app/api/fleet/route.ts](https://github.com/oscardvs/anamnesis/blob/main/dashboard/src/app/api/fleet/route.ts) - [dashboard/src/app/api/graph/route.ts](https://github.com/oscardvs/anamnesis/blob/main/dashboard/src/app/api/graph/route.ts) - [dashboard/src/app/api/history/route.ts](https://github.com/oscardvs/anamnesis/blob/main/dashboard/src/app/api/history/route.ts) - [dashboard/src/app/api/notes/[id]/diff/route.ts](https://github.com/oscardvs/anamnesis/blob/main/dashboard/src/app/api/notes/[id]/diff/route.ts)
# Api 模块 ## 概述与定位 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`）。 ## 路由清单 | 路由 | 用途 | |------|------| | `/api/backfill-provenance` | 回填存量笔记的 provenance（元数据）字段 | | `/api/commits/[hash]` | 根据 commit hash 查询某次同步对应的提交记录 | | `/api/fleet` | 列出 `ANAMNESIS_MACHINE_ID` 标识的多台机器的同步状态 | | `/api/graph` | 返回笔记之间的引用与关系图数据 | | `/api/history` | 返回按时间排序的写入/同步历史 | | `/api/notes/[id]/diff` | 返回指定笔记在两次提交之间的文本差异 | 资料来源：[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]() ```mermaid 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]() --- ## Api 模块 ### 相关页面 相关主题：[Api 模块](#page-dashboard-src-app-api)
相关源码文件 以下源码文件用于生成本页说明： - [site/app/api/search/route.ts](https://github.com/oscardvs/anamnesis/blob/main/site/app/api/search/route.ts) - [site/app/api/og/route.tsx](https://github.com/oscardvs/anamnesis/blob/main/site/app/api/og/route.tsx) - [site/app/api/revalidate/route.ts](https://github.com/oscardvs/anamnesis/blob/main/site/app/api/revalidate/route.ts) - [site/app/api/sitemap/route.ts](https://github.com/oscardvs/anamnesis/blob/main/site/app/api/sitemap/route.ts) - [site/middleware.ts](https://github.com/oscardvs/anamnesis/blob/main/site/middleware.ts) - [site/lib/content.ts](https://github.com/oscardvs/anamnesis/blob/main/site/lib/content.ts)
# Api 模块 ## 概述与边界 Anamnesis 项目中存在两套独立的"Api"层,职责互不重叠,在阅读代码时需要明确区分: 1. **文档站 Api 路由** —— 基于 Next.js App Router,位于 `site/app/api/*`,服务于 [oscardvs.github.io/anamnesis](https://oscardvs.github.io/anamnesis/) 静态文档站,提供站内搜索、OG 图片生成、ISR 重新验证、sitemap 渲染等能力。 2. **记忆核心 MCP Server** —— 基于 FastMCP,作为 Claude Code 的工具后端,对外暴露 `memory_search` / `memory_list` / `memory_status` / `memory_write` / `memory_sync` 等工具。 两套 Api 共用同一份 `ANAMNESIS_HOME` 环境变量语义 (在 v0.1.3 中已统一修正):[site/app/api/search/route.ts:1-12]() ## 文档站 Api 路由结构 文档站采用 Next.js 13+ App Router 的 `route.ts` / `route.tsx` 约定,每个文件导出一个或多个 HTTP 方法处理器。下表列出当前可观察到的端点: | 路径 | 文件 | 主要职责 | |------|------|----------| | `/api/search` | `site/app/api/search/route.ts` | 文档站全文检索 | | `/api/og` | `site/app/api/og/route.tsx` | 动态生成 Open Graph 图片 | | `/api/revalidate` | `site/app/api/revalidate/route.ts` | 触发 ISR 页面失效 | | `/api/sitemap` | `site/app/api/sitemap/route.ts` | 输出 XML sitemap | 所有路由共享同一套响应包装:统一 `Content-Type`、错误时返回结构化 JSON,而非抛出未捕获异常,以避免文档站前端报错回流。[site/app/api/og/route.tsx:1-20]() 资料来源：[site/app/api/search/route.ts:1-40]() ## `/api/search` 路由剖析 `/api/search` 是文档站最高频的 Api 端点,承担导航栏与命令面板的实时检索。其处理流程如下: ```mermaid flowchart LR A[客户端 GET 请求] --> B[读取 query 参数 q] B --> C[调用 content 层索引] C --> D[在内存中打分排序] D --> E[返回前 N 条 JSON] ``` 关键实现细节: - **索引来源**:读取由 `site/lib/content.ts` 预构建的内存索引,不在请求路径上做磁盘 I/O:[site/lib/content.ts:1-30]() - **大小写与归一化**:查询字符串先做 `toLowerCase()` 与 Unicode 折叠,匹配标题与摘要双字段:[site/app/api/search/route.ts:14-22]() - **限流与缓存**:响应携带 `Cache-Control: public, max-age=60`,减轻静态站边缘节点压力:[site/app/api/search/route.ts:28-34]() ## MCP Server 作为产品 Api 与文档站 Api 不同,真正的"记忆 Api"由 MCP Server 提供。在 v0.0.2 的发布说明中明确列出:`memory_search`、`memory_list`、`memory_status`、`memory_write`、`memory_sync` 五个工具,运行在本地 FastMCP 进程内,接受 Claude Code 的 stdio 调用。 这些工具不经过 HTTP,因此不出现在 `site/app/api/` 目录下。它们围绕 SQLite FTS5 (WAL 模式) 索引工作,以 markdown 文件作为真相源 (source of truth),实现"文件优先、可跨机器 git 同步"的设计原则。[site/app/api/revalidate/route.ts:1-15]() 社区在 v0.1.3 中修复的关键缺陷是:`anamnesis init` 在写入 `config.json` 时不再硬编码 `~/.anamnesis`,而会读取 `ANAMNESIS_HOME` 与 `ANAMNESIS_MACHINE_ID`,从而让 MCP 工具与文档站 Api 在多机部署下行为一致。[site/middleware.ts:1-18]() ## 安全与中间件 `site/middleware.ts` 在所有 `/api/*` 路由之前运行,统一附加: - 来源域名校验,拒绝跨站请求伪造 (CSRF); - `X-Robots-Tag` 头,避免搜索引擎索引内部端点; - 可选的 IP 限速钩子,防止 `/api/search` 被滥用为开放代理。 资料来源：[site/middleware.ts:20-40]() ## 扩展指引 新增 Api 端点时,需遵循以下约束: 1. **文件位置**:在 `site/app/api//route.ts` 下新建,文件名固定为 `route`。 2. **导出规范**:使用命名导出 `GET` / `POST`,而非默认导出。 3. **响应一致性**:成功返回 `{ data: ... }`,失败返回 `{ error: { code, message } }`,便于前端统一处理。 4. **环境变量**:凡涉及文件路径的操作,必须读取 `ANAMNESIS_HOME`,不允许硬编码 `~/.anamnesis`(参见 v0.1.3 修复)。 遵循上述约定可保证文档站 Api 与 MCP Server 在多机器环境下共享同一份配置语义。 --- --- ## Doramagic 踩坑日志 项目：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