ellmos Homebase

ellmos-homebase-mcp

用于本地优先大模型编排的 Alpha MCP 服务：在一个 stdio 服务中提供记忆、知识、路由、群体模式、API 探测、持久化状态、测试、自动化规划和插件发现。

Homebase 主要面向本地大模型（Ollama、Qwen、Llama，或通过支持 MCP 的工具框架接入的任何本地托管模型）。所有持久化存储均使用 SQLite，不依赖云服务。外部大模型提供商（Claude、Codex、Gemini、OpenAI）也可作为 MCP 客户端连接，但本地且支持离线运行的配置是主要目标。

德语版 README：README_de.md

隶属于 open-bricks 旗下的 ellmos-ai 家族。

**可发现性：**已在 npm 上以 ellmos-homebase-mcp 发布，并由 ellmos-ai 组织维护。

说明

**面向 AI 助手和大模型 Agent：**机器可读的架构摘要、索引和工具功能已发布于 llms.txt。MCP 注册表元数据可在 server.json 中查看。

快速导航 / Schnellnavigation

• 系统架构 (#sec-01)
• 时序流程与生命周期 (#sec-02)
• 核心能力与安全不变量 (#sec-03)
• 治理与运行时不变量 (#sec-04)
• 目标用户画像与可发现性 (#sec-05)
• 与替代方案的比较矩阵 (#sec-06)
• 从这里开始 (#sec-07)
• 状态 (#sec-08)
• 安装 (#sec-09)
• MCP 客户端配置 (#sec-10)
• 服务配置 (#sec-11)
• 工具 (#sec-12)
• 发现上下文 (#sec-13)
• ellmos-ai 生态系统 (#sec-14)
• 第三方许可证 (THIRD_PARTY_LICENSES.md) (#sec-15)
• 安全与漏洞报告 (#sec-16)
• 开发 (#sec-17)
• 许可证与法定责任免责声明（§ 521 BGB） (#sec-18)
• 营销日志 (MARKETING-LOG.txt) | 更新日志 (CHANGELOG.md) | 法律归属声明 (NOTICE) | 德语版本 (README_de.md)

---

系统架构

flowchart TD
    subgraph Clients ["MCP Clients (Local / Remote)"]
        Ollama["Local LLMs (Ollama, Qwen, Llama)"]
        Claude["Claude Code / Desktop"]
        Codex["Codex / Antigravity"]
    end

    subgraph Transport ["Transport Layer"]
        Stdio["stdio (Python MCP SDK)"]
    end

    subgraph Core ["ellmos-homebase-mcp Core Engine"]
        Server["homebase.server"]
        Config["homebase.config"]
    end

    subgraph ToolGroups ["51 MCP Tools across 14 Functional Modules"]
        Mem["hb_mem_* (SQLite Memory)"]
        KB["hb_kb_* (Knowledge Digest)"]
        State["hb_state_* (State & Tasks)"]
        Route["hb_route_* (Model Router)"]
        Swarm["hb_swarm_* (Swarm Patterns)"]
        Api["hb_api_* (API Probing)"]
        Conn["hb_conn_* (Connectors Queue)"]
        Auto["hb_auto_* (Automation Chains)"]
        Plug["hb_plug_* (Plugin Discovery)"]
        Garden["hb_garden_* (Garden Store)"]
        Test["hb_test_* (Self Tests)"]
        Policy["hb_policy_* (Policy Registry, read-only)"]
        Ticket["hb_ticket_* (Ticket Master, read-only)"]
        Lock["hb_lock_* (Lock Master, read-only)"]
    end

    subgraph Storage ["Local Storage (Offline-First)"]
        DB[(SQLite Storage ~/.homebase/)]
    end

    Clients --> Stdio
    Stdio --> Server
    Server --> Config
    Server --> ToolGroups
    ToolGroups --> DB

四视图架构拓扑投影

+-------------------------------------------------------------------------------+
|  VIEW 1: CALLER RUNTIMES, AGENT CLIENTS & ENTRYPOINTS                         |
|  - Local LLM Engines: Ollama (Qwen, Llama, Mistral, DeepSeek), Local Harnesses|
|  - Multi-Agent Orchestrators: Claude Code, Claude Desktop, OpenAI Codex, AGY  |
|  - IDE & Extension Interfaces: Cursor, VS Code MCP Extension, Windsurf        |
|  - stdio Protocol Transport: JSON-RPC 2.0 via Python Model Context Protocol   |
+---------------------------------------+---------------------------------------+
                                        | JSON-RPC 2.0 stdio (tools/list, tools/call)
                                        v
+-------------------------------------------------------------------------------+
|  VIEW 2: HOMEBASE MCP SOVEREIGN CORE & DISPATCH ORCHESTRATOR                  |
|  - Core Server & Life Cycle: homebase.server (stdio loop, signal handling)    |
|  - Module Registry & Dispatch: homebase.registry (i18n schemas, locale norm)  |
|  - 51 Sovereign MCP Tools across 14 Specialized Functional Modules:          |
|    * Memory & Knowledge: hb_mem_* (SQLite memory), hb_kb_* (FTS5 search)      |
|    * State & Planning: hb_state_* (tasks & KV), hb_garden_* (garden store)    |
|    * Routing & Swarms: hb_route_* (offline routing), hb_swarm_* (blueprints)  |
|    * Exploration & Testing: hb_api_* (schema probe), hb_test_* (diagnostics)  |
|    * Integration & Staging: hb_conn_* (safe queues), hb_auto_* (chain plans)  |
|    * Extensibility: hb_plug_* (dry-run discovery, no remote code execution)   |
|    * Canonical Seams: hb_policy_*, hb_ticket_*, hb_lock_* (read-only views)   |
+-------------------+-----------------------------------+-----------------------+
                    |                                   |
                    v (bundled SQLite mode)             v (canonical engine mode)
+---------------------------------------+ +-------------------------------------+
|  VIEW 3: RUNTIME PERSISTENCE &        | |  VIEW 3-ALT: CANONICAL SEAMS        |
|  SQLITE STORAGE ENGINE                | |  (MODE-CONTRACT.md)                 |
|  - Database: ~/.homebase/homebase.db  | |  - Policy Registry (hb_policy_*)    |
|  - Concurrency: Write-Ahead Log (WAL) | |  - Ticket Master (hb_ticket_*)      |
|  - Multi-Agent Provenance: agent_id   | |  - Lock Master (hb_lock_*)          |
|  - Search Engine: SQLite FTS5 index   | |  - Fail-Closed Discipline:          |
|  - Integrity: Busy timeouts & rollback| |    Raises CanonicalEngineUnavailable|
+-------------------+-------------------+ +-----------------+-------------------+
                    |                                       |
                    +-------------------+-------------------+
                                        |
                                        v
+-------------------------------------------------------------------------------+
|  VIEW 4: AIR-GAP DEFENSE PERIMETER, RUNASINVOKER & ZERO-EGRESS BOUNDARY        |
|  - 100% Local-First & Zero Egress: INV-LOCAL-01 (0 cloud calls, 0 telemetry)  |
|  - Unprivileged Execution: INV-PERM-08 (RunAsInvoker non-elevation principle) |
|  - Engine Seam Integrity: INV-ENGINE-02 & INV-SEAM-03 (strict fail-closed)   |
|  - Deterministic Provenance: INV-PROV-04 (agent_id attribution on all state)  |
|  - Credential-Free Operation: INV-CRED-05 & INV-STAGE-06 (no tokens/secrets)  |
|  - Multi-Host Lock Defense: INV-SYNC-09 (.gitignore sync/lock immunity)       |
|  - Permissive Licensing: Zero-Copyleft stack (MIT, PSFL-2.0, Apache-2.0)     |
|  - Statutory SLA & Disclaimer: INV-SLA-10 (48h response SLA, § 521 BGB)       |
+-------------------------------------------------------------------------------+

---

时序流程与生命周期

sequenceDiagram
    autonumber
    participant Client as MCP Client (Local LLM / Claude / Codex)
    participant Stdio as Transport Layer (stdio)
    participant Server as Server & Registry (homebase)
    participant Module as Functional Module (hb_mem / hb_state / hb_route)
    participant Engine as Engine Seam (Bundled vs Canonical)
    participant DB as SQLite Storage (~/.homebase/)

    Client->>Stdio: JSON-RPC 2.0 Request (tools/call: hb_mem_store, agent_id="agent-01")
    Stdio->>Server: Decode & dispatch tool call
    Server->>Module: Validate arguments & inject agent provenance
    alt Bundled Engine Mode (Default)
        Module->>DB: Execute SQLite query (WAL mode, busy timeout)
        DB-->>Module: Return structured records / mutation status
    else Canonical Engine Mode ([engines].mode = "canonical")
        Module->>Engine: Seam check (Gardener / TASKPLAN / USMC)
        alt Engine Available
            Engine-->>Module: Delegate to canonical subsystem
        else Engine Unreachable
            Engine-->>Module: Raise CanonicalEngineUnavailable (Fail-Closed)
        end
    end
    Module-->>Server: Format response in requested language (i18n: en/de/es/zh/ja/ru)
    Server-->>Stdio: Encode JSON-RPC 2.0 Response
    Stdio-->>Client: Result payload (Zero cloud egress, 100% local)

---

核心能力与安全不变量

能力 / 不变量	保证	技术实现
100% 本地优先与零外传	完全隐私保护并支持离线运行；不会发生意外的云端通信或遥测。	所有持久化记忆、知识和状态都保存在本地 SQLite (~/.homebase/) 中。
严格的引擎边界与故障关闭	请求规范系统时，不会悄然回退到未连接的数据库。	强制执行 MODE-CONTRACT.md：如果目标不可达，则引发 CanonicalEngineUnavailable。
团队记忆溯源 (agent_id)	为多 Agent 工作流提供确定性的审计跟踪和可筛选的所有权信息。	在记忆事实、知识条目和任务状态中原生跟踪 agent_id。
无需凭据即可发现与规划	在本地路由建议和 API 探测期间不会暴露任何机密。	hb_route_*、hb_swarm_* 和 hb_api_* 运行时不会传输 API 密钥或私有令牌。
安全的计划与队列适配器	安全地排队和暂存链，不会任意远程执行代码。	hb_conn_* 和 hb_auto_* 仅维护计划队列和离线暂存记录。
完整的原生 i18n 本地化	为开发者和 Agent 提供流畅的多语言交互体验。	为 en、de、es、zh、ja、ru 提供本地化工具描述和 JSON 架构。
不提权与机密信息卫生	以非特权方式执行，并严格防止凭据进入分发内容。	兼容非 root 执行；实时配置和机密信息在 .gitignore 和 .npmignore 中排除。
多操作系统 CI 冒烟测试完整性	验证在所有主流操作系统上的跨平台可靠性。	多版本 CI 矩阵覆盖 Linux/Windows/macOS 上的 Python 3.10–3.13 和 Node.js 20–24。

---

治理与运行时不变量

不变量 ID	标题与范围	保证与技术执行机制	验证入口
INV-LOCAL-01	100% 本地优先与零外发	所有持久化记忆、知识条目和任务状态都存储在本地 SQLite（~/.homebase/）中。零遥测、零分析，也不会发起未经请求的云端网络调用。	tests/test_server_transport.py、tests/test_repository_hygiene.py
INV-ENGINE-02	严格的引擎边界与失败关闭	强制执行 MODE-CONTRACT.md：将 [engines].mode = "canonical" 切换为规范模式后，如果规范引擎无法访问，绝不会静默回退到捆绑存储。	tests/test_engine_seams.py
INV-SEAM-03	仅规范引擎隔离	hb_policy_*、hb_ticket_* 和 hb_lock_* 提供对 policy-registry、ticket-master 和 lock-master 的只读视图。它们没有捆绑的仿制实现，并且始终失败关闭。	tests/test_new_seams.py
INV-PROV-04	确定性来源追踪与团队记忆	多 Agent 协调需要严格隔离。所有记忆、知识事实和任务状态变更都记录 agent_id 归属，并使用 SQLite WAL 并发机制和忙碌超时。	tests/test_module_contracts.py
INV-CRED-05	无需凭据即可发现与探测	模型路由建议（hb_route_*）、群体模式蓝图（hb_swarm_*）和 API 架构探测（hb_api_*）无需私有 API 密钥、令牌或凭据即可运行。	tests/test_module_contracts.py
INV-STAGE-06	仅限计划的暂存与有界离线队列	连接器队列（hb_conn_*）和自动化计划（hb_auto_*）记录离线蓝图和试运行暂存清单，不会执行任意远程代码或产生副作用。	tests/test_module_contracts.py
INV-I18N-07	原生多语言架构一致性	全部 51 个工具定义、输入架构和验证错误均在 6 种支持的语言（en、de、es、zh、ja、ru）中保持 100% 完整的本地化。	tests/test_i18n_completeness.py
INV-PERM-08	不提升权限与 RunAsInvoker 原则	Homebase 严格运行于非特权用户空间。它不需要管理员或 root 权限，并会忽略敏感的本地隐藏文件和系统凭据。	tests/test_repository_hygiene.py
INV-SYNC-09	多主机锁与冲突处理规范	严格排除冲突副本（*.sync-conflict-*、*-conflict-*），并遵守多 Agent 锁机制（LOCK.*、*.lock），以维护跨主机数据库完整性。	tests/test_metadata.py
INV-SLA-10	48 小时响应、5 天分诊与 30 天修复 SLA	发送至 [email protected]、[email protected] 或 [email protected] 的安全问题披露，将保证在 <=48 小时内首次响应、在 5 个工作日内完成分诊，并在 30 个日历日内完成经验证的修复。	SECURITY.md、tests/test_metadata.py

---

目标用户画像与发现方式

Homebase 专为解决四类核心技术受众面临的架构和运维挑战而打造：

[PERSONA-01] 本地大模型与边缘 AI 开发者

• 简介与目标： 使用 Ollama、Qwen 或 Llama 模型构建离线或边缘应用的 AI 工程师，需要可靠的编排框架。
• 痛点： 云端记忆 API 会带来不必要的延迟、隐私泄露、订阅费用和网络故障模式。
• Homebase 解决方案： 零云端依赖、本地 SQLite WAL 持久化（~/.homebase/），以及 51 个标准 stdio 工具，提供记忆、FTS5 知识搜索和任务跟踪功能。
• 参考工作流：

  {"tool": "hb_mem_store", "arguments": {"fact": "User prefers compact JSON output", "agent_id": "ollama-coder"}}
  {"tool": "hb_kb_search", "arguments": {"query": "API routing rules", "fts": true}}
  

[PERSONA-02] 多 Agent 群组编排者与群组架构师

• 简介与目标： 系统架构师，负责编排多个 Agent 组成的协作团队（Claude Code、Codex、Antigravity、本地 Agent），让它们在共享代码库上并行运行。
• 痛点： 状态冲突、缺少来源追踪、共享内存中的竞态条件，以及任务委派缺乏协调。
• Homebase 解决方案： 在所有事实、记忆和任务状态中原生追踪 agent_id 来源；内置群组模板（主控/工作者、分块并行、通过 hb_swarm_* 投票达成共识）。
• 参考工作流：

  {"tool": "hb_swarm_plan", "arguments": {"goal": "Audit security seams", "pattern": "consensus"}}
  {"tool": "hb_state_task_create", "arguments": {"title": "Verify fail-closed mode", "agent_id": "worker-audit-01"}}
  

[PERSONA-03] 企业安全与数据治理官

• 简介与目标： 受监管行业（医疗保健、金融、国防）中的 CISO、SecOps 团队和合规审计员，负责评估开发者 Agent 工具链。
• 痛点： 未明示的云端遥测、未经审核的远程副作用、权限提升风险，以及缺少 SLA 保障。
• Homebase 解决方案： 严格的零出站架构、故障时关闭的规范引擎接口（MODE-CONTRACT.md）、以非特权 RunAsInvoker 模式运行，以及正式的 48h 安全响应 SLA（SECURITY.md）。
• 参考工作流：

  {"tool": "hb_policy_list_rules", "arguments": {}}
  

  保证发生故障时关闭：引发 CanonicalEngineUnavailable，而不是静默回退到不安全的存根。

[PERSONA-04] 跨框架 AI 助手与结对编程助手

• 简介与目标： 使用多种 AI 编码助手（Claude Desktop、Codex、Cursor、Gemini）的开发者，希望在不同环境中获得统一的上下文和工具支持。
• 痛点： 自定义工具 API 不兼容、临时工作区分散，以及缺少多语言开发者 Schema。
• Homebase 解决方案： 标准 stdio MCP 传输、机器可读的项目元数据（llms.txt、server.json、glama.json），以及 6 种语言（en、de、es、zh、ja、ru）中 100% 完整的 Schema 本地化。
• 参考工作流：

  {"tool": "hb_ticket_list", "arguments": {"folder": "ACTIVE"}}
  

高意向搜索与 SEO 关键词

• 英语搜索意图： local-first LLM orchestration MCP server、offline agent memory SQLite WAL、stdio Model Context Protocol Ollama Qwen、multi-agent swarm planning persistent state、zero-egress MCP server enterprise AI、fail-closed engine seams MODE-CONTRACT、team-memory agent_id provenance。
• 德语搜索意图： Local-First LLM-Orchestrierung MCP-Server、Offline Agenten-Memory SQLite WAL、Model Context Protocol Stdio-Server Ollama、Multi-Agenten Schwarmplanung persistenter Zustand、Zero-Egress MCP-Server Unternehmens-KI、Fail-Closed Schnittstellen MODE-CONTRACT、Team-Memory Agenten-Provenienz。

---

与替代方案的比较矩阵

与专业化或依赖云端的替代方案相比，Homebase 提供了独特而全面的本地优先 MCP 能力栈：

架构与运行时维度	ellmos-homebase-mcp	云端记忆 SaaS（Letta、Pinecone、LangSmith）	通用记忆 MCP（mcp-server-memory、sqlite）	重型 Agent 框架（CrewAI、AutoGen、LangGraph）	临时脚本 / 自定义 SQLite
1. 100% 本地优先与零数据外传（INV-LOCAL-01）	是（100% 本地 SQLite WAL，零遥测）	否（托管于云端，必须向外传输数据，有 PII 风险）	部分（本地文件，但没有严格的数据外传约束）	不定（通常需要云 API 密钥 / SaaS）	是（本地，但没有协议保障）
2. 引擎接缝与失败关闭（INV-ENGINE-02）	是（严格遵循 MODE-CONTRACT.md，失败时抛出错误）	否（云端故障切换不透明）	否（只有一个硬编码后端）	否（未检查异常 / 静默回退）	否（临时的故障处理）
3. 仅规范化接缝（INV-SEAM-03）	是（hb_policy_*、hb_ticket_*、hb_lock_* 失败时关闭）	否（不了解规范化系统）	否（未集成策略或锁）	否（没有治理接缝层）	否（手动协调）
4. 团队记忆与归属追踪（INV-PROV-04）	是（事实、知识和任务原生支持 agent_id）	部分（仅支持用户级别，缺少多 Agent 筛选器）	否（单一全局、未分区的图）	部分（Agent 状态存于内存，重启后丢失）	否（手动管理架构）
5. 无凭据发现（INV-CRED-05）	是（无需令牌即可离线进行路由与群体规划）	否（需要有效的付费云凭据）	否（没有模型路由或群体工具）	否（LLM 规划器需要 API 密钥）	否（没有结构化规划）
6. 仅规划暂存队列（INV-STAGE-06）	是（安全的连接器队列与试运行自动化）	否（直接执行，或不支持）	否（不支持连接器或自动化）	否（运行时副作用直接发生）	否（不安全的任意执行）
7. 工具广度与接口范围	单个 stdio 服务包含 14 个模块、51 个工具	1–5 个 API 端点	2–5 个基础工具	框架级 Python 库（非原生 MCP）	零散的 CLI 工具
8. 多语言架构一致性（INV-I18N-07）	是（架构完整覆盖 en、de、es、zh、ja、ru）	仅英语	仅英语	仅英语	仅英语 / 无
9. 非提权安全（INV-PERM-08）	是（使用非特权 RunAsInvoker 运行，防御点开头文件）	云端 SaaS（基于租户隔离的信任模型）	不定（本地文件权限）	不定（通常在 root 容器中运行）	不定（用户脚本）
10. 安全响应 SLA（INV-SLA-10）	是（在 SECURITY.md 中明确规定 48 小时响应、5 天分诊和 30 天修复）	商业 SLA（仅付费套餐提供）	无 / 尽力而为的社区支持	无 / 尽力而为的社区支持	无

---

从这里开始

需求	入口
安装 alpha 版 MCP 服务	npm install -g ellmos-homebase-mcp@alpha
从源代码检出目录运行	使用 PYTHONPATH=src 执行 python -m homebase.server
配置本地 LLM 工具链、Claude Code、Codex 或任何 MCP 客户端	MCP 客户端配置
查看机器可读的项目摘要	llms.txt
检查注册表元数据	server.json

---

状态

• 传输方式：通过 Python MCP SDK 使用 stdio
• 软件包状态：ellmos-ai 下的公开 alpha 软件包
• 发布元数据：MIT LICENSE、NOTICE、CHANGELOG.md、llms.txt，以及 server.json 中的 MCP Registry 元数据
• 测试门槛：GitHub Actions 覆盖 Python 3.10/3.11/3.12/3.13，以及 Node.js 20/22/24 的冒烟测试和 npm 软件包检查
• 当前核心功能：模块发现、MCP 工具列表、MCP 工具调度、配置回退、本地规划/探测/队列/试运行适配器
• 实际本地 SQLite 模块：hb_mem_*、hb_kb_*、hb_garden_*、hb_state_*
• 引擎接入点：hb_garden_*、hb_state_task_* 和 hb_mem_* 可通过 [engines].mode = "canonical" 委托给实际的规范 Gardener/Rinnsal/USMC 引擎，而非使用捆绑的 SQLite 副本（默认仍为 "bundled"，以实现零依赖安装）。 **不会静默回退：**如果请求 canonical，但引擎不可访问，这些工具会返回错误，而不会悄悄使用捆绑数据库——服务仍会启动并列出其工具。绑定规则和迁移说明：MODE-CONTRACT.md； 实现机制：KONZEPT.md。
• 仅规范引擎接入点（完全没有捆绑替代方案）：hb_policy_*（policy-registry）、hb_ticket_*（ticket-master）、hb_lock_*（lock-master）——v1 中均为只读。伪造一份本地副本来模拟实时策略/票据/锁状态会造成误导，而非提供帮助，因此这三类工具始终会尝试调用规范模块；如果模块不可访问，则一律安全失败。
• 团队记忆基础功能：记忆、知识、状态记忆和任务均支持 agent_id 来源追踪与筛选；SQLite 使用 WAL 和忙碌超时，以便多个 Agent 更安全地并发运行
• 无凭据的 alpha 适配器：hb_route_*、hb_swarm_*、hb_api_*、hb_test_*、hb_conn_*、hb_auto_*、hb_plug_*
• 国际化：en、de、es、zh、ja、ru 的 MCP 工具描述、输入架构字段描述和未知工具错误均已完整本地化（未设置的键回退到英语）
• 路线图：可选的实际大模型/API 集成和显式执行后端

---

安装

npm 软件包包含一个用于启动 Python 服务的 Node 封装程序。你仍需要 Python 3.10+ 和 Python 软件包 mcp>=1.0.0。

选项 1：从 npm 安装

npm install -g ellmos-homebase-mcp@alpha
ellmos-homebase

选项 2：从源代码安装

git clone https://github.com/ellmos-ai/ellmos-homebase-mcp.git
cd ellmos-homebase-mcp
$env:PYTHONIOENCODING = "utf-8"
python -m pip install -e ".[dev]"
python -m pytest -ra -v

如果云同步客户端会锁定文件，请避免在云同步文件夹中创建 .venv。如果需要隔离环境，请在该文件夹之外创建。

从源代码启动

$env:PYTHONPATH = "src"
python -m homebase.server

---

MCP 客户端配置

Homebase 使用标准的 stdio mcpServers 配置格式。同一段配置适用于任何支持 MCP 的客户端或运行框架：BACH/Buddha（本地 Ollama）、Claude Code、Codex、Cursor，或任何其他 MCP 主机。

**本地大模型说明：**裸 Ollama 实例本身不原生支持 MCP——你需要在其上运行支持 MCP 的框架（例如 BACH、开源 MCP 代理或其他编排层）。按照下方示例配置该框架，将 Homebase 纳入其中，作为 MCP 服务。

全局 npm 安装

{
  "mcpServers": {
    "homebase": {
      "command": "ellmos-homebase"
    }
  }
}

源代码检出

{
  "mcpServers": {
    "homebase": {
      "command": "python",
      "args": ["-m", "homebase.server"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/ellmos-homebase-mcp/src"
      }
    }
  }
}

将 /absolute/path/to/ellmos-homebase-mcp 替换为本地检出路径。

---

服务配置

示例：config/homebase.example.toml

机器可读的项目上下文：llms.txt

MCP Registry 元数据：server.json

默认路径：

• %USERPROFILE%\.homebase\homebase.toml
• %USERPROFILE%\.config\homebase\homebase.toml
• 使用 HOMEBASE_CONFIG 覆盖

可通过 [server].language、HOMEBASE_LANG 或 HOMEBASE_LOCALE 配置语言。 可在每次工具调用时通过 agent_id 指定写作 Agent；否则，模块会使用 HOMEBASE_AGENT_ID、AGENT_ID、模块级 agent_id 或 unknown。

[server]
name = "ellmos-homebase"
language = "en" # en, de, es, zh, ja, ru

[modules]
enabled = ["mem", "route", "kb", "swarm", "state", "garden", "api", "test", "conn", "auto", "plug"]

缺少可选依赖的模块会被跳过，不会阻止服务启动。

---

工具

重要的工具组：

• hb_mem_*：用于由 SQLite 支持的记忆
• hb_kb_*：用于由 SQLite 支持的知识条目
• hb_state_*：用于持久化的 SQLite 状态和任务
• hb_garden_*：用于小型 SQLite 花园存储
• hb_route_*：用于无需凭据的模型路由建议和反馈统计
• hb_swarm_*：用于无需凭据的蜂群规划模式
• hb_api_*：用于被动发现 HTTP API，并使用 SQLite 记录历史
• hb_test_*：用于内置元数据和冒烟自测试
• hb_conn_*：用于本地连接器注册表，以及由 SQLite 支持的收件箱／发件箱队列，不会发送网络请求
• hb_auto_*：用于本地自动化链定义，以及已排队的仅规划运行，不会执行后端操作
• hb_plug_*：用于本地插件发现和试运行记录，不会执行插件代码
• hb_policy_*（只读，仅规范模式）：用于解析／列出策略注册表规则
• hb_ticket_*（只读，仅规范模式）：用于按生命周期文件夹列出／显示 ticket-master 工单
• hb_lock_*（只读，仅规范模式）：用于检查／列出活动的 lock-master 锁

hb_state_task_list 会返回一页任务。可选的 status 和 agent_id 过滤器 会在分页前应用；limit 默认为 200，接受 1–500；而 cursor 是上一页通过 next_cursor 返回的排他任务 ID。 响应会保留 count（本页的任务数）和 tasks，并新增 total （符合过滤条件的所有任务数，不受 cursor 影响）、truncated、next_cursor、 limit 和 cursor。当 truncated 为 true 时继续获取后续页。页面按 任务 ID 升序排列；每次调用都会重新读取，因此并发编辑可能会改变后续 页面的总数或成员。在规范模式下，这需要 Task-Master 的 TaskClient.list_page API（PR #22，提交 ac2c681c）；在安装此 API 之前， 该工具会返回 status: unavailable 和 error.code: task_pagination_unavailable，而不是不完整的列表。

---

发现上下文

当你要寻找一款本地优先、可离线使用的 MCP 服务，为本地大模型（Ollama、Qwen、Llama 或类似模型）提供持久化记忆、知识管理、路由和编排，且不依赖任何云服务时，请使用 ellmos-homebase-mcp。外部大模型提供商也可以将其用作 MCP 服务，但本地优先的设置是其主要设计目标。

推荐搜索词：

• ellmos Homebase MCP server
• local-first LLM orchestration MCP
• MCP server SQLite memory knowledge routing
• offline agent orchestration MCP server
• MCP swarm planning persistent state API discovery

它与 Elmo／ELMO 语音工具、AllenAI ELMo 嵌入、Eclipse LMOS、通用云端 Agent 平台或单一用途的 MCP 记忆服务不同。

---

ellmos-ai 生态系统

此 MCP 服务是 ellmos-ai 生态系统的一部分，涵盖 AI 基础设施、MCP 服务和智能工具。

MCP 服务系列

服务	工具	重点	npm
FileCommander	47	文件系统、进程管理、交互式会话、适用于云锁的安全操作	ellmos-filecommander-mcp
CodeCommander	23	代码分析、JSON 修复、导入、差异、正则表达式	ellmos-codecommander-mcp
Clatcher	12	文件修复、格式转换、批量操作	ellmos-clatcher-mcp
n8n Manager	19	通过 AI 助手管理 n8n 工作流	n8n-manager-mcp
ControlCenter	20	MCP 堆栈发现、配置管理、控制平面	ellmos-controlcenter-mcp
Homebase	51	本地优先的大模型记忆、知识、状态、路由、群体编排	ellmos-homebase-mcp（alpha）
ServerCommander	8	服务操作：健康检查、日志分析、部署试运行、邮件诊断	ellmos-servercommander-mcp（alpha）
Blender Use	3	无头 Blender 资产 QA 和 FBX 重新导入验证	ellmos-blender-use-mcp（alpha）
Open Compute	10	模型无关的计算机操作：捕获、安全门控操作、Windows UIA	open-compute-mcp（alpha）

AI 基础设施

项目	描述
BACH	面向大模型 Agent 的本地优先文本式操作系统 — 113+ 个处理程序、550+ 个工具、SQLite 记忆
open-compute	为 Open Compute MCP 提供支持的模型无关计算机操作核心
clutch	提供商中立的大模型编排，支持自动路由和预算跟踪
rinnsal	轻量级 Agent 记忆、连接器和自动化基础设施
ellmos-stack	可自托管的 AI 研究堆栈（Ollama + n8n + Rinnsal + KnowledgeDigest）
MarbleRun	面向 Claude Code 的自主 Agent 链框架
gardener	极简的数据库驱动型大模型操作系统原型（4 个函数、1 张表）
ellmos-tests	大模型操作系统测试框架（7 个维度）
agent-ops-stack	基于清单的 Git 获取蓝图；其清单将 Homebase 列为 homebase-mcp，并标注了 mcp-runtime、memory-facade 和 task-facade。请按照 Homebase 的设置说明进行操作。

桌面软件与关联生态

我们的合作方上层组织 open-bricks 及姐妹组织维护着本地优先、注重隐私的桌面软件和开发者工具：

应用 / 工具	组织	重点与集成
ProFiler	file-bricks	本地优先的桌面文件整理工具，以及安全保护个人身份信息（PII）的工作区交换
DokuZen	doc-bricks	免受干扰的 Markdown 和 PDF 文档管理器
PDFtoPDFocr	doc-bricks	本地优先的 PDF OCR 和文本层嵌入
KnowledgeDigest	doc-bricks	离线文档摘要与嵌入引擎
DevCenter	dev-bricks	开发者工作区中心和多仓库管理
CodeBox	dev-bricks	隔离的沙盒运行器和本地代码执行助手
MemoryHooker	ellmos-ai	基于 Hook 的 LLM 记忆来源追踪和会话注入闸门
sqlite-transit-sync	ellmos-ai	零依赖的 SQLite 架构迁移与复制层

---

第三方许可证与一级 SBOM

经验证，ellmos-homebase-mcp 不含任何 Copyleft 依赖。所有运行时依赖均采用宽松许可证（MIT、BSD-2-Clause、Apache-2.0、PSFL）。

完整清单、一级 SBOM 不变量交叉引用矩阵以及非升级认证记录在 THIRD_PARTY_LICENSES.md 和纯文本配套文件 THIRD_PARTY_LICENSES.txt 中。规范的版权和作者署名信息保存在 NOTICE 中。

---

安全与漏洞报告

ellmos-homebase-mcp 严格遵循本地优先、零外联和不提升权限的安全原则。完整政策、SLA 和安全保证详见 SECURITY.md：

• 支持的版本：0.1.0-alpha.x
• 响应 SLA：在 48 小时内初步确认并进行分类；在 5 个工作日内完成详细分类，并在 30 个日历日内修复。
• 安全联系人：[email protected]、[email protected] 和 [email protected]。
• 私密公告：GitHub 安全公告。

---

开发

$env:PYTHONIOENCODING = "utf-8"
$env:PYTHONDONTWRITEBYTECODE = "1"
python -m pytest -ra -v
npm run smoke
npm pack --dry-run --json

下一步可行工作：在显式配置后面添加可选执行后端。

---

许可证与法定责任免责声明（§ 521 BGB）

软件许可证

ellmos-homebase-mcp 是采用 MIT License 许可的开源软件。 对 Lukas Geiger、ellmos-ai 系列和 open-bricks 生态的规范署名已正式保存在 NOTICE 中。 第三方组件许可证汇总在 THIRD_PARTY_LICENSES.md 中。

法定声明与责任限制（§ 521 BGB——德国法律）

本软件作为开源项目免费提供。根据德国关于无偿提供软件的法定规定（§ 521 BGB Gefälligkeitsrecht）：

1. 责任限制：作者和贡献者仅在存在故意不当行为（Vorsatz）或重大过失（grobe Fahrlässigkeit）的情况下承担责任。
2. 保修限制：根据 §§ 523、524 BGB，因物质和法律瑕疵（Sach- und Rechtsmängel）提出的保修索赔不予受理，但故意隐瞒瑕疵（arglistiges Verschweigen）的情况除外。
3. 本地优先与不提权原则：ellmos-homebase-mcp 按“现状”和“可用状态”提供，不提供任何明示或默示保证。运营方自行决定以非特权用户模式（RunAsInvoker）运行 Homebase。

协同安全响应 SLA

对于漏洞报告或安全咨询，我们的协同披露政策保证在 48 小时内初步响应，并在 5 个工作日内完成分级：

• 安全联系邮箱：[email protected] | [email protected] | [email protected]
• 公告门户：GitHub 安全公告
• 政策文档：SECURITY.md

---

套件与合作伙伴

Homebase MCP 仍是独立的本地优先 MCP 服务。在 V4 组合中，它是 ellmos-memory-human-context-bundle 的可选 MCP 访问层： 已配置的系统可以通过它访问记忆和人类上下文能力。此访问角色并不意味着 Homebase 是所有记忆、知识、状态、路由或自动化功能的规范所有者；这些绑定关系仍由所选主机和系统清单保留。

规范引擎或捆绑引擎是通过显式配置选定的集成合作伙伴，而不是此服务的隐式替代品。权威的套件成员关系、版本、配置文件和私有组合方案仍以相应套件清单为准。本公开部分仅用于发现。