ellmos-homebase-mcp
OfficialA local-first, zero-egress MCP server that gives LLM agents persistent SQLite-backed memory, knowledge, state, planning and orchestration tools.
Memory (
hb_mem_*) – store facts/lessons/working notes with category, confidence andagent_idprovenance; keyword search; build compact context strings for prompt injection; merge duplicates and decay/prune low-confidence entries (dry-run by default).Knowledge base (
hb_kb_*) – full-text search, ingest text/URL/file content with tags and source, fetch single entries, list tags.State & tasks (
hb_state_*) – key/value state memory, plus task creation, listing, updating (status, priority, description) and a connector-dispatch status stub.Model routing (
hb_route_*) – recommend a model/provider for a prompt under constraints, rate responses for feedback learning, read routing stats — no credentials or network calls.Swarm planning (
hb_swarm_*) – generate plan-only blueprints for parallel chunking, consensus voting, boss-worker hierarchy, and stigmergy/blackboard coordination.Garden store (
hb_garden_*) – store, retrieve, search and (only if explicitly enabled) run keyed entries.API probing (
hb_api_*) – passive discovery against a URL via OpenAPI, wordlist, pattern and HATEOAS strategies; auto-detect schema; export results as Markdown/JSON; review probe history.Self-tests (
hb_test_*) – list batteries, run tests, and read summarized or detailed results.Connectors (
hb_conn_*) – list connectors and queue/read inbound messages locally with health and queue counts, without any network delivery.Automation (
hb_auto_*) – list chain definitions, queue plan-only runs, and inspect run status/results without executing external backends.Plugins (
hb_plug_*) – discover plugins in a local directory, inspect metadata, and record dry-runs without executing plugin code.Canonical read-only seams – resolve/list policy-registry rules, list/show ticket-master tickets by lifecycle category, and list/check lock-master locks (call before writing to a project dir); these fail closed if the canonical engine is absent.
Primary target of the server: it is designed for local, offline LLM orchestration against locally-hosted models such as Ollama (also Qwen/Llama-class models), providing a model router, credential-free API probing, swarm patterns, team memory with agent provenance, and knowledge/state tools that operate entirely locally with zero cloud egress.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ellmos-homebase-mcp Remember that I prefer dark mode for all UIs."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
For AI Assistants & LLM Agents: Machine-readable architecture summary, index, and tool capabilities are published in llms.txt. MCP registry metadata is available in server.json.
Quick Navigation / Schnellnavigation
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)Security & Vulnerability Reporting (
#sec-16)Development (
#sec-17)License & Statutory Liability Disclaimer (§ 521 BGB) (
#sec-18)Marketing Log (MARKETING-LOG.txt) | Changelog (CHANGELOG.md) | Contributing (CONTRIBUTING.md) | Code of Conduct (CODE_OF_CONDUCT.md) | Legal Attribution (NOTICE) | Deutsche Version (README_de.md)
Related MCP server: tdai-memory-mcp
System Architecture
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 --> DBFour-View Architectural Topology Projection
+-------------------------------------------------------------------------------+
| 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) |
+-------------------------------------------------------------------------------+Sequence Flow & Lifecycle
1. Tool Call & Engine Seam Lifecycle (hb_mem_store)
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)2. Multi-Agent Swarm & Routing Lifecycle (hb_route_* & hb_swarm_*)
sequenceDiagram
autonumber
participant Client as MCP Client (Ollama / Local Agent)
participant Stdio as Transport Layer (stdio)
participant Server as Server Core (homebase.server)
participant Route as Route Module (hb_route_*)
participant Swarm as Swarm Module (hb_swarm_*)
Note over Client,Route: Phase 1: Model routing (credential-free, no model call)
Client->>Stdio: JSON-RPC tools/call (hb_route_select, prompt="Debug this Python stacktrace", constraints={"speed": "fast"})
Stdio->>Server: Decode & dispatch to route module
Server->>Route: Analyse the prompt (code, research, planning and creative terms, length)
Route-->>Server: Recommendation (route_id, provider, model, strategy, confidence, signals)
Server-->>Stdio: JSON-RPC Response (no credentials, no external network query)
Stdio-->>Client: Model/provider candidate selected
Note over Client,Swarm: Phase 2: Swarm planning (plan only, nothing is executed or stored)
Client->>Stdio: JSON-RPC tools/call (hb_swarm_hierarchy, task="Audit the module", subtasks=["review code", "review tests"])
Stdio->>Server: Decode & dispatch to swarm module
Server->>Swarm: Build the boss-worker plan
Swarm-->>Server: Plan (status "planned", boss role, one worker per subtask)
Server-->>Stdio: JSON-RPC Response (structured plan, the caller starts the workers)
Stdio-->>Client: Plan returned for the caller to executeCore Capabilities & Security Invariants
Capability / Invariant | Guarantee | Technical Implementation |
100% Local-First & Zero-Egress | Complete privacy and offline operation; no unexpected cloud communication or telemetry. | All persistent memory, knowledge, and state are saved in local SQLite ( |
Strict Engine Seams & Fail-Closed | No silent fallback into disconnected databases when requesting canonical systems. |
|
Team-Memory Provenance ( | Deterministic audit trail and filterable ownership for multi-agent workflows. | Native |
Credential-Free Discovery & Planning | Zero secret exposure during local routing recommendations and API probing. |
|
Safe Plan-and-Queue Adapters | Safe queueing and chain staging without arbitrary remote code execution. |
|
Full Native i18n Localization | Seamless multilingual developer and agent interaction. | Localized tool descriptions and JSON schemas for |
Non-Elevation & Secret Hygiene | Unprivileged execution and strict credential exclusion from distribution. | Non-root compatibility; live configs/secrets ignored in |
Multi-OS CI Smoke Integrity | Verified cross-platform reliability on all major operating systems. | Multi-version CI matrix covering Python 3.10–3.13 and Node.js 20–24 on Linux/Windows/macOS. |
Governance & Runtime Invariants
Invariant ID | Title & Scope | Guarantee & Technical Enforcement | Verification Seam |
| 100% Local-First & Zero-Egress | All persistent memory, knowledge entries, and task states are stored locally in SQLite ( |
|
| Strict Engine Seams & Fail-Closed |
|
|
| Canonical-Only Isolation |
|
|
| Deterministic Provenance & Team-Memory | Multi-agent coordination requires strict isolation. All memories, knowledge facts, and task transitions record |
|
| Credential-Free Discovery & Probing | Model routing suggestions ( |
|
| Plan-Only Staging & Bounded Offline Queues | Connector queues ( |
|
| Native Multilingual Schema Parity | All 51 tool definitions, input schemas, and validation errors maintain 100% complete localization across 6 supported languages ( |
|
| Non-Elevation & RunAsInvoker Principle | Homebase runs strictly in unprivileged user space. It requires no administrator or root privileges and ignores sensitive local dotfiles and system credentials. |
|
| Multi-Host Lock & Conflict Discipline | Strict exclusion of conflict copies ( |
|
| 48h Response, 5-Day Triage & 30-Day Remediation SLA | Security disclosures sent to |
|
Target Personas & Discoverability
Homebase is purpose-built to solve architectural and operational challenges across four core technical audiences:
[PERSONA-01] Local LLM & Edge AI Developers
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}}
[PERSONA-02] Multi-Agent Swarm Orchestrators & Swarm Architects
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_idprovenance across all facts, memories, and task states; built-in swarm templates (boss/worker, chunked parallel, consensus voting viahb_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"}}
[PERSONA-03] Enterprise Security & Data Governance Officers
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), unprivilegedRunAsInvokeroperation, and formal 48h Security Response SLA (SECURITY.md).Reference Workflow:
{"tool": "hb_policy_list_rules", "arguments": {}}Guaranteed fail-closed behavior: raises
CanonicalEngineUnavailableinstead of silently falling back to insecure stubs.
[PERSONA-04] Cross-Framework AI Assistants & Pair Programmers
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"}}
High-Intent Search & SEO Keywords
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.
Comparative Matrix vs. Alternatives
Homebase provides a uniquely comprehensive, local-first MCP capability stack compared to specialized or cloud-bound alternatives:
Architectural & Runtime Dimension |
| Cloud Memory SaaS (Letta, Pinecone, LangSmith) | Generic Memory MCPs (mcp-server-memory, sqlite) | Heavy Agent Frameworks (CrewAI, AutoGen, LangGraph) | Ad-Hoc Scripts / Custom SQLite |
1. 100% Local-First & Zero Egress ( | Yes (100% local SQLite WAL, zero telemetry) | No (Cloud-hosted, mandatory egress, PII risk) | Partial (Local file, but no strict egress contracts) | Variable (Often requires cloud API keys / SaaS) | Yes (Local, but no protocol guarantees) |
2. Engine Seams & Fail-Closed ( | Yes (Strict | No (Opaque cloud failovers) | No (Single hardcoded backend) | No (Unchecked exceptions / silent fallbacks) | No (Ad-hoc failure handling) |
3. Canonical-Only Seams ( | Yes ( | No (No canonical system awareness) | No (No policy or lock integration) | No (No governance seam layer) | No (Manual coordination) |
4. Team-Memory & Attribution ( | Yes (Native | Partial (User-level only, lacks multi-agent filters) | No (Single global unpartitioned graph) | Partial (In-memory agent state, lost on restart) | No (Manual schema management) |
5. Credential-Free Discovery ( | Yes (Offline routing & swarm planning without tokens) | No (Requires active paid cloud credentials) | No (No model routing or swarm tools) | No (Requires API keys for LLM planners) | No (No structured planning) |
6. Plan-Only Staging Queues ( | Yes (Safe connector queues & dry-run automation) | No (Direct execution or none) | No (No connector or automation support) | No (Direct runtime side-effects) | No (Unsafe arbitrary execution) |
7. Tool Breadth & Surface | 51 Tools across 14 Modules in single stdio server | 1-5 API endpoints | 2-5 basic tools | Framework-level Python library (not MCP native) | Fragmented CLI utilities |
8. Multilingual Schema Parity ( | Yes (Full en, de, es, zh, ja, ru schema coverage) | English only | English only | English only | English only / None |
9. Non-Elevation Security ( | Yes (Unprivileged RunAsInvoker, dotfile defense) | Cloud SaaS (Tenant-isolation trust model) | Variable (Local file permissions) | Variable (Often runs in root containers) | Variable (User scripts) |
10. Security Response SLA ( | Yes (Formal 48h Response, 5d Triage & 30d Remediation in | Commercial SLA (Paid tiers only) | None / Best-effort community | None / Best-effort community | None |
Start Here
Need | Entry point |
Install the alpha MCP server |
|
Run from a source checkout |
|
Configure a local LLM harness, Claude Code, Codex, or any MCP client | |
Inspect the machine-readable project summary | |
Check registry metadata |
Status
Transport: stdio via the Python MCP SDK
Package status: public alpha package under
ellmos-aiRelease metadata: MIT
LICENSE,NOTICE,CHANGELOG.md,llms.txt, and MCP Registry metadata inserver.jsonTest 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_*,hb_mem_*,hb_kb_*andhb_route_*can delegate to the real canonical Gardener/Rinnsal/USMC/KnowledgeDigest/clutch engines instead of the bundled copies via[engines].mode = "canonical"(default remains"bundled"for a zero-dependency install). No silent fallback: if you requestcanonicaland the engine is unreachable, those tools return an error rather than quietly using the bundled DB — the server still starts and lists its tools. The public APIs of KnowledgeDigest and clutch are narrower than thehb_kb_*/hb_route_*families: under a reachable canonical enginehb_kb_search,hb_route_selectandhb_route_statsdelegate, whilehb_kb_ingest/get/listandhb_route_evaluatereportnot_supported(gaps are reported, not worked around). 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_idprovenance and filters for memory, knowledge, state memory, and tasks; SQLite uses WAL plus a busy timeout for safer concurrent agentsCredential-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
Install
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.
Option 1: Install From npm
npm install -g ellmos-homebase-mcp@alpha
ellmos-homebaseOption 2: Install From Source
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 -vAvoid creating a .venv inside cloud-synced folders if your sync client locks files. If you need an isolated environment, create it outside that folder.
Start From Source
$env:PYTHONPATH = "src"
python -m homebase.serverMCP Client Configuration
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.
Global npm Install
{
"mcpServers": {
"homebase": {
"command": "ellmos-homebase"
}
}
}Source Checkout
{
"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.
Server Configuration
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.tomloverride 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.
Tools
Important tool groups:
hb_mem_*for SQLite-backed memoryhb_kb_*for SQLite-backed knowledge entrieshb_state_*for persistent SQLite state and taskshb_garden_*for a small SQLite garden storehb_route_*for credential-free model-routing recommendations and feedback statshb_swarm_*for credential-free swarm planning patternshb_api_*for passive HTTP API discovery with SQLite historyhb_test_*for built-in metadata and smoke self-testshb_conn_*for a local connector registry plus SQLite-backed inbox/outbox queues without network sendshb_auto_*for local automation chain definitions and queued plan-only runs without backend executionhb_plug_*for local plugin discovery and dry-run records without executing plugin codehb_policy_*(read-only, canonical-only) for resolving/listing policy-registry ruleshb_ticket_*(read-only, canonical-only) for listing/showing ticket-master tickets by lifecycle folderhb_lock_*(read-only, canonical-only) for checking/listing active lock-master locks
hb_state_task_list returns one task page. Optional status and agent_id filters
apply before pagination; limit defaults to 200 and accepts 1–500, while
cursor is the exclusive task ID returned as next_cursor by the prior page.
The response keeps count (tasks on this page) and tasks, and adds total
(all matches for the filters, regardless of cursor), truncated, next_cursor,
limit, and cursor. Continue while truncated is true. Pages use ascending
task IDs; each call is a fresh read, so concurrent edits may change later
totals or membership. In canonical mode this requires Task-Master's
TaskClient.list_page API (PR #22, commit ac2c681c); until that API is
installed, the tool returns status: unavailable with
error.code: task_pagination_unavailable instead of an incomplete list.
Discovery Context
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 serverlocal-first LLM orchestration MCPMCP server SQLite memory knowledge routingoffline agent orchestration MCP serverMCP 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.
ellmos-ai Ecosystem
This MCP server is part of the ellmos-ai ecosystem — AI infrastructure, MCP servers, and intelligent tools.
MCP Server Family
Server | Tools | Focus | npm |
47 | Filesystem, process management, interactive sessions, cloud-lock-safe operations | ||
23 | Code analysis, JSON repair, imports, diffs, regex | ||
12 | File repair, format conversion, batch operations | ||
19 | n8n workflow management via AI assistants | ||
20 | MCP stack discovery, profile management, control plane | ||
51 | Local-first LLM memory, knowledge, state, routing, swarm orchestration |
| |
8 | Server operations: health checks, log analysis, deploy dry-runs, mail diagnostics |
| |
3 | Headless Blender asset QA and FBX reimport verification |
| |
10 | Model-agnostic computer use: capture, safety-gated actions, Windows UIA |
|
AI Infrastructure
Project | Description |
Local-first text-based OS for LLM agents — 113+ handlers, 550+ tools, SQLite memory | |
Model-agnostic computer-use core powering Open Compute MCP | |
Provider-neutral LLM orchestration with auto-routing and budget tracking | |
Lightweight agent memory, connectors, and automation infrastructure | |
Self-hosted AI research stack (Ollama + n8n + Rinnsal + KnowledgeDigest) | |
Autonomous agent chain framework for Claude Code | |
Minimalist database-driven LLM OS prototype (4 functions, 1 table) | |
Testing framework for LLM operating systems (7 dimensions) | |
Manifest-based Git fetch blueprint; its manifest lists Homebase as |
Desktop Software & Sibling Ecosystem
Our partner umbrella organization open-bricks and sister organizations maintain local-first, privacy-centric desktop software and developer tools:
Application / Tool | Organization | Focus & Integration |
| Local-first desktop file organizer and PII-safe workspace exchange | |
| Distraction-free Markdown & PDF documentation manager | |
| Local-first PDF OCR and text layer embedding | |
| Offline document summarization and embedding engine | |
| Developer workspace hub and multi-repository management | |
| Isolated sandbox runner and local code execution assistant | |
| Hook-based LLM memory provenance and session injection gate | |
| Zero-dependency SQLite schema migration & replication layer |
Third-Party Licenses & Level 1 SBOM
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.
Security & Vulnerability Reporting
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.xResponse 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, andsecurity@open-bricks.org.Private Advisory: GitHub Security Advisories.
Development
$env:PYTHONIOENCODING = "utf-8"
$env:PYTHONDONTWRITEBYTECODE = "1"
python -m pytest -ra -v
npm run smoke
npm pack --dry-run --jsonNext useful step: add optional execution backends behind explicit configuration.
License & Statutory Liability Disclaimer (§ 521 BGB)
Software License
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.
Statutory Notice & Liability Limitation (§ 521 BGB - German Law)
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):
Liability Limitation: The author and contributors are liable only in cases of intentional misconduct (Vorsatz) or gross negligence (grobe Fahrlässigkeit).
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).
Local-First & Non-Elevation Principle:
ellmos-homebase-mcpis 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.
Coordinated Security Response SLA
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.orgAdvisory Portal: GitHub Security Advisories
Policy Documentation:
SECURITY.md
Bundles and partners
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.
Available Tools
51 toolshb_api_discoverC
Auto-detect API schema from a base URL
Inputs: url (required).
hb_api_exportC
Export probe results as Markdown or JSON
Inputs: probe_id (required), format.
hb_api_historyC
List previous probe results
Inputs: limit.
hb_api_probeC
Probe a URL using all strategies (OpenAPI, wordlist, pattern, HATEOAS)
Inputs: url (required), strategies.
hb_auto_list_chainsB
List available local automation chain definitions
Inputs: no named parameters.
hb_auto_resultC
Get the recorded local automation run result
Inputs: run_id (required).
hb_auto_runB
Queue a local automation chain plan without executing external backends
Inputs: chain (required), input.
hb_auto_statusB
Check local automation run status
Inputs: run_id (required).
hb_conn_listB
List configured connectors
Inputs: no named parameters.
hb_conn_receiveB
Get recent local inbox messages for a connector
Inputs: connector (required), limit.
hb_conn_sendB
Queue a message for a connector without network delivery
Inputs: message (required), connector (required), target.
hb_conn_statusB
Check local connector health and queue counts
Inputs: connector (required).
hb_garden_findC
Search the garden
Inputs: query (required), limit.
hb_garden_getC
Get a specific entry by key
Inputs: key (required).
hb_garden_putC
Store or update an entry
Inputs: key (required), value (required).
hb_garden_runC
Run a stored command if execution is explicitly enabled
Inputs: key (required).
hb_kb_getB
Get a single knowledge entry with metadata
Inputs: id (required), agent_id.
hb_kb_ingestC
Add new knowledge (text, URL, or file content)
Inputs: content (required), tags, source, agent_id.
hb_kb_listC
List tags in the knowledge base
Inputs: agent_id.
hb_kb_searchB
Full-text search in knowledge database
Inputs: query (required), limit, agent_id, category.
hb_lock_checkA
Check whether a project directory currently has an active lock -- call this BEFORE any write action there (read-only).
Inputs: project_dir (required).
hb_lock_listA
List all currently active locks across configured roots (read-only).
Inputs: no named parameters.
hb_mem_consolidateA
Decay memory confidence and prune low-confidence entries (dry_run previews; dry_run=false applies)
Inputs: decay, dry_run, agent_id, min_confidence.
hb_mem_contextC
Generate compact context string for prompt injection
Inputs: focus, agent_id, max_tokens.
hb_mem_mergeB
Confidence-based merge of duplicate memories (dry_run previews; dry_run=false applies the merge)
Inputs: dry_run, agent_id.
hb_mem_queryC
Search memory by keyword
Inputs: query (required), limit, agent_id, category.
hb_mem_storeC
Store a fact, lesson, or working memory entry
Inputs: content (required), category (required), agent_id, confidence.
hb_plug_discoverC
Scan a local directory for plugin metadata
Inputs: path.
hb_plug_infoC
Get local plugin metadata
Inputs: plugin (required).
hb_plug_listB
List discovered local plugins
Inputs: no named parameters.
hb_plug_runB
Record a plugin dry-run without executing plugin code
Inputs: plugin (required), args.
hb_policy_listC
List policy-registry entries (read-only, canonical-only), optionally filtered.
Inputs: kind, query, scope, consumer.
hb_policy_resolveC
Resolve the authoritative policy/rule/decision for a scope via the real policy-registry engine (read-only, canonical-only).
Inputs: scope (required), query, consumer, required_kind.
hb_route_evaluateC
Rate a response for routing feedback loop (epsilon-greedy learning)
Inputs: quality (required), route_id (required).
hb_route_selectC
Analyze a prompt and recommend the best model/provider
Inputs: prompt (required), constraints.
hb_route_statsC
Get routing statistics and learning progress
Inputs: no named parameters.
hb_state_dispatchC
Return connector-dispatch status
Inputs: message (required), connector (required), target.
hb_state_mem_getC
Get state memory entries
Inputs: type, query, agent_id.
hb_state_mem_setC
Store a state memory entry
Inputs: key (required), value (required), type, agent_id.
hb_state_task_createC
Create a new task
Inputs: title (required), agent_id, priority, description.
hb_state_task_listC
List tasks with optional status filter
Inputs: status, agent_id.
hb_state_task_updateC
Update a task (status, description, priority)
Inputs: task_id (required), status, agent_id, priority, +1 more.
hb_swarm_consensusC
Get majority vote from multiple independent agents
Inputs: question (required), voters.
hb_swarm_hierarchyD
Boss-worker delegation pattern
Inputs: task (required), subtasks.
hb_swarm_parallelC
Split task into chunks and process in parallel
Inputs: task (required), chunks (required), workers.
hb_swarm_stigmergyC
Indirect coordination via shared state (blackboard pattern)
Inputs: task (required), iterations.
hb_test_listB
List available test batteries
Inputs: no named parameters.
hb_test_resultsC
Get results of last test run
Inputs: format, battery.
hb_test_runC
Run a test battery or single test
Inputs: battery (required), test.
hb_ticket_listA
List tickets in one lifecycle category (INBOX/ACTIONABLE/QUEUED/BLOCKED/WAITING/USER/PARKED/SOLVED) -- header fields only, read-only.
Inputs: category (required), limit.
hb_ticket_showB
Show one ticket's header fields by ID (e.g. T-20260825-196589547), read-only.
Inputs: ticket_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 51 tools
Most tools are cleanly separated by domain prefix and verb. Minor overlaps exist: hb_api_probe vs hb_api_discover (probe-all-strategies vs schema auto-detect), and hb_mem_* vs hb_state_mem_* memory families could be confused by an agent. The many *_run/*_list/*_get tools are differentiated by their domain prefix, so ambiguity is limited.
Strong, predictable hb_<domain>_<verb> pattern across nearly all tools (hb_kb_search, hb_mem_store, hb_lock_check). A few deviations: hb_auto_list_chains inverts the order used by hb_auto_run/status/result, and accessors are inconsistently named hb_garden_get / hb_kb_get vs hb_ticket_show.
51 tools is well above the heavy threshold and far beyond what an agent can reliably select from in one session. The surface bundles at least a dozen separate domains (plugins, memory, routing, KB, swarm, state, garden, API, tests, connectors, automation, policy, tickets, locks), which should be split into focused servers.
Coverage is broad per domain but shallow: plugins have no install/enable, KB and garden lack update/delete, tasks have create/update but no delete, and policy/ticket tools are read-only by design. Read-only design is defensible, but the missing mutating operations leave lifecycle dead ends in several domains.
Maintenance
Related MCP Connectors
Private-by-default, local-first memory/context/task orchestrator for MCP apps and agents.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Persistent memory, hybrid search and a goal graph for AI agents, over stdio or remote HTTP.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceLocal-first, auditable memory for AI agents. Provides durable context for MCP hosts with SQLite storage, CLI, and MCP tools for memory management.2Apache 2.0
- AlicenseAqualityFmaintenanceLocal-first MCP memory server that gives AI coding agents long-term memory via SQLite and sqlite-vec, with optional LLM-powered layering. No gateway or API key required.7113 npm4MIT
- AlicenseCqualityBmaintenanceLocal-first, governable long-term memory for AI agents. Provides SQLite-backed storage, cross-session recall, and traceable memory corrections through a standard MCP interface.4036 PyPI1MIT
- AlicenseBqualityBmaintenanceSovereign, deterministic, local-first context and DAG lifecycle engine with native stdio MCP server for autonomous AI coding agents.23MIT