thecodacus/understory

understory – 适用于LLM代理的自接线Markdown知识库

这是什么

• 一个轻量级、基于文件的“记忆”，代理可以读取、写入和查询。记忆以遵循 Open Knowledge Format (OKF) v0.1 的纯Markdown文件集合形式存在——每个概念都是一个带有小型YAML前置元数据块（type等）的Markdown文件。
• 该仓库附带一个服务器，将此包封装为工具调用接口（MCP）、一个React Web UI和一个CLI。服务器可以在本地运行（Docker或从源代码），并与任何OpenAI兼容或Anthropic兼容的LLM端点通信。

关键理念

1. 确定性包层 – 保证每次变更都生成有效的OKF包（前置元数据存在、索引文件重新生成、日志追加、路径沙盒化）的是代码而非LLM提示。
2. 代理驱动更新 – 要求LLM决定更改内容，服务器安全地应用更改。
3. 图形视图与追踪 – 概念以力导向图（Obsidian风格）可视化，并且每次代理交互都记录为可在图上重放的追踪。
4. 配置文件 – 单个服务器可以托管多个隔离的记忆，每个记忆通过各自的API密钥选择。
5. 维护工具 – memory_maintain 对图形进行lint检查，查找孤立概念或损坏的链接，并请求内部代理修复。

交互方式

接口	功能
MCP服务器 (/mcp 或 stdio)	提供工具集 memory_query、memory_add、memory_update、memory_status、memory_maintain。调用是流式的，因此LLM可以实时看到工具结果。
Web UI (http://localhost:3800)	浏览包树、查看实时图、查看更新日志并与同一代理聊天。工具调用内联显示；追踪可重放。
CLI (pnpm agent:query …、pnpm agent:mutate …)	用于测试或脚本的快速命令行访问。
配置文件CLI (`profiles create	list

快速开始（Docker）

services:
  understory:
    image: ghcr.io/thecodacus/understory:latest
    ports: ["3800:3800"]
    extra_hosts: ["host.docker.internal:host-gateway"]
    volumes:
      - understory-memory:/bundle   # 您的markdown包存放在这里
    environment:
      BUNDLE_ROOT: /bundle
      LLM_API_BASE_URL: ${LLM_API_BASE_URL}
      LLM_API_KEY: ${LLM_API_KEY}
      LLM_API_FORMAT: openai   # 或 "anthropic"
      LLM_MODEL: ${LLM_MODEL:-}

docker compose up -d   # UI: http://localhost:3800, MCP: http://localhost:3800/mcp

您可以将服务器指向任何OKF包（本地文件夹、命名卷或绑定挂载）。LLM端点可以是OpenAI、DeepSeek、Anthropic、Groq或本地运行的llama.cpp服务器。

典型工作流程

1. 启动会话 – 服务器将当前知识库的简要概述注入LLM的系统提示和memory_query工具描述中。
2. 向代理提问 – 例如 memory_query "What is our deployment schedule?"。
3. 添加新事实 – memory_add "We deploy on Fridays, never Mondays"。代理创建一个markdown概念，更新反向链接，UI立即显示新节点。
4. 维护 – 定期（或计划）运行memory_maintain以自动修复孤立节点和损坏的链接。
5. 重放 – 在UI中打开一个追踪，查看交互期间读取/写入了哪些概念。

为什么使用它？

• 人类可读且版本可控 – 记忆以纯Markdown存储，可在Git中diff，因此您可以审计更改或回滚。
• 模型无关 – 适用于任何支持工具调用的LLM；服务器处理繁重工作。
• 自组织 – 内部代理保持图形整洁，减少知识库增长时的漂移。
• 多租户 – 配置文件允许您在同一主机上保留独立的知识图谱（工作、健康、副项目）。

限制 / 当前范围

• 搜索是简单的线性扫描；可扩展到数千个概念，但还不是全文索引或基于嵌入的检索。
• UI是单页React应用；除了Bearer令牌外没有身份验证（仅建议在LAN上使用）。
• 图级模式（类型化实体、更丰富的关系）已计划但未实现。

参与进来

• 使用 pnpm install && pnpm build 从源代码运行仓库；monorepo包含 core、server 和 web 包。
• 测试（pnpm test）涵盖包验证、并发和MCP往返。
• 通过GitHub上的问题/PR贡献；项目采用MIT许可，欢迎扩展（例如，FTS5/嵌入搜索、自定义页面类型模式）。

---

Understory 让您为LLM代理提供一个持久、可编辑且可视化的知识图谱，该图谱存在于纯Markdown中——一个“不断增长的记忆”，不会将您锁定在专有数据库中。