llm-kosh

---

为什么要做这个

AI Agent 能在越来越长的工作流中进行推理，但它们的记忆往往要么是临时的，要么被交给不透明的托管服务。

**LLM-Kosh 将记忆视为本地基础设施：**可检查、可移植、可审计、受权限控制，并可供兼容 MCP 的客户端使用。

它为 Agent 提供持久记忆层，由普通本地文件、结构化索引和治理控制机制构成：

• 本地优先 — 默认情况下，你的记忆仓库保留在本机。
• 可检查 — 记忆始终可读、可备份、可比较差异并可审阅。
• 可审计 — 所有变更都会记录在防篡改账本中。
• 权限控制 — MCP 默认以只读方式启动；写入、修改和私密导出都需要明确选择启用。
• 可移植 — 一个记忆仓库即可支持多个兼容的 AI 客户端和工作流。
• 感知证据 — Kosh Verify 能区分支持、矛盾、推断、证据缺口和缺失。

安装： python -m pip install --upgrade llm-kosh

Kosh Verify：能够展示推理依据的记忆

长期记忆会带来一种不同于一次性错误回答的失效模式：薄弱或被误解的记忆可能在后续会话中再次被回忆起来。

Kosh Verify 是 LLM-Kosh 的证据感知验证界面。给定卡匣中已有的证据，它可以生成结构化报告，其中包含时间背景、支持性事实、因果路径、矛盾、推断得出但尚未发现的关系、缺失的证据、稳定性信息，以及证据不足时的明确弃答状态。

它不是通用的真相判定器，也不会仅仅因为导入的来源被存储起来，就让其变得可信。其目标是保留以下区别：卡匣观察到的内容、推断出的内容、存在冲突的内容，以及缺乏证据支持的内容。

试用确定性的合成事件演示：

llm-kosh --root ./kosh-demo kosh-verify \
  "Why did checkout fail and what evidence contradicts the explanation?" \
  --when "2026-05-01T13:30:00+00:00" \
  --depth 5 \
  --demo-seed \
  --json

--demo-seed 会将合成事件证据写入所选根目录，因此请使用临时目录。自动化测试和离线验收框架也涵盖了相同的行为：

python scripts/kosh_verify_acceptance.py

请参阅 Kosh Verify，了解契约、边界、API 示例、MCP 接口和可复现检查。

LLM-Kosh 的不同之处

能力	LLM-Kosh
本地优先的持久记忆	✅
原生 MCP 访问	✅
可供人工检查的存储	✅
防篡改变更日志	✅
默认只读的 Agent 访问	✅
有证据支持的上下文包	✅
时间／因果验证	✅
矛盾与证据缺口报告	✅
明确的无证据弃答	✅
需要托管记忆服务	❌
需要自动云同步	❌

架构

flowchart TB
    A[AI client / agent] -->|MCP| R[Access layer]
    M[CLI] --> R
    N[Background service] --> R
    O[Local HTTP MCP - optional] --> R

    subgraph KOSH[LLM-Kosh]
      R
      C[Memory]
      D[Evidence]
      E[Search]
      F[Policy]
      G[Ledger]
      H[Context packs]
      V[Kosh Verify]

      R --> C
      R --> D
      R --> F
      C --> E
      C --> G
      C --> H
      C --> V
      D --> V
    end

    C --> I[(Local cartridge)]
    D --> I
    E --> I
    G --> I
    I --> J[Plain files]
    I --> K[SQLite / FTS]
    I --> L[Audit ledger]

仓库根目录包含代码。卡匣根目录包含实时记忆存储。受监视的导入文件夹可以将新内容导入卡匣，而不会将运行时数据与源代码检出目录混在一起。

60 秒快速入门

需要 Python 3.10 或更高版本。

python -m pip install --upgrade llm-kosh
llm-kosh install --yes
llm-kosh status

这会安装软件包，在 ~/.llmkosh/cartridge 创建默认卡匣，配置本地默认设置，并在可能的情况下注册受支持的桌面集成。

创建并查询自定义卡匣：

llm-kosh --root ./my-cartridge init --owner "Local User"
llm-kosh --root ./my-cartridge add --kind note --title "First memory" --body "Hello"
llm-kosh --root ./my-cartridge query "Hello"

