ellmos-homebase-mcp

Alpha MCP server for local-first LLM orchestration: memory, knowledge, routing, swarm patterns, API probing, persistent state, tests, automation planning, and plugin discovery in one stdio server.

Homebase is designed primarily for local LLMs (Ollama, Qwen, Llama, or any locally-hosted model via a MCP-capable harness). All persistent storage uses SQLite with no cloud dependency. External LLM providers (Claude, Codex, Gemini, OpenAI) can also connect as MCP clients, but local, offline-capable setups are the primary target.

German README: README_de.md

Part of the ellmos-ai family under the open-bricks umbrella.

Discoverability: Published on npm as ellmos-homebase-mcp and maintained in the ellmos-ai organization.

• System Architecture (#sec-01)
• Sequence Flow & Lifecycle (#sec-02)
• Core Capabilities & Security Invariants (#sec-03)
• Governance & Runtime Invariants (#sec-04)
• Target Personas & Discoverability (#sec-05)
• Comparative Matrix vs. Alternatives (#sec-06)
• Start Here (#sec-07)
• Status (#sec-08)
• Install (#sec-09)
• MCP Client Configuration (#sec-10)
• Server Configuration (#sec-11)
• Tools (#sec-12)
• Discovery Context (#sec-13)
• ellmos-ai Ecosystem (#sec-14)
• Third-Party Licenses (THIRD_PARTY_LICENSES.md) (#sec-15)
• Security & Vulnerability Reporting (#sec-16)
• Development (#sec-17)
• License & Statutory Liability Disclaimer (§ 521 BGB) (#sec-18)
• Marketing Log (MARKETING-LOG.txt) | Changelog (CHANGELOG.md) | Legal Attribution (NOTICE) | Deutsche Version (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)

Homebase is purpose-built to solve architectural and operational challenges across four core technical audiences:

• Profile & Objective: AI engineers building offline or edge applications with Ollama, Qwen, or Llama models who need a robust orchestration harness.
• Pain Points: Cloud memory APIs introduce unwanted latency, privacy leaks, subscription billing, and network failure modes.
• Homebase Solution: Zero-cloud dependency, local SQLite WAL persistence (~/.homebase/), and 51 standard stdio tools providing memory, FTS5 knowledge search, and task tracking.
• Reference Workflow:

  {"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}}

• Profile & Objective: System architects orchestrating multi-agent collectives (Claude Code, Codex, Antigravity, local agents) operating concurrently on shared codebases.
• Pain Points: State collisions, lack of origin tracking, race conditions in shared memory, and uncoordinated task delegation.
• Homebase Solution: Native agent_id provenance across all facts, memories, and task states; built-in swarm templates (boss/worker, chunked parallel, consensus voting via hb_swarm_*).
• Reference Workflow:

  {"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"}}

• Profile & Objective: CISOs, SecOps teams, and compliance auditors in regulated industries (healthcare, finance, defense) evaluating developer agent toolchains.
• Pain Points: Silent cloud telemetry, unvetted remote side-effects, privilege escalation risks, and missing SLA assurances.
• Homebase Solution: Strict zero-egress architecture, fail-closed canonical engine seams (MODE-CONTRACT.md), unprivileged RunAsInvoker operation, and formal 48h Security Response SLA (SECURITY.md).
• Reference Workflow:

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

  Guaranteed fail-closed behavior: raises CanonicalEngineUnavailable instead of silently falling back to insecure stubs.

• Profile & Objective: Developers utilizing multiple AI coding assistants (Claude Desktop, Codex, Cursor, Gemini) seeking uniform context and tool parity across environments.
• Pain Points: Incompatible custom tool APIs, fragmented scratchpads, and lack of multilingual developer schemas.
• Homebase Solution: Standard stdio MCP transport, machine-readable project metadata (llms.txt, server.json, glama.json), and 100% complete schema localization across 6 languages (en, de, es, zh, ja, ru).
• Reference Workflow:

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

• English Intent: 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.
• German Intent: 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 provides a uniquely comprehensive, local-first MCP capability stack compared to specialized or cloud-bound alternatives:

• Transport: stdio via the Python MCP SDK
• Package status: public alpha package under ellmos-ai
• Release metadata: MIT LICENSE, NOTICE, CHANGELOG.md, llms.txt, and MCP Registry metadata in server.json
• Test gate: GitHub Actions covers Python 3.10/3.11/3.12/3.13 plus Node.js 20/22/24 smoke and npm package checks
• Current core: module discovery, MCP tool listing, MCP tool dispatch, config fallbacks, local planning/probing/queue/dry-run adapters
• Real local SQLite modules: hb_mem_*, hb_kb_*, hb_garden_*, hb_state_*
• Engine seams: hb_garden_*, hb_state_task_* and hb_mem_* can delegate to the real canonical Gardener/Rinnsal/USMC engines instead of the bundled SQLite copies via [engines].mode = "canonical" (default remains "bundled" for a zero-dependency install). No silent fallback: if you request canonical and the engine is unreachable, those tools return an error rather than quietly using the bundled DB — the server still starts and lists its tools. Binding rule and migration notes: MODE-CONTRACT.md; mechanism: KONZEPT.md.
• Canonical-only seams (no bundled alternative at all): hb_policy_* (policy-registry), hb_ticket_* (ticket-master), hb_lock_* (lock-master) — all read-only in v1. A locally faked copy of live policy/ticket/lock state would mislead rather than help, so these three always attempt the canonical module and fail closed unconditionally if it is unreachable.
• Team-memory basics: agent_id provenance and filters for memory, knowledge, state memory, and tasks; SQLite uses WAL plus a busy timeout for safer concurrent agents
• Credential-free alpha adapters: hb_route_*, hb_swarm_*, hb_api_*, hb_test_*, hb_conn_*, hb_auto_*, hb_plug_*
• i18n: fully localized MCP tool descriptions, input-schema field descriptions, and unknown-tool errors for en, de, es, zh, ja, ru (English fallback for any unset key)
• Roadmap: optional real LLM/API integrations and explicit execution backends

The npm package contains a Node wrapper that starts the Python server. You still need Python 3.10+ and the Python package mcp>=1.0.0.

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

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

Avoid creating a .venv inside cloud-synced folders if your sync client locks files. If you need an isolated environment, create it outside that folder.

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

Homebase uses the standard stdio mcpServers configuration format. The same snippet works in any MCP-capable client or harness: BACH/Buddha (local Ollama), Claude Code, Codex, Cursor, or any other MCP host.

Note on local LLMs: A bare Ollama instance does not speak MCP natively — you need a MCP-capable harness on top of it (e.g., BACH, an open-source MCP proxy, or another orchestration layer). Configure that harness to include Homebase as an MCP server using the snippet below.

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

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

Replace /absolute/path/to/ellmos-homebase-mcp with your local checkout path.

Example: config/homebase.example.toml

Machine-readable project context: llms.txt

MCP Registry metadata: server.json

Default paths:

• %USERPROFILE%\.homebase\homebase.toml
• %USERPROFILE%\.config\homebase\homebase.toml
• override with HOMEBASE_CONFIG

Language can be configured with [server].language, HOMEBASE_LANG, or HOMEBASE_LOCALE. The writing agent can be passed per tool call as agent_id; otherwise modules use HOMEBASE_AGENT_ID, AGENT_ID, a module-level agent_id, or 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"]

Modules with missing optional dependencies are skipped without blocking server startup.

Important tool groups:

• hb_mem_* for SQLite-backed memory
• hb_kb_* for SQLite-backed knowledge entries
• hb_state_* for persistent SQLite state and tasks
• hb_garden_* for a small SQLite garden store
• hb_route_* for credential-free model-routing recommendations and feedback stats
• hb_swarm_* for credential-free swarm planning patterns
• hb_api_* for passive HTTP API discovery with SQLite history
• hb_test_* for built-in metadata and smoke self-tests
• hb_conn_* for a local connector registry plus SQLite-backed inbox/outbox queues without network sends
• hb_auto_* for local automation chain definitions and queued plan-only runs without backend execution
• hb_plug_* for local plugin discovery and dry-run records without executing plugin code
• hb_policy_* (read-only, canonical-only) for resolving/listing policy-registry rules
• hb_ticket_* (read-only, canonical-only) for listing/showing ticket-master tickets by lifecycle folder
• hb_lock_* (read-only, canonical-only) for checking/listing active lock-master locks

Use ellmos-homebase-mcp when searching for a local-first, offline-capable MCP server that gives local LLMs (Ollama, Qwen, Llama, or similar) persistent memory, knowledge management, routing, and orchestration — without requiring any cloud dependency. External LLM providers can also use it as an MCP server, but local-first setups are the primary design target.

Good search phrases:

• 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

Not the same as Elmo/ELMO voice tools, AllenAI ELMo embeddings, Eclipse LMOS, generic cloud agent platforms, or single-purpose MCP memory servers.

This MCP server is part of the ellmos-ai ecosystem — AI infrastructure, MCP servers, and intelligent tools.

Our partner umbrella organization open-bricks and sister organizations maintain local-first, privacy-centric desktop software and developer tools:

ellmos-homebase-mcp is verified to contain 0% copyleft dependencies. All runtime dependencies are permissively licensed (MIT, BSD-2-Clause, Apache-2.0, PSFL).

Full inventory, Level 1 SBOM Invariant Cross-Reference Matrix, and non-elevation certifications are documented in THIRD_PARTY_LICENSES.md and plain-text companion THIRD_PARTY_LICENSES.txt. Canonical copyright and author attribution is maintained in NOTICE.

ellmos-homebase-mcp strictly adheres to local-first, zero-egress, and non-elevation security principles. Full policies, SLAs, and security guarantees are documented in SECURITY.md:

• Supported Versions: 0.1.0-alpha.x
• Response SLA: Initial acknowledgment and triage within 48 hours. Detailed triage within 5 business days; remediation within 30 calendar days.
• Security Contacts: security@ellmos.ai, support@lukasgeiger.com, and security@open-bricks.org.
• Private Advisory: GitHub Security Advisories.

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

Next useful step: add optional execution backends behind explicit configuration.

ellmos-homebase-mcp is open-source software licensed under the MIT License. Canonical attribution to Lukas Geiger, the ellmos-ai family, and the open-bricks ecosystem is formally preserved in NOTICE. Third-party component licenses are cataloged in THIRD_PARTY_LICENSES.md.

This software is made available free of charge as an open-source project. Under German statutory law governing gratuitous software provision (§ 521 BGB Gefälligkeitsrecht):

1. Liability Limitation: The author and contributors are liable only in cases of intentional misconduct (Vorsatz) or gross negligence (grobe Fahrlässigkeit).
2. Warranty Limitation: In accordance with §§ 523, 524 BGB, warranty claims for material and legal defects (Sach- und Rechtsmängel) are excluded, except in cases where defects have been fraudulently concealed (arglistiges Verschweigen).
3. Local-First & Non-Elevation Principle: ellmos-homebase-mcp is provided on an "as is" and "as available" basis without any express or implied warranty. Operators run Homebase in unprivileged user mode (RunAsInvoker) at their own discretion.

For vulnerability reporting or security inquiries, our coordinated disclosure policy guarantees an initial response within 48 hours and triage within 5 business days:

• Security Contact: security@ellmos.ai | support@lukasgeiger.com | security@open-bricks.org
• Advisory Portal: GitHub Security Advisories
• Policy Documentation: SECURITY.md

Homebase MCP remains a standalone local-first MCP server. In the V4 composition it is an optional MCP access surface of the ellmos-memory-human-context-bundle: a configured system may use it to reach memory and human-context capabilities. This access role does not make Homebase the canonical owner of every memory, knowledge, state, routing or automation function; the selected host and system manifests retain those bindings.

Canonical or bundled engines are integration partners selected by explicit configuration, not implicit replacements for this server. Authoritative bundle membership, versions, profiles and private composition recipes remain in the corresponding bundle manifests. This public section is discovery-only.