内容
# 知道
本地优先的知识操作系统，适用于 AI 代理。
知道提供给 AI 编码代理一个持久的项目记忆，而不默认将该记忆发送到托管服务。它在 `.knowl/` 下的每个项目中存储结构化的知识原子， 通过 CLI 公开该记忆，并提供一个 MCP 服务器，以便 Codex、Cursor 或 Claude Desktop 等工具可以在工作时检索和更新项目上下文。
知道的设计适用于持久的工程上下文：决策、架构、目标、约束、事实、当前状态和可重用的技能。它不用于存档原始聊天记录。
## 功能
- 在 `.knowl/knowl.db` 中本地存储项目记忆。
- 将记忆组织成 `fact`、`decision`、`goal`、`constraint`、`architecture`、`state` 和 `skill` 类别。
- 提供确定性的 MCP 工具，用于存储和查询结构化的知识，而无需知道侧的 AI 提供商。
- 生成或刷新 `AGENTS.md` 指南，以便代理知道在检查文件之前查询知道。
- 记录工作循环的开始、检查点和完成情况，作为带有知识提交的结构化状态原子。
- 用自动工作循环包装 shell 命令，以便代理在执行前查询记忆，并在执行后写入成功或失败状态。
- 在 `.knowl/skills/<name>/` 下存储学习的执行技能包，带有 `SKILL.md`、`skill.json` 和可选脚本。
- 公开稳定的 MCP 和 CLI 技能桥，以便新的学习技能无需为每个技能添加新工具即可使用。
- 检测支持的代理并从 `knowl init` 安装 MCP 注册。
- 在项目初始化期间将 `.knowl/` 添加到 `.gitignore`。
- 支持用于原始文本摄入和自然语言答案的可选 AI 支持的 CLI 命令。
- 支持 BM25 加默认开启的本地向量搜索，带有延迟首次使用模型下载。
- 跟踪记忆更改为知识提交，以便项目记忆具有历史记录。
- 使用 Tree-sitter 在本地索引 TypeScript/JavaScript 符号，并可以将持久证据附加到 `symbol://` 定位器。
- 支持时间断言、独家冲突标识、有限上下文包、分层记忆命名空间和验证的 JSONL 可移植性。
- 通过 `knowl view` 包含一个只读的 localhost 查看器。
## 安装
安装已发布的 CLI：
```bash
npm install -g @dat999zx/knowl
knowl --version
```
从源代码构建和链接：
```bash
git clone <repo-url>
cd knowl
npm install
npm run build
npm link
```
## 快速入门
从项目根目录初始化一个项目：
```bash
knowl init
```
这会创建 `.knowl/config.json`，启动 `.knowl/knowl.db`，将知道的指南安装到 `AGENTS.md`，确保 `.knowl/` 被 git 忽略，并为检测到的代理提供项目本地的 MCP 和生命周期钩子设置。
记录一个决定：
```bash
knowl decide "使用 SQLite" "使用 SQLite 进行本地项目记忆。" \
--reasoning "它保持知道的本地优先和简单安装。" \
--alternatives PostgreSQL MongoDB \
--tags database local-first
```
检查项目记忆：
```bash
knowl status
knowl state
knowl doctor
```
交互式选择检测到的代理，或显式配置它们：
```bash
knowl init
knowl init codex claude cursor
knowl doctor
```
项目本地的 MCP 和钩子配置是首选的。在设置完成后启动一个新的代理会话，并信任主机在运行项目钩子之前询问。
用自动知道工作循环包装工作：
```bash
knowl task run "实现搜索 UI" --query "搜索检索" -- npm test
```
或记录手动检查点：
```bash
knowl task start "实现搜索 UI" --query "搜索检索"
knowl task checkpoint <task-id> "添加搜索 UI 测试"
knowl task finish <task-id> "验证搜索 UI 实现"
```
会话事件是临时的scratch记忆，而不是转录存档。它们仅保留有限的命令/测试/错误/git/决策元数据，过期时间为 48 小时，过期的活跃会话可以安全恢复：
```bash
knowl session start "实现搜索 UI" --query "搜索检索"
knowl session event <session-id> test --summary "存储测试通过"
knowl session finish <session-id> --status finished --summary "实现验证"
knowl session recover
```
当终端会话正常结束时，知道会确定性地提升最多五个候选：决策、验证命令、结果和任务状态。每个提升的候选都需要会话或文件证据。可选的合成永远不需要提升；确定性候选仍然是回退。
### 代理生命周期自动化
`knowl init` 为 Codex CLI、Claude Code 和 Cursor 安装了验证的项目本地钩子。生命周期钩子调用短寿命的 `knowl agent-hook <host> <event>` 进程，这些进程将供应商有效载荷规范化为有限的会话事件。MCP 工具使用一个单独的主机生成的 `knowl serve` 进程；钩子永远不会启动或管理服务。
SessionStart 是唯一的自动面向模型的上下文注入。用于工具、失败、压缩和停止的捕获钩子保持静默/仅捕获。成功的命令、文件更改、测试、失败、压缩检查点和回合完成都会馈送现有的验证/证据/提升管道。
当支持的主机以硬停止失败结束（Claude `StopFailure`、Codex/Cursor 停止/会话结束失败，或通用停止失败），知道会存储一个主机范围的确定性 `pending_handoff` 状态项（无需 AI）。下一个匹配的主机 `SessionStart` 会将该交接注入，然后是正常的最近上下文，并将其存档，以便交付是一次性的。普通的成功停止和工具失败不会创建交接。
多个剩余的 `knowl serve` 进程通常意味着多个主机会话或重新连接，而不是钩子重新生成。多个代理可以使用一个存储库，共享 SQLite 数据库和简短的锁定等待；不同存储库中的代理在每个项目 `.knowl/` 下保持隔离。
原始提示、转录、stdout/stderr、环境变量和未知字段不会被保留。格式错误或包含机密的有效载荷会被拒绝，重复的停止事件会被幂等丢弃，一个通用的 stdin-JSON 契约可用于其他主机，但普通用户只需运行 `knowl init` 和 `knowl doctor`。
钩子支持仍然特定于主机。知道永远不会猜测或写入未经验证的主机配置。不受支持的主机保留 MCP 访问；`knowl task run` 仍然是手动回退。
创建并运行一个学习的技能包：
```bash
knowl skill create run_app \
--purpose "在本地启动应用程序" \
--markdown "# 运行应用程序\n\n使用此命令启动应用程序。" \
--file "run.ps1=Write-Output 'run-app'" \
--script run.ps1
knowl skill list
knowl skill read run_app
knowl skill run run_app
```
## MCP 工作流
MCP 是代理使用知道的首选方式。MCP 工具不需要知道侧的 AI 配置来进行正常的结构化记忆工作流。客户端模型应该提取持久的知识并调用知道的结构化工具。
推荐的代理流程：
1. 生命周期钩子在会话开始时传递紧凑的上下文。仅当钩子不可用或需要刷新时才调用 `knowl_recent`。
2. 使用 `knowl_query` 进行特定问题，带有 2-6 个简洁的关键词。
3. 仅使用 `knowl_state` 进行广泛的完整状态摘要。
4. 对于多步骤任务，在每个新子任务或切换区域之前再次查询知道。
5. 使用 `knowl_store`、`knowl_decide` 或 `knowl_ingest_atoms` 在每个完成的 subtask 或验证的发现后立即存储持久的新事实、决策、约束、架构注释、状态和技能。
6. 尽快使用 `knowl_update`，因为您发现过时或矛盾的记忆。
例行生命周期事件仍然是短暂的。MCP 响应默认情况下是紧凑和有界的；显式细节选项请求更大的检查负载。
可用 MCP 工具：
| 工具 | 用途 |
| --- | --- |
| `knowl_recent` | 返回最近的活跃知识和最近的知识提交，用于会话启动。 |
| `knowl_query` | 搜索活跃或历史项目记忆。默认为活跃项目，返回最多三个命中。 |
| `knowl_state` | 返回完整的活跃项目记忆为 markdown。 |
| `knowl_store` | 存储一个结构化的知识原子，无需 AI 配置。 |
| `knowl_ingest_atoms` | 存储一批结构化的知识原子，无需 AI 配置。 |
| `knowl_decide` | 记录一个带有必需推理的决定。 |
| `knowl_update` | 更新项目内容、标题、推理或状态。 |
| `knowl_task_start` | 启动一个手动工作循环，查询相关记忆，并存储活跃的任务状态。 |
| `knowl_task_checkpoint` | 存储一个活跃工作循环的持久进度。 |
| `knowl_task_finish` | 存储一个工作循环的持久完成状态。 |
| `knowl_skill_list` | 列出 `.knowl/skills` 下的学习文件支持的技能包。 |
| `knowl_skill_read` | 读取一个学习技能包（`skill.json` 和 `SKILL.md`）。 |
| `knowl_skill_create` | 创建一个学习技能包，并将其索引为一个 `skill` 知识项。 |
| `knowl_skill_run` | 自动运行一个学习技能入口点，优先使用存储库本地脚本，可选 shell 回退。 |
| `knowl_ingest` | 运行原始文本通过知道的 AI 支持的提取管道。需要显式 AI 配置。 |
| `knowl_gc_preview` | 预览重复、过时或冷记忆清理建议。 |
| `knowl_gc_apply` | 以事务方式应用垃圾收集并记录知识提交。 |
可读的 MCP 资源：
| 资源 | 用途 |
| --- | --- |
| `knowl://recent` | 紧凑的最近会话上下文。 |
| `knowl://brain` | 完整的活跃项目大脑状态。 |
| `knowl://category/<name>` | 活跃的项目类别项，例如 `decision`、`architecture` 或 `state`。此 URI 形式可读，即使只有 `knowl://recent` 和 `knowl://brain` 在资源发现期间列出。 |
## 代理设置
`knowl init` 检测 Codex、Claude Code、Cursor 和 Claude Desktop，然后呈现一个多选 UI。可以在任何时候重新运行它以添加另一个代理或修复一个过时的知道注册。它保留无关的 MCP 服务器，在更改现有代理配置之前备份，并在不重复正确条目的情况下不复制它们。
如果 MCP 客户端为此本地 stdio 服务器显示 `Auth: Unsupported`，则这是预期的，不意味着知道不可用。
## CLI 命令
| 命令 | 描述 |
| --- | --- |
| `knowl init [agents...]` | 初始化或升级此项目，然后交互式地选择检测到的代理。传递 `codex`、`claude`、`cursor` 或 `claude-desktop` 以显式配置。 |
| `knowl upgrade` | 升级现有的知道存储库以适应当前默认值和代理文件。 |
| `knowl status` | 显示存储库路径、项目计数、类别计数、AI 配置状态和最近的知识提交。 |
| `knowl doctor` | 检查项目是否准备好用于代理内存使用。 |
| `knowl audit` | 只读验证、引用、JSON、状态和 FTS 完整性审计。 |
| `knowl snapshot create` | 创建一个带 SHA-256 清单的带时间戳的 SQLite 快照。 |
| `knowl snapshot restore <path> --confirm` | 以事务方式还原快照；首先创建预恢复快照。 |
| `knowl evidence list <item-id>` | 列出链接的文件、提交、测试、命令、URL、用户、代理或符号证据。 |
| `knowl state` | 打印完整的活跃分层项目记忆。 |
| `knowl task start <title>` | 启动一个工作循环，查询相关记忆，并存储活跃的任务状态。 |
| `knowl task checkpoint <task-id> <summary>` | 存储一个活跃工作循环的持久进度。 |
| `knowl task finish <task-id> <summary>` | 存储一个工作循环的持久完成状态。 |
| `knowl task run <title> -- <command...>` | 启动一个工作循环，运行一个命令，然后在子退出代码成功或检查失败时完成。 |
| `knowl timeline <item-id>` | 打印一个知识项的不可变内容断言。 |
| `knowl query <query> --as-of <timestamp>` | 在 ISO-8601 时间查询历史有效内容。 |
| `knowl conflicts` | 列出活跃的独家冲突标识。 |
| `knowl supersede <item-id> <replacement-id>` | 标记一个项目由显式替换。 |
| `knowl context --token-budget <n>` | 编写一个带有固定约束和排除的紧凑任务上下文包。 |
| `knowl code index` | 增量索引 TypeScript/JavaScript 符号和导入/导出边。 |
| `knowl code symbols <path>` | 打印一个存储库相对文件索引的符号。 |
| `knowl synthesize --scope <tag>` | 创建或刷新确定性证据支持的架构理解。 |
| `knowl export <path>` | 编写一个版本化、清单验证的 JSONL 内存导出。 |
| `knowl import <path> [--dry-run]` | 验证和导入 JSONL 内存，而不自动解决冲突。 |
| `knowl view` | 在 `127.0.0.1` 上启动只读本地查看器。 |
| `knowl agent-event <event>` | 接收有限的主机生命周期事件；接受结构化标志或 stdin 上的 JSON。 |
| `knowl agent-hook <host> <event>` | 内部主机钩子翻译器，用于项目本地自动捕获。 |
| `knowl session start|event|finish|recover` | 管理有限、过期的 scratch 会话事件和恢复过时的会话。 |
| `knowl skill list` | 列出 `.knowl/skills` 下的学习文件支持的技能包。 |
| `knowl skill read <name>` | 打印一个学习技能包的 `skill.json` 和 `SKILL.md`。 |
| `knowl skill create <name> --purpose ...` | 创建一个学习技能包，并将其索引为一个 `skill` 知识项。 |
| `knowl skill run <name>` | 运行一个学习技能入口点并更新索引技能项的使用元数据。 |
| `knowl decide [title] [content]` | 记录一个决定。当标题或内容省略时交互式运行。 |
| `knowl ask <question>` | 在项目内存上提出一个自然语言问题。需要 AI 配置。 |
| `knowl ingest <text>` | 从原始文本中提取和合并知识。需要 AI 配置。 |
| `knowl config` | 打开交互式分类配置 UI。 |
| `knowl config get <key>` | 打印一个验证的配置值。 |
| `knowl config set <key> <value>` | 设置一个验证的配置值。 |
| `knowl config reset [key]` | 重置一个设置，或在确认后重置所有设置。 |
| `knowl reindex --vectors` | 重新构建本地向量嵌入。 |
| `knowl gc` | 预览内存垃圾收集建议。 |
| `knowl gc --apply` | 应用内存垃圾收集建议。 |
| `knowl serve` | 启动_stdio MCP 服务器。 |
有用的命令示例：
```bash
knowl config
knowl config set ai.provider openai
knowl config set ai.model gpt-4o-mini
knowl config set ai.apiKey '${OPENAI_API_KEY}'
knowl config set search.vector.enabled false
knowl reindex --vectors
knowl init codex
knowl task start "Fix auction settlement bug" --query "auction settlement wallet"
knowl task run "Run tests" --query "test verification" -- npm test
knowl gc
knowl gc --apply
knowl audit
knowl snapshot create
knowl snapshot restore .knowl/snapshots/<snapshot>.db --confirm
``` ## 可选 AI 配置
知道不需要 AI 配置来支持诸如 `knowl_store`、`knowl_ingest_atoms`、`knowl_decide`、`knowl_query`、`knowl_recent` 或 `knowl_state` 等 MCP 结构化工具。
仅当您想要：
- `knowl ask`
- `knowl ingest`
- MCP `knowl_ingest`
- CLI 中的 AI 辅助决策冲突处理
支持的提供商是 `openai`、`anthropic`、`ollama` 和 `custom`。
OpenAI 示例：
```bash
knowl config set ai.provider openai
knowl config set ai.model gpt-4o-mini
knowl config set ai.apiKey '${OPENAI_API_KEY}'
```
Anthropic 示例：
```bash
knowl config set ai.provider anthropic
knowl config set ai.model claude-3-5-sonnet-latest
knowl config set ai.apiKey '${ANTHROPIC_API_KEY}'
```
Ollama 示例：
```bash
knowl config set ai.provider ollama
knowl config set ai.model llama3.1
```
自定义示例：
```bash
knowl config set ai.provider custom
knowl config set ai.model my-model
knowl config set ai.baseUrl http://localhost:8080/v1
knowl config set ai.apiKey my-key
```
环境变量占位符（例如 `${OPENAI_API_KEY}`）在运行时被解析。
## 本地数据
知道在 `.knowl/` 下存储项目数据：
- `.knowl/config.json` 包含安全、AI 和搜索配置。
- `.knowl/knowl.db` 包含项目内存、知识提交、搜索索引和可选嵌入。项目范围由数据库位置隐含，因此 Knowl 不会将单独的项目名称或根路径元数据保存在数据库中。
- `.knowl/skills/` 包含带有 `SKILL.md`、`skill.json` 和可选脚本的文件支持的学习技能包。
`skill.json` 定义路径安全学习技能元数据和入口点。`default` 入口点通常指向存储库本地脚本，例如 `run.ps1`、`run.sh` 或 `run.cmd`。当技能需要直接 shell 调用时，允许使用 `fallback` shell 命令。
默认情况下，`knowl init` 和 `knowl upgrade` 确保 `.knowl/` 被 git 忽略。
## 开发
安装依赖：
```bash
npm install
```
运行测试：
```bash
npm test
```
构建 CLI：
```bash
npm run build
```
验证 npm 包内容：
```bash
npm pack --dry-run
```
在 Windows 上，如果默认 npm 缓存有权限问题，请使用工作区本地缓存：
```bash
npm pack --dry-run --cache .tmp\npm-cache
```
## 软件包
npm 软件包以 `@dat999zx/knowl` 发布。安装的二进制文件仍命名为 `knowl`。
软件包有效载荷仅限于：
- `dist`
- `README.md`
- `LICENSE`
`prepublishOnly` 在发布前运行 `npm run build`。
## 许可
Knowl 遵循 Apache License zn.0。有关完整条款，请参见 [LICENSE](LICENSE)。
连接信息
猜你喜欢
暂无推荐服务器