内容
# Memphis
<p align="center">
<img width="704" alt="memphis_github" src="https://github.com/user-attachments/assets/851ab1f8-9412-497c-8194-0b4cb4c4ea61" />
</p>
> "在孟菲斯建造了世界上最重要的纪念碑之一，即古代世界中唯一幸存的奇迹——吉萨大金字塔。"
**Memphis（MEM-phis）是一种全方位的记忆和上下文工具，适用于AI代理。** 它是一个单一的Go二进制文件，为代理提供两种知识，基于同一底层存储——纯Markdown + YAML前置信息，版本控制在Git中：
- **Canon（权威知识）** —— 您团队的**权威**知识：需求、决策、设计、路线图和提示，以Markdown格式记录，验证真实性，并在CI中强制执行。这是持久的记录系统 —— **什么是真实的**。代理**引用**它，而不是重新审议。
- **Reference（参考知识）** —— **摄入**的文档（爬取的网站、导入的仓库），以可导航的开放知识格式（OKF）"文件柜"呈现：丰富的、总结的和可搜索的支持材料 —— **事情如何运作**。
> **意图：** 代理的唯一真正约束是其上下文窗口。因此，任务是选择哪些真实、相关的令牌放入其中。memphis将两个属性分开，矢量数据库将这两个属性混淆 —— **权威**（这是团队同意的规范真相吗？）和**可发现性**（能否在正确的时间找到正确的信息？）—— 并通过MCP为代理提供两者。
> **记忆是Canon。上下文是Canon + Reference的预算投影。AI仅存在于投影中。底层存储是Git。**
### 哲学
- **权威优先。** Canon领先并被强制执行；Reference支持它。在同等相关性时，权威的制品优先于摄入的文档，每个Canon结果都带有可验证的引用及其生命周期状态。
- **在关键环节确定性。** 权威路径 —— 输入、验证、关系完整性、门控 —— 是一个纯粹的存储库状态函数，**没有LLM和没有网络**（失败的测试强制执行此约束）。AI被限制在发现/投影层，可以总结和排名，但不能决定什么是权威的。
- **没有数据库，没有锁定。** 真相的源头是Git中人类和代理可读的Markdown。搜索索引、关系图和总结是**派生投影**，您可以随意删除和重建。
- **在编写时捕获问题。** 不规范的知识在上线前被CI门控拒绝；摄入的参考文档则以宽容的态度处理。严格性与错误成本相匹配。
### 代理循环
**发现**（跨两个层级的模糊全文搜索）→ **定位**（解析命中的权威的、状态检查的Canon制品，跟踪更新到当前继承者）→ **组装**（打包到令牌预算中，优先考虑Canon，并保留规范要求文本原样）。代理模糊地回忆，然后立足于真相。
### 用例
- **阻止代理（和人员）违反已做出的决策。** 将ADRs和需求作为Canon捕获；代理检索**原因**并引用它。
- **使大型文档库可作为代理内存使用**，无需建立矢量存储 —— 爬取或导入到Reference包中，通过MCP提供。
- **在CI中强制执行需求质量** —— `memphis gate`检查BCP-14 / ISO 29148 / EARS一致性和关系完整性，发出SARIF。
- **将散布的文档提升为权威制品**，随着知识成熟，并将模糊的部分升级到外部RAG，当它超出文件柜范围时 —— 同时Canon始终在存储库中保持权威。
Canon权威模型是**代码需求（Requirements-as-Code）**引擎（rac-core）的忠实Go移植版；两个工具通过开放知识格式互操作。有关完整设计，请参见 [ARCHITECTURE.md](./ARCHITECTURE.md)。
## 为什么是"文件柜"？
当前的AI内存系统可以分为三种：
- **笔记本**: 用于捕捉、草拟和个人连接。
- 示例：
- Obsidian保险库是一个柏拉图式笔记本：一个markdown文件文件夹，自由链接和可移植。然而，它的优势也是其局限性。它没有结构化检索，因此要执行搜索，需要进行全文搜索。它没有引用完整性，因为您可以链接到不存在的笔记，Obsidian不会阻止您。它没有并发安全性，因此不支持两个编写者，否则会产生冲突。它可以扩展到任意数量的笔记，**适用于一个人进行自己的思考**。只要涉及多个参与者和编写，笔记本就会力不从心。
- **数据库**: 面向大规模、多用户、精确检索的工程设计。
- 这些通常是矢量存储（例如Pinecone或Milvus）和关系数据库（例如PostgreSQL）。
- 它们可以扩展到数百万个项目，支持并发写入，提供ACID保证，并生成审计日志。
- 成本是复杂的设置、操作维护、沉重的基础设施、可能误导的嵌入式存储以及部署故事不像"将这些文件放入文件夹"那么简单。
需要一个中间立场，可以在不极端的情况下满足大多数功能。
- **文件柜**：在上面添加结构层的文件夹。
- 文件柜的抽屉：文件夹、标签、分类规则等。
- 这些不是文档本身。它们是导航系统，使文档在不阅读所有文档的情况下可被找到。在保险库概念中，这意味着前端惯例、摘要调用、索引文件、反向链接规则和维护所有这些的代理循环。优势是摘要优先导航、可追溯的答案和没有矢量基础设施。
- 限制也是现实的:
- 在大约100篇文章和400,000个字的规模下，任何LLM通过摘要和索引页面的导航能力似乎是足够的，文件的复杂性和延迟可能引入的开销大于其带来的好处。但是超过这个上限，摘要导航开始产生噪音的速度比它去除的速度更快。RAG搜索和检索系统变得不那么累赘，而是需求。
## 文件柜架构
开放知识格式知识包 [https://openknowledgeformat.com/what-is-okf] 被设计为人类和代理可读的Markdown文件与YAML前置信息的捆绑包。人们可以编写它，代理可以生成它，工具可以交换它，而不需要中央注册或专有SDK。
OKF包可以扩展以提供"文件柜"的功能，为AI代理提供持久的、结构化的知识存储，位于上下文窗口之外。主要属性：
- **摘要优先导航**：每个概念都有一个摘要调用，索引提供内联摘要，以便代理在不支付全部令牌成本的情况下决定读取内容
- **双向反向链接**：概念在前置信息中跟踪出站链接和反向链接，实现图遍历
- **规模上限检测**：`inspect`命令在包超过~100个概念或~400K令牌时发出警告，提示考虑添加RAG实现
- **令牌感知检索**：工具支持令牌预算和压缩级别，以适应上下文窗口内的响应
这种架构允许AI代理通过优先阅读摘要然后根据需要深入特定概念来高效导航大型文档集。
## Canon：权威代理内存
文件柜处理**参考**知识 —— 丰富的文档，回忆比完美更重要。但是，实际指导代理的知识 —— **为什么**选择一种方法、**什么**必须成立 —— 具有不同的生命周期和更高的错误成本。memphis将这些作为 **Canon**：类型化、验证、强制执行的制品，与Reference存储在同一存储中。
- **五种类型制品** —— 需求、决策、设计、路线图、提示。类型从制品包含的`##`部分推断，而不是声明。
- **铸造身份** —— 每个Canon制品都有一个稳定的不透明ID (`<repo-key>-<12-char Crockford base32>`); 跨引用通过别名索引解析，因此像`ADR-002`这样的可读链接仍然有效。
- **类型关系** —— `## Related <Type>` / `## Supersedes` 边带有完整性检查：断开 / 模糊 / 自我引用，边合法性，目标类型范围，状态一致性（实时制品可能不指向已退休的制品，除非通过继承），和循环检测。
- **标准映射验证** —— 需求质量根据 **BCP-14 / RFC 8174** （仅大写MUST/SHALL/SHOULD具有规范权重），**ISO/IEC/IEEE 29148** （单一需求）和 **EARS** 模式进行检查。
- **生命周期 + 时效性** —— 每种类型的`## Status`（例如Proposed/Accepted/Superseded），时效性从Git历史记录中推断，而不是存储的时间戳。
- **阻塞门控** —— `memphis gate`运行验证 + 关系完整性，根据治理策略对发现结果进行分类，并发出SARIF用于CI。
没有Canon的存储库，其行为与原始的memphis完全相同 —— 采用权威层是附加的。有关完整内容，请参见 [ARCHITECTURE.md](./ARCHITECTURE.md)。
### 编写Canon
```bash
# 配置存储库（可选；否则使用默认配置）
mkdir -p .okf
cat > .okf/config.yaml <<'EOF'
repository_key: OKF
canon_roots: [canon]
ticketing:
provider: github
EOF
# 搭建一个带有新鲜铸造ID的制品
memphis new decision canon/adr-001-use-bleve.md --title "Use Bleve for search"
# 编辑章节，然后检查（以及整个语料库）
memphis gate .
# 检查类型化的关系图及其健康状况
memphis relationships . --validate --summary
# 将摄入的Reference文档提升为规范的Canon草案
memphis promote guides/caching.md --type decision
```
## 安装
### 下载二进制文件
从 [发布页面](https://github.com/chasedputnam/memphis/releases) 下载适用于您平台的最新二进制文件。
### 从源代码构建
```bash
go install github.com/chasedputnam/memphis/cmd/memphis@latest
```
或克隆并构建：
```bash
git clone https://github.com/chasedputnam/memphis.git
cd memphis
make build
```
### Apple Intelligence（可选）
在macOS 26 Tahoe with Apple Silicon上，memphis可以直接通过Apple的设备端Foundation Models进行总结。提供者通过`applefm`构建标签启用，需要一次性Swift shim编译。请参阅[docs/APPLE_INTELLIGENCE.md](docs/APPLE_INTELLIGENCE.md)了解构建工作流程。
## 快速入门
### 1. 爬取文档网站
```bash
memphis crawl https://docs.example.com --out ./my-bundle
```
### 2. 或导入本地Markdown
```bash
memphis import ./docs --out ./my-bundle
```
#### 示例：启用现有存储库
将具有散布的Markdown文件的存储库转换为可搜索的知识包：
```bash
# 导入存储库中的所有Markdown文件
memphis import ~/repo/my-project --out ~/repo/my-project/.okf --source-name "My Project"
# 过滤到特定目录或模式
memphis import ~/repo/my-project \
--out ~/repo/my-project/.okf \
--source-name "My Project" \
--include "docs/**/*.md" \
--include "**/*.mdx" \
--include "**/README.md" \
--exclude "node_modules/**" \
--exclude "vendor/**"
# 将.okf添加到.gitignore（可选）
echo ".okf/" >> ~/repo/my-project/.gitignore
# 为AI代理提供服务
memphis serve ~/repo/my-project/.okf --mcp
```
此操作会在存储库中创建一个`.okf`包，索引所有文档、README、ADR和其他Markdown内容。然后，AI代理可以搜索和导航项目的知识库。
**示例：启用monorepo**
```bash
memphis import ~/repo/cloud-platform \
--out ~/repo/cloud-platform/.okf \
--source-name "Cloud Platform" \
--include "**/docs/**/*.md" \
--include "**/README.md" \
--include "**/ARCHITECTURE.md" \
--include "**/adr/**/*.md" \
--exclude "**/test/**" \
--exclude "**/fixtures/**"
```
**保持包更新**
```bash
# 文档更改时重新导入
memphis update ~/repo/my-project/.okf --force
```
### 4. 验证您的包
```bash
memphis validate ./my-bundle
```
### 5. 通过MCP提供服务
```bash
memphis serve ./my-bundle --mcp
```
### 6. 配置您的AI客户端
添加到您的MCP客户端配置中（例如Claude Desktop）：
```json
{
"mcpServers": {
"my-docs": {
"command": "memphis",
"args": ["serve", "./my-bundle", "--mcp"]
}
}
}
```
## 命令
### `memphis crawl <url>`
爬取文档网站并创建OKF包。
```bash
memphis crawl https://docs.example.com --out ./bundle [options]
```
选项：
- `--out, -o` - 输出目录（必需）
- `--max-pages` - 要爬取的最大页面数（默认：100）
- `--max-depth` - 最大爬取深度（默认：4）
- `--include` - 包含模式（glob或正则表达式）
- `--exclude` - 排除模式
- `--same-origin` - 仅限于相同的源（默认：true）
- `--respect-robots` - 尊重robots.txt（默认：true）
- `--concurrency` - 获取并发性（默认：4）
- `--force` - 覆盖输出目录
- `--dry-run` - 列出页面而不爬取
### `memphis import <path>`
将本地文件导入OKF包。
```bash
memphis import ./docs --out ./bundle [options]
```
选项：
- `--out` - 输出目录（必需）
- `--source-name` - 包标题
- `--include` - 包含模式
- `--exclude` - 排除模式
- `--force` - 覆盖输出目录
- `--summarize` - 摘要模式：`extractive`（默认）或`llm`
- `--summarize-algorithm` - 提取算法：`lsa`（默认）、`lexrank`、`textrank`、`luhn`、`edmundson`、`sumbasic`、`kl`、`reduction`、`random`
- `--language` - 分割器语言：`english`（默认）、`french`、`spanish`、`russian`、`swedish`、`norwegian`、`hungarian`
- `--edmundson-config` - `edmundson.config` YAML的路径（仅当 `--summarize-algorithm=edmundson` 时使用）
请参阅 [Summarization](#summarization) 以了解每个模式和算法的作用，以及如何配置LLM提供者。
### `memphis validate <bundle>`
验证OKF包的结构和健康状况。
```bash
memphis validate ./bundle [--json]
```
验证：
- 索引结构和前置信息
- 概念前置信息（必需的`type`字段）
- 内部链接完整性（断开的链接）
- **文件柜健康状况**：缺少摘要调用、摘要长度、规模上限
缺少摘要会产生警告（不是错误）以与较旧的包向后兼容。
### `memphis inspect <bundle>`
显示包统计数据和规模指标。
```bash
memphis inspect ./bundle
memphis inspect ./bundle --recommendations
```
输出包括：
- 概念计数、链接计数、断开的链接、孤立的概念
- 类型和标签分布
- **规模指标**：总令牌数、每个概念的平均令牌数、索引比率
- **规模状态**：健康、警告（接近上限）或超出
### `memphis serve <bundle>`
启动MCP服务器用于包。
```bash
memphis serve ./bundle --mcp
```
选项：
- `--mcp` - 使用MCP stdio传输（默认：true）
- `--name` - 服务器名称
- `--max-result-chars` - 工具结果中的最大字符数（默认：12000）
### `memphis update <bundle>`
从其原始源更新现有的OKF包。
```bash
memphis update ./bundle [options]
```
源自动从包的`changelog.txt`文件（在爬取或导入时创建）读取。您可以覆盖它与 `--source` 标志。
选项：
- `--source, -s` - 覆盖源URL或路径
- `--force` - 应用所有更改而不提示
- `--dry-run` - 显示更改而不应用它们
- `--max-pages` - 要爬取的最大页面数，用于URL来源（默认：100）
- `--max-depth` - URL来源的最大爬取深度（默认：4）
- `--concurrency` - 获取并发性，用于URL来源（默认：4）
- `--include` - 包含模式
- `--exclude` - 排除模式
- `--summarize` - 覆盖存储在更改日志中的摘要模式
- `--summarize-algorithm` - 覆盖存储在更改日志中的提取算法
- `--language` - 覆盖存储在更改日志中的语言
- `--edmundson-config` - `edmundson.config` YAML的路径
当省略时，摘要标志默认为无论何时在包的更改日志中记录的内容。覆盖项仅适用于一次运行并且不会持久更改日志头。
示例工作流程：
```bash
# 初始爬取
memphis crawl https://docs.example.com --out ./my-bundle
# 后来，更新更改
memphis update ./my-bundle --dry-run # 预览更改
memphis update ./my-bundle --force # 应用所有更改
memphis update ./my-bundle # 交互式模式
```
### `memphis demo`
运行带有内置示例的离线demo。
### 取消授权
这些命令在**权威**层（存储库根目录下的`canon_roots`配置的制品）上运行。纯Reference存储库中为无操作。
#### `memphis new <type> <path>`
在指定路径下构建一个类型化的Canon制品（`requirement`、`decision`、`design`、`roadmap`、`prompt`），并赋予一个新鲜的、不透明的ID，以及该类型所需的推荐章节。
```bash
memphis new decision canon/adr-001-use-bleve.md --title "Use Bleve for search"
memphis new requirement canon/req-search.md --store .
```
#### `memphis gate [store]`
运行统一权限网关：验证每个佳作，检查关系完整性，并根据商店的 `enforcement` 策略将发现结果分类为阻塞或建议。如果存在任何阻塞性发现，则退出时返回非零值。
```bash
memphis gate . # 人类输出
memphis gate . --json # 机器可读结果
memphis gate . --sarif # SARIF 2.1.0 用于 CI 必需检查
```
#### `memphis relationships [store]`
报告和验证类型化关系图。
```bash
memphis relationships . # 列出边
memphis relationships . --validate # + 完整性问题（失败时报错）
memphis relationships . --summary # + 覆盖率 / 孤立 / 破损计数
memphis relationships . --validate --json
```
#### `memphis promote <concept> --type <type>`
将摄入的 Reference 概念提升为类型化的佳作草稿 — 生成 ID，搭建类型的章节，并将概念的内容植入主要文本部分。然后验证草稿，确保它永远不会被悄悄地视为权威。
```bash
memphis promote guides/caching.md --type decision
```
#### `memphis rebuild [store]`
从真实的 Markdown 源重新生成所有派生索引（全文搜索，关系图）。派生索引是缓存 — 删除并重新生成它们永远不会影响规范文件。
```bash
memphis rebuild .
```
#### `memphis export [store]`
导出 **Reference** 层以便升级到外部 RAG 或图后端，当它超出存储库文件柜的容量时。佳作保留在存储库中作为真实来源，永远不会以文档形式导出。
```bash
memphis export . --documents # Reference 概念为 JSONL（适用于 RAG）
memphis export . --graph # 关系图为 JSON
memphis export . --documents --out refs.jsonl
```
## MCP 工具
在通过 MCP 提供捆绑包时，以下工具可供 AI 代理使用。服务器是 **只读** 的 — 所有突变操作都通过 CLI 和 Git PR 审查进行。
### 佳作（权威）工具
| 工具 | 描述 |
|------|-------------|
| `get_artifact` | 按 ID 读取一个权威的佳作，包含其类型、状态、关系和引用 |
| `find_decisions` | 查找与某个主题相关的佳作决策 |
| `get_related` | 某个工件的分类关系：输出引用、输入引用和有界多跳邻居 |
| `get_summary` | 总结佳作语料库：按类型和生命周期状态计数 |
### 搜索和阅读工具
| 工具 | 描述 |
|------|-------------|
| `search_concepts` | 跨两个层级的全文搜索，带有 token 预算控制 |
| `read_concept` | 读取特定概念的内容，支持压缩选项 |
| `get_neighbors` | 通过出站链接和反向链接查找相关概念 |
| `get_context` | 在 token 预算内进行权威感知上下文组装（发现 → 落地 → 组装）；佳作优先并附带引用，引用项标记为 `derived` |
| `list_types` | 列出捆绑包中的所有概念类型 |
| `list_tags` | 列出捆绑包中的所有标签 |
| `bundle_summary` | 获取捆绑包统计数据、规模指标和索引内容 |
### 实时更新工具
| 工具 | 描述 |
|------|-------------|
| `check_updates` | 检查捆绑包源是否有可用更新 |
| `apply_updates` | 应用源的待处理更新（重新生成摘要和反向链接） |
| `bundle_health` | 检查捆绑包健康状况、规模上限、缺失摘要和源可达性 |
### 实用工具
| 工具 | 描述 |
|------|-------------|
| `compression_stats` | 查看此会话的 token 压缩统计信息 |
### Token 预算和压缩
搜索和读取工具支持 token 感知的响应，以帮助 AI 代理高效管理上下文窗口：
**参数：**
- `token_budget` - 响应的最大 token 数（使用 cl100k_base 编码进行估计）
- `compression` - 压缩级别：`none`、`light`、`medium`、`aggressive`
- `detail_level` - 详细级别 0-3（0=最小，3=完整内容）
**压缩级别：**
| 级别 | 效果 |
|-------|--------|
| `none` | 无压缩，完整内容 |
| `light` | 规范化空格，折叠空白行 |
| `medium` | 轻度 + 截断到章节边界并提供大纲 |
| `aggressive` | 中度 + 激进截断并提供检索提示 |
**示例：预算感知搜索**
```json
{
"tool": "search_concepts",
"arguments": {
"query": "authentication",
"token_budget": 2000,
"compression": "medium",
"detail_level": 2
}
}
```
**示例：获取某个主题的上下文**
```json
{
"tool": "get_context",
"arguments": {
"query": "how to authenticate users",
"token_budget": 4000,
"compression": "light"
}
}
```
### 实时更新
当 MCP 服务器运行时，可以从原始源更新捆绑包：
**检查更新**
```json
{
"tool": "check_updates",
"arguments": {
"timeout_seconds": 30
}
}
```
响应包括 `has_changes`、`added`、`modified`、`deleted` 计数。
**应用更新**
```json
{
"tool": "apply_updates",
"arguments": {
"confirm": true
}
}
```
使用 `dry_run: true` 预览更改而不应用它们。
## 开放知识格式
OKF 捆绑包是包含带有 YAML 前置信息的 Markdown 文件的目录。该格式实现了文件柜模式，带有摘要调用和双向反向链接。
### 概念格式
```markdown
---
type: Guide
title: 入门指南
description: 学习如何快速入门该产品。
tags:
- quickstart
- tutorial
resource: https://docs.example.com/getting-started
backlinks:
- concepts/authentication
- concepts/installation
---
# 入门指南
> [!summary]
> 学习如何在 5 分钟内安装和配置该产品。
您的内容在这里...
```
### 必需字段
- `type` - 概念类型（Guide、API Reference、Concept 等）
### 可选字段
- `title` - 文档标题
- `description` - 简要描述（最多 180 个字符）
- `tags` - 主题标签数组
- `resource` - 原始来源 URL
- `timestamp` - 最后修改日期
- `backlinks` - 链接到此概念的概念数组（自动生成）
### 索引格式
根目录 `index.md` 提供摘要优先导航：
```markdown
---
okf_version: "0.1"
total_concepts: 47
total_tokens: 125000
generated: 2024-01-15T10:30:00Z
---
# 我的文档捆绑包
## 概念（47）
- [[getting-started]] · Guide, quickstart, tutorial
学习如何在 5 分钟内安装和配置该产品。
- [[authentication]] · Guide, security, oauth
配置支持多个提供者的 OAuth2 身份验证。
```
### 摘要调用
每个概念都应在其标题后有一个摘要调用：
```markdown
> [!summary]
> 一个 1-2 句子的摘要（最多 200 个字符），用于导航。
```
摘要在 `crawl` 和 `import` 期间由配置的摘要器自动生成（参见 [Summarization](#summarization)）。默认情况下使用文档主体上的提取式 LSA；LLM 模式和其他提取式算法可通过标志在 `import` 时选择。
## Summarization
每个捆绑包中的概念都获取一个 `> [!summary]` 调用。摘要使得索引可内联阅读，并且是大多数文件柜令牌效率的主要驱动力。memphis 支持两种摘要模式，按 `--summarize` 在 `import` 上选择：
| 模式 | 来源 | 何时使用 |
|------|--------|-------------|
| `extractive`（默认） | 嵌入式 Go 端口 [sumy](https://github.com/miso-belica/sumy) — 无网络，完全确定性 | 默认适用于大多数捆绑包；快速，在线，可重复 |
| `llm` | 外部 API，Apple Intelligence 或本地 Ollama（参见下面的提供商堆栈） | 当您想要生成式单句摘要，能够更好地处理链接密集或嘈杂的文档 |
### 提取算法
使用 `import` 上的 `--summarize-algorithm` 进行选择。默认为 `lsa`。
| 算法 | 功能 |
|-----------|--------------|
| `lsa`（默认） | 潜在语义分析；术语-句子矩阵上的奇异值分解。适用于一般目的。 |
| `lexrank` | IDF 修改的余弦句子图上的 PageRank。适用于技术散文。 |
| `textrank` | 共享词句子图上的 PageRank。比 LexRank 更便宜，质量相似。 |
| `luhn` | 重要词簇。适用于提示丰富的文档（标题，定义）。 |
| `edmundson` | 提示 + 关键 + 标题 + 位置启发式。可通过 `edmundson.config` 调整。 |
| `sumbasic` | 贪婪词概率，并带有冗余权重降低。 |
| `kl` | 文档分布之间的 KL-散度最小化。 |
| `reduction` | 成对共享词计数的总和。廉价基线。 |
| `random` | 时间种子随机句子选取。有用作控制。 |
### 语言
`--language` 配置提取管道的词干提取。支持：`english`（默认），`french`，`spanish`，`russian`，`swedish`，`norwegian`，`hungarian`。停用词过滤目前仅限英语；非英语捆绑包仍然进行词令牌化，词干提取和评分，但失去停用词过滤。
### LLM 模式
当传递 `--summarize=llm` 时，memphis 会遍历提供商堆栈并使用第一个可用的堆栈：
1. **外部 OpenAI 兼容 API** — 在 `llm.config` 中设置 `api_endpoint` 和 `api_token` 时使用。遵守 429 状态码的 `Retry-After` 并重试 5xx 状态码，指数退化。
2. **平台原生设备 LLM** — Apple Intelligence 在 macOS 26 Tahoe + Apple Silicon（需要 `applefm` 构建标签，参见 [docs/APPLE_INTELLIGENCE.md](docs/APPLE_INTELLIGENCE.md)）；Windows Copilot Runtime 存根。
3. **本地 Ollama** — 默认 `http://localhost:11434`，模型 `phi3:mini`。
4. **提取式回退** — 如果上述任何一个不可达，引擎回退到提取式摘要，以便导入永远不会因为 LLM 离线而失败。
配置位于 `llm.config`（YAML）中，按以下顺序搜索：`<bundle>/llm.config`，然后 `~/.config/memphis/llm.config`。
```yml
# 使用外部 OpenAI 兼容端点
api_endpoint: https://api.openai.com/v1/chat/completions
api_token: sk-...
model: gpt-4o-mini
# 或将本地回退指向自定义 Ollama
local_endpoint: http://localhost:11434
local_model: phi3:mini
# 可选：覆盖提示
prompt_template: |
将以下文档总结为一个简洁的句子（最多 200 个字符）。
标题：{{.Title}}
内容：
{{.Content}}
```
在发送到 LLM 之前，文档内容会被智能截断到约 8000 个令牌预算；优先保留标题和段落以减少噪音，如果仅保留标题的减少量仍然超过限制，则使用硬令牌级别的回退。
### Apple Intelligence（macOS 26 Tahoe）
在运行 macOS 26 Tahoe 的 Apple Silicon Mac 上，memphis 可以通过进程内 CGo 桥直接调用 Foundation Models — 无需 HTTP 服务器，无需 API 密钥，无令牌离开设备。这是需要 `applefm` 构建标签的可选功能，因此默认构建在 Intel Mac、较旧的 macOS、Linux 和 Windows 上继续工作。有关构建工作流程，请参见 [docs/APPLE_INTELLIGENCE.md](docs/APPLE_INTELLIGENCE.md)。
当桥接构建并可用时，`llm` 模式会自动优选 Apple Intelligence 而不是 Ollama 回退（如果配置了外部 `api_endpoint`，仍然优先 — 方便在云模型之间进行 A/B 比较）。
## 规模上限和 RAG 晋级
文件柜模式适用于最多约 100 个概念或 400K 个令牌的文档集。超出此范围，查询成本呈非线性增长，因为摘要导航会产生太多候选结果。
**检查您的捆绑包规模：**
```bash
memphis inspect ./my-bundle
```
**当超出上限时：**
```bash
memphis inspect ./my-bundle --recommendations
```
此输出提供有关添加向量搜索（RAG）以外的 wiki 结构的指导：
- 使用基于标头的分块（不是基于令牌计数的分块）
- 推荐的本地向量存储：带有 vss 扩展的 DuckDB，ChromaDB
- 保留 wiki 结构以解决综合问题；使用向量进行精确查找
## 开发
```bash
# 运行测试
make test
# 运行 linter
make lint
# 为所有平台构建
make build-all
# 运行演示
make demo
```
## 端到端管道
`internal/summarize/summarizer.go` 根据 `--summarize` 调度到两个管道之一：
```
原始字节（markdown / HTML / text）
│
▼
nlp.Parser.Parse(text) ─── stripMarkdownArtifacts → splitParagraphs → tokenize → Document
│ （frontmatter，代码块，调用，链接，加粗/斜体等）
▼
┌────────────── mode = extractive（默认） ──────────────┐
│ │
▼ │
sumer.NewSummarizer(algo, lang) → Summarizer │
│ │
▼ │
summarizer.Summarize(doc, sentenceCount=1) → []*nlp.Sentence │
│ ↑ │
│ └─ 算法特定评分（LSA，LexRank，...） │
▼ │
Base.GetBestSentences ── 稳定排序按评级降序，然后重新排序 │
│ 选择的文件夹顺序 │
▼ │
ExtractiveAdapter 截断到 MaxSummaryLength，返回 Summary{Text} │
│ │
│ ┌─────────────── mode = llm ──────────────┐ │
│ ▼ │ │
│ llm.Engine.Summarize(content, title) │ │
│ │ │ │
│ ▼ │ │
│ intelligentTruncate 到 ~8000 个令牌 │ │
│ （优先保留标题和段落） │ │
│ │ │ │
│ ▼ │ │
│ selectProvider → api → apple → ollama │ │
│ │ （Apple Foundation Models │ │
│ │ 在 macOS 26 + applefm 标签） │ │
│ ▼ │ │
│ provider.Generate(ctx, prompt) │ │
│ │ │ │
│ ▼ │ │
│ 如果错误 → 回退到提取式 ──────────────────┘ │
│ │
└────────────────────────────────┬──────────────────────────────────┘
▼
writer.injectSummaryCallout 将
`> [!summary]` 块写入渲染的 .md 文件
```
提取路径始终请求 **一个** 句子，因为 OKF 摘要调用是单行。LLM 路径包装了一个单句提示模板；如果配置的提供商不可用或失败，引擎静默回退到提取式，以便导入永远不会因为 LLM 离线而失败。
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器