🤖 Knowtation and agent orchestration

What this page is: A practical guide for builders wiring Knowtation into agent systems—whether the agent talks over MCP (like Cursor) or runs knowtation CLI commands in a container. If you only want a one-page overview of CLI vs MCP vs Hub API, see AGENT-INTEGRATION.md first.

Knowtation is designed as a knowledge backend for multi-agent orchestration systems. Orchestrators and their agents can read from and write to the vault via CLI or MCP. This doc describes both options and how to integrate with systems like AgentCeption.

On this page: Why both surfaces → Option A (MCP) → Option B (CLI) → Patterns → AgentCeption → Muse / MuseHub → Summary — scroll to the matching emoji heading.

🧭 Why both CLI and MCP?

Recommendation: support both. Use MCP where the runtime already has MCP; use CLI where agents run in isolated environments (Docker, git worktrees) and only have the binary and env.

🔌 Option A: MCP

1. Run the Knowtation MCP server (e.g. knowtation mcp or your package’s MCP entry point).

2. Configure your client (Cursor, Claude Desktop, or the orchestrator’s MCP client) to use it. Example (Cursor / Claude):

   {
     "mcpServers": {
       "knowtation": {
         "command": "node",
         "args": ["/path/to/knowtation/mcp/server.mjs"],
         "env": { "KNOWTATION_VAULT_PATH": "/path/to/vault" }
       }
     }
   }
   

3. Tools (same semantics as CLI): search, get_note, list_notes, index, write, export, import. Same filters and JSON shapes as in SPEC §4.

4. Scope (Phase G): The server includes instructions with file:// paths for the vault and index data directory. Hosts that support MCP roots may also receive a one-time structured log of the client’s roots/list response (for debugging alignment).

5. Sampling: If the host supports MCP sampling, tools such as summarize may run the summary in the client’s LLM (host approval may be required). If sampling is unavailable, Knowtation falls back to server-side Ollama/OpenAI. Implementation lives under mcp/tools/ and mcp/sampling.mjs. Hosted MCP (OAuth, session pool) is documented in AGENT-INTEGRATION.md §2.

Use tiered retrieval from the SKILL: small limit, --fields path or path+snippet, then get_note only for chosen paths. See RETRIEVAL-AND-CLI-REFERENCE.md.

💻 Option B: CLI in the agent environment

1. Install Knowtation in the environment where the agent runs (e.g. in the Docker image used by engineer agents, or on the host that runs the orchestrator).
2. Set env (and optional config):
   • KNOWTATION_VAULT_PATH — path to the vault (required).
   • Optionally config/local.yaml or other env (e.g. QDRANT_URL, KNOWTATION_DATA_DIR).
     For read-only (search, list-notes, get-note), vault path and index are enough; for write/export, config may be needed (e.g. AIR).
3. Invoke from the agent:
   • knowtation search "auth flow" --project myapp --limit 3 --json
   • Parse JSON; then knowtation get-note <path> --json for the 1–2 paths you need.
   • To write back: knowtation write vault/projects/myapp/decisions/phase-1.md --stdin --frontmatter source=agentception date=2026-03-13 (body from stdin).

Same tiered retrieval pattern: use --limit, --fields path, --count-only to keep payloads small; then fetch full content only for selected paths.

🎯 Patterns

📖 Vault as knowledge backend (read)

• Before or during planning: Search the vault for requirements, decisions, or prior context (e.g. search "decisions about X" --project myapp --limit 5 --json). Use results to enrich the plan or the brain dump.
• During execution: When an engineer agent runs, it can call Knowtation (CLI or MCP) to get notes for the current project/component so code and PRs align with existing decisions.

✍️ Write-back (plans and summaries)

• After a phase or after “Create Issues,” write a short summary or the plan into the vault so the next phase or the next run can search it. Example: pipe a phase summary into knowtation write with frontmatter source: agentception, date, project. See the optional bridge script in scripts/write-to-vault.sh (or equivalent in this repo).

💸 Token and cost

• Use retrieval levers: --limit, --fields path, --snippet-chars, --count-only for search/list-notes; --body-only or --frontmatter-only for get-note when you only need one part. This keeps context small and cost low when agents pull vault content into their context.

🔗 AgentCeption specifically

For integration patterns with external orchestrators, see AGENT-INTEGRATION.md and GETTING-STARTED.md (agents section).

AgentCeption turns a brain dump into a structured plan (PlanSpec), GitHub issues, and an agent org (CTO → coordinators → engineers) that works in isolated worktrees and opens PRs.

• Knowtation as backend: Point the orchestrator (or its agents) at a shared Knowtation vault. CTO/coordinators/engineers use MCP if they run in a context where MCP is configured (e.g. Cursor), or CLI inside the Docker/worktree environment. They search/list/get-note for project and component context; optionally write phase summaries or decisions back into the vault.
• Vault as input: The brain dump or spec can live in the vault (e.g. a note or an export). The planner (or human) pulls from the vault to create the PlanSpec; then AgentCeption runs as usual.
• Bridge script: Use a small script (e.g. after a phase) that pipes the phase summary into knowtation write ... --stdin --frontmatter ... so the vault accumulates “what the org decided” and remains searchable.

No change to AgentCeption’s core flow; Knowtation is an optional context and memory layer that agents call via CLI or MCP.

🗂️ Muse and MuseHub (version control for this repo)

This codebase is tracked with Muse and pushed to MuseHub (staging). Git / GitHub remain for mirrors, PRs, Actions, and collaborators who are not on Muse yet.

Default workflow (Muse first)

When you change source in this repository and the goal is to record history on MuseHub, use the Muse CLI (not git commit):

1. muse status
2. muse code add <paths> or muse code add . (respects .museignore)
3. muse commit -m "type: summary"
4. muse push staging <branch> — staging remote is named staging (owner/slug: aaronrene/knowtation on staging.musehub.ai).

Say “Muse commit” when you mean muse commit; say “Git commit” when you mean git commit.

When to use Git instead

Use git add / git commit / git push when the task is explicitly GitHub-only — for example: open or update a GitHub PR, satisfy branch protection, trigger GitHub Actions, or pair with a reviewer who only uses Git. If the user says both, do Muse first for the canonical product snapshot, then mirror to Git per the user’s export / PR process.

If the user says only “commit” and does not specify, prefer Muse for this tree or ask once which remote they want updated.

Ignores and secrets

• .museignore controls what Muse snapshots. It is not auto-synced from .gitignore; keep them aligned for sensitive paths (config/local.yaml, data/, .tmp-transcribe-chunks/, etc.).
• Never commit config/local.yaml or other gitignored / museignored secret paths.

Vault vs repo

MCP/CLI orchestration above applies to vault access for agents. Private or personal vaults should live outside this repo (or only be referenced from ignored local config). Do not put private material under in-repo vault/ if the Muse/Git remote may be public.

📋 Summary

Spec and CLI/MCP semantics: docs/SPEC.md. Retrieval and token levers: docs/RETRIEVAL-AND-CLI-REFERENCE.md.