管理后台服务：

llm-kosh service start
llm-kosh service status
llm-kosh service stop

当前可用功能

核心项目现已可用：

• 已发布的 Python 软件包 llm-kosh
• 用于创建、搜索、导入、打包和验证卡匣的本地 CLI
• 受治理的 llm-kosh-memory CLI，用于提出、回忆、检查、处理冲突，以及明确审核可信记忆
• 用于证据感知时间／因果验证的 Kosh Verify CLI 和 Python API
• 确定性的 Kosh Verify 事件演示和验收测试
• 具有明确写入、变更和私有导出能力门控的本地 MCP 服务
• 源码级 MCP 组合，在不改变这些门控的前提下，添加只读 kosh_verify 和受治理的可信记忆工具
• 用于导入和维护任务的后台服务
• 基于纯文件、可供检查的存储，并带有本地索引
• 防篡改变更日志
• GitHub Actions 测试、质量检查、安全扫描和发布工作流
• 用于有证据支持的记忆和引用上下文的实验性公司知识库基础

剩余的发布工作主要是完善桌面软件包并完成 Windows、macOS 和 Linux 平台的签名。此处介绍的 llm-kosh-mcp 和 llm-kosh-memory 入口已存在于当前 master 源码中，计划用于下一次软件包发布；当前已发布的 PyPI 2.1.3 软件包早于这些入口。

与 MCP 客户端搭配使用

目前已发布的软件包通过现有 CLI 提供标准 MCP 服务：

llm-kosh --root ./my-cartridge mcp-server

在当前源代码中，组合后的 MCP 入口提供标准服务、只读的 kosh_verify，以及受治理的可信记忆工具：

python -m pip install -e .
llm-kosh-mcp --root ./my-cartridge

等效的模块调用方式：

python -m llm_kosh.mcp_trusted_memory_server --root ./my-cartridge

可信记忆 MCP 接口有意设置了权限限制：

• trusted_memory_recall、trusted_memory_inbox、trusted_memory_conflicts 和 trusted_memory_explain 均为只读。
• trusted_memory_propose 需要 --allow-write。
• trusted_memory_review 需要 --allow-mutate。
• Agent 创建的提案证据会记录为 agent_observation，绝不会自行提升为 user_direct。
• 显式审核可以更改生命周期，而不会重写原始来源的权威性；严格召回仍要求证据具有权威性或可信度。

Kosh Verify 不需要额外权限。写入、变更和私密导出功能仍需选择启用，并继续使用标准服务标志：

llm-kosh-mcp --root ./my-cartridge --allow-write
llm-kosh-mcp --root ./my-cartridge --allow-write --allow-mutate
llm-kosh-mcp --root ./my-cartridge --allow-private

组合后的服务还支持本地可流式传输的 HTTP：

llm-kosh-mcp --root ./my-cartridge --http --port 8000
# endpoint: http://127.0.0.1:8000/mcp

如果将 HTTP 传输暴露到回环地址之外，请将其视为真实的网络边界。有关受治理记忆的约定，请参阅 MCP 上的可信记忆；有关 kosh_verify 的约定，请参阅 Kosh Verify；有关常规 MCP 设置，请参阅 MCP 指南。

公司知识大脑基础

实验性的公司知识大脑层在简单的笔记召回之外扩展了知识库。它引入了以参考为先的证据、会话和事件理解、基于证据的记忆、审核生命周期、权限优先的检索，以及结构化的引用上下文包。

迁移现有知识库：

llm-kosh --root ./my-cartridge brain migrate --dry-run
llm-kosh --root ./my-cartridge brain migrate
llm-kosh --root ./my-cartridge brain health
llm-kosh --root ./my-cartridge brain context "Prepare the next project decision"

注册现有文件，但不复制其源字节：

llm-kosh --root ./my-cartridge brain register ./report.xlsx --artifact-type worksheet
llm-kosh --root ./my-cartridge brain inspect <evidence-id> \
  --locator '{"sheet":"Summary","range":"A1:F25"}'
llm-kosh --root ./my-cartridge brain evaluate

根据已注册的 JSONL 导出文件构建可重放的会话或事件图：

