willow-mcp

Agent-neutral MCP server with persistent memory and task execution. Works with any MCP client: Claude Code, Claude Desktop, Cursor, or any custom agent that speaks stdio MCP.

Corpus memory: the whole Willow constellation — the code, human, and collaboration corpora assembled and queryable — lives in the sovereign willow-compose repo. The hub calls it; it doesn't live here (keeping the hub lean).

Three storage backends in one server:

• SOIL store — SQLite-backed local key/value store with full-text search and soft delete
• Postgres knowledge base — multi-keyword searchable knowledge graph
• Kart task queue — sandboxed task executor for shell commands and scripts

Every tool call is authorized via a filesystem-based manifest ACL — no ACL database, no external auth service. See Authorization.

Install

pip install willow-mcp

Requires Python 3.11+. Postgres is optional — SOIL store works standalone.

willow-mcp-init    # scaffold $WILLOW_HOME (idempotent)
willow-mcp-compile --force   # compile manifests (use product venv — see below)
willow-mcp-sign-seed hanuman # ratify home seed + detach-sign (operator terminal only)
willow-mcp-compile-persona hanuman # seed → personas/hanuman.md (AS-7)

Local sandbox (one command)

To take a fresh clone to a working stdio server — venv, editable install, scaffolded $WILLOW_HOME, compiled manifests, and (best-effort) a local Postgres with every table created — run:

bash scripts/sandbox-bootstrap.sh   # idempotent; ends with a live diagnostic_summary

On a bootstrapped sandbox the schema mappings for the tables the script itself just created are auto-confirmed (so task_* and knowledge writes work immediately), behind three guards: existing mapping artifacts are never touched, every field must resolve exact, and the live columns must equal the repo's own DDL — an adopted/foreign database always falls through to the human schema_confirm_mapping path (see src/willow_mcp/sandbox_confirm.py).

It scaffolds a repo-local, gitignored .willow/ so the sandbox never touches your real fleet state. Postgres is optional and handled best-effort (the SOIL store stands alone); pass WILLOW_SKIP_PG=1 for a SOIL-only stand-up, or WILLOW_PG_BOOTSTRAP_ROLE=1 on a bare cluster where your OS user has no Postgres role yet.

A fresh Postgres database needs willow-mcp's tables. On a shared fleet DB they already exist; on a standalone install, apply the DDL in docs/schema/ (knowledge, agents, routing_decisions, tasks — the four diagnostic_summary checks for). The bootstrap script applies all four for you. Each knowledge/tasks write path stays locked behind schema_confirm_mapping until you confirm the mapping once.

PATH note: ~/.local/bin/willow-mcp is often the fleet shim (sap_mcp.py), not this product. Use the venv binary from wherever you ran pip install willow-mcp (or pip install -e . in a clone) — e.g. .venv/bin/willow-mcp-compile --force or .venv/bin/willow-mcp compile-agents --force — not a bare willow-mcp on PATH.

Runtime layout: docs/design/product-layout.md (LOCKED).

Tools

Tool	Description
store_put	Write record (JSON object) to SQLite store
store_get	Read record by record_id
store_list	List all records in a collection
store_update	Update an existing record
store_search	Multi-keyword AND search in a collection
store_delete	Soft-delete a record by record_id
store_search_all	Search across all col