# ellmos-homebase-mcp

Canonical repository: https://github.com/ellmos-ai/ellmos-homebase-mcp
Package: https://www.npmjs.com/package/ellmos-homebase-mcp
License: MIT
Status: public alpha

ellmos Homebase is a local-first MCP stdio server for LLM orchestration. It combines local memory, knowledge entries, persistent state, garden storage, model-routing recommendations, swarm planning, passive API discovery, self-tests, connector queues, automation-chain planning, and plugin discovery in one server. Memory, knowledge, state-memory, and tasks support `agent_id` provenance for shared team-memory workflows.

Important files:

- `README.md`: English installation and usage guide with quick navigation, 4 target personas, 10-dimension comparative matrix, and Mermaid sequence diagram.
- `README_de.md`: German installation and usage guide with quick navigation, 4 target personas, 10-dimension comparative matrix, and Mermaid sequence diagram.
- `SECURITY.md`: Bilingual security policy with local-first guarantees, 48h SLA, and invariant matrix.
- `THIRD_PARTY_LICENSES.md`: Permissive open-source license review for runtime and dev dependencies.
- `MARKETING-LOG.txt`: Discoverability, target personas, and 10 governance runtime invariants.
- `KONZEPT.md`: German concept and module roadmap.
- `MODE-CONTRACT.md`: binding contract for the `canonical` and `bundled` engine modes (German).
  Defines both stack modes, the per-namespace seam status, and the rule that a requested
  `canonical` engine which is unreachable causes a tool error instead of a silent fallback to
  the bundled database.
- `config/homebase.example.toml`: Example configuration.
- `server.json`: MCP Registry metadata.
- `glama.json`: Glama-compatible MCP directory metadata.
- `src/homebase/server.py`: MCP stdio server entry point.
- `src/homebase/registry.py`: Module discovery and tool dispatch.
- `src/homebase/modules/`: Homebase tool modules.
- `tests/`: Pytest coverage for config, registry, modules, contract tests, and localization.

Tool namespace groups:

- `hb_mem_*`: SQLite-backed local memory.
- `hb_kb_*`: SQLite-backed knowledge entries.
- `hb_state_*`: persistent local state and tasks.
- `hb_garden_*`: small local knowledge garden.
- `hb_route_*`: credential-free routing recommendations and feedback stats.
- `hb_swarm_*`: swarm planning patterns.
- `hb_api_*`: passive API probing with local history.
- `hb_test_*`: built-in self-tests.
- `hb_conn_*`: local connector registry and queues without network sends.
- `hb_auto_*`: local automation chain definitions and plan-only queued runs.
- `hb_plug_*`: plugin discovery and dry-run records without executing plugin code.
- `hb_policy_*`: read-only, canonical-only delegation to policy-registry (resolve/list rules).
- `hb_ticket_*`: read-only, canonical-only delegation to ticket-master (list/show tickets).
- `hb_lock_*`: read-only, canonical-only delegation to lock-master (list/check active locks).

## Audience

- LLM developers and AI engineers building local agent workflows with MCP-compatible tools
- Claude Code, Codex, and Gemini CLI users who want persistent local memory, state, and routing without cloud dependencies
- Developers orchestrating multi-agent swarms or automation chains locally
- Teams running self-hosted LLM setups who need a local knowledge base and API-probing layer
- Python and Node.js developers looking for a comprehensive, offline-first MCP server

## Search Phrases

```
ellmos Homebase MCP server
ellmos-ai ellmos-homebase-mcp
local-first LLM orchestration MCP
MCP memory knowledge routing swarm state API testing
stdio MCP server for local LLM agents
ellmos-ai homebase mcp local memory
MCP knowledge garden persistent state SQLite
local swarm planning MCP agent coordination
offline LLM orchestration memory routing
MCP server SQLite memory knowledge routing
offline agent orchestration MCP server
MCP swarm planning persistent state API discovery
```

## Disambiguation

This repository is not related to Elmo or ELMO voice generators, AllenAI ELMo embeddings, Eclipse LMOS, generic cloud-hosted agent platforms, or single-purpose MCP memory servers. Homebase is the ellmos-ai local-first orchestration MCP server for memory, knowledge, routing, state, swarm planning, passive API discovery, connector queues, automation planning, and plugin discovery.

## Last-checked: 2026-09-16