llm-kosh --root ./my-cartridge brain register ./session.jsonl --artifact-type structured_data
llm-kosh --root ./my-cartridge brain understand <evidence-id> --dry-run
llm-kosh --root ./my-cartridge brain understand <evidence-id>
llm-kosh --root ./my-cartridge brain episodes --query "what was implemented"

参阅公司知识大脑基础。

核心概念

有三个重要位置：

1. 仓库根目录 — 源代码检出目录。
2. 知识库根目录 — 由 --root 或 LLMKOSH_ROOT 选择的实时记忆存储。
3. 监视的收集文件夹 — receipts/、intake/ 和配置的外部投放文件夹。

如果文件被放入知识库的收集区域，服务可以异步处理它们。也可以通过 [daemon].watched_directories 监视外部文件夹。

可选功能

python -m pip install "llm-kosh[watch]"     # filesystem events
python -m pip install "llm-kosh[server]"    # FastAPI service
python -m pip install "llm-kosh[semantic]"  # local semantic search
python -m pip install "llm-kosh[ingest]"    # document conversion helpers
python -m pip install "llm-kosh[all]"       # all optional features

基础安装中包含 MCP 支持。

安全模型

LLM-Kosh 对 Agent 权限和导出边界采取谨慎策略：

• 默认情况下，存储和搜索均在本地进行
• 不会自动进行云同步或软件包遥测
• MCP 默认以只读模式启动
• 写入、变更和私密导出功能需要明确选择启用
• 可选的 HTTP 传输是真实的网络边界，应进行相应配置
• 共享前会检查导出的上下文中是否包含常见机密模式
• 知识库文件采用明文，这是有意设计；如果本地静态数据需要加密，请使用操作系统磁盘加密

有关权威威胁模型、报告指南和当前安全边界，请参阅 SECURITY.md。

项目状态

LLM-Kosh 是一个积极维护的开源持久 Agent 记忆基础设施项目。

Python 软件包、CLI、MCP 服务、本地服务、Kosh Verify 接口、测试工作流和发布流程均已投入使用。目前的工作重点是互操作性、打包、受治理记忆、证据感知验证，以及让外部贡献者更容易安全地扩展项目。

Electron 桌面应用与 Python 软件包分开打包。支持本地开发者构建和 Windows 安装程序冒烟测试；桌面应用公开 GA 发布仍需完成经验证的 Windows 代码签名以及 macOS Developer ID 签名和公证。

有关详细的发布准备情况，请参阅 GA_READINESS.md。

开发者工作流

python -m pip install -e ".[server,watch,ingest]"
python -m pytest -q

单独运行小型公开验证验收契约：

python scripts/kosh_verify_acceptance.py

进行打包或发布相关更改时：

python -m build
python -m twine check dist/*

原生 C++ 数学加速为可选功能。设置 LLM_KOSH_BUILD_NATIVE=1 并在构建前安装 pybind11，即可对其进行测试。发布版 wheel 使用可移植的纯 Python 回退方案。

贡献

欢迎贡献，尤其是以下方面：

• MCP 互操作性
• 测试和回归覆盖
• 打包和跨平台可靠性
• 文档
• 本地优先的记忆工作流
• 安全加固
• 证据和检索质量
• 可复现的验证和基准测试方法

在提出重大更改前，请阅读 CONTRIBUTING.md。请通过 GitHub Issues 提交可复现且不涉及敏感信息的错误报告和功能提案；涉及安全问题的报告请遵循 SECURITY.md。

文档

指南	用途
快速入门	首次安装和本地使用
Kosh Verify	感知证据的验证契约和可复现演示
通过 MCP 实现可信记忆	通过 MCP 实现受治理的跨 Agent 回忆、提案、冲突处理和审核
架构	系统结构和设计
CLI 参考	命令参考
MCP 指南	MCP 配置和使用
开发者指南	开发工作流
MCP 开发者指南	MCP 内部机制
服务开发者指南	后台服务内部机制
桌面开发者指南	桌面端打包
发布工程	构建和发布流程
安全	威胁模型和报告方式
GA 就绪情况	当前发布状态
已归档的历史文档	历史资料

开源

LLM-Kosh 以开源方式在 MIT License 下维护。

欢迎提交错误报告、有针对性的拉取请求、互操作性改进、测试和文档贡献。

---