aaronrene/knowtation — blame/sha256:8/AGENT-ORCHESTRATION.md

1 files

1 commits

0 hotspots

0 🧊 dead

0 💥 blast risk

sha256:9 feat(calendar): hosted bridge/gateway route parity and timeline noteRec… · aaronrene · Jun 19, 2026

1	# 🤖 Knowtation and agent orchestration
2
3	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](./AGENT-INTEGRATION.md) first.
4
5	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](https://github.com/cgcardona/agentception).
6
7	On this page: Why both surfaces → Option A (MCP) → Option B (CLI) → Patterns → AgentCeption → Muse / MuseHub → Summary — scroll to the matching emoji heading.
8
9	---
10
11	## 🧭 Why both CLI and MCP?
12
13	\| Context \| Use \|
14	\|--------\|-----\|
15	\| MCP \| Agent runtimes that speak MCP (Cursor, Claude Desktop, or an orchestrator that exposes MCP to its agents). One config block; tools appear as `search`, `get_note`, `list_notes`, etc. \|
16	\| CLI \| Agents that run in containers, worktrees, or headless processes (e.g. engineer agents in [AgentCeption](https://github.com/cgcardona/agentception) worktrees). No MCP server in that process; they exec `knowtation` and parse `--json` output. \|
17
18	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.
19
20	---
21
22	## 🔌 Option A: MCP
23
24	1. Run the Knowtation MCP server (e.g. `knowtation mcp` or your package’s MCP entry point).
25	2. Configure your client (Cursor, Claude Desktop, or the orchestrator’s MCP client) to use it. Example (Cursor / Claude):
26
27	```json
28	{
29	"mcpServers": {
30	"knowtation": {
31	"command": "node",
32	"args": ["/path/to/knowtation/mcp/server.mjs"],
33	"env": { "KNOWTATION_VAULT_PATH": "/path/to/vault" }
34	}
35	}
36	}
37	```
38
39	3. Tools (same semantics as CLI): `search`, `get_note`, `list_notes`, `index`, `write`, `export`, `import`. Same filters and JSON shapes as in [SPEC §4](./SPEC.md).
40
41	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).
42
43	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](./AGENT-INTEGRATION.md) §2.
44
45	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](./RETRIEVAL-AND-CLI-REFERENCE.md).
46
47	---
48
49	## 💻 Option B: CLI in the agent environment
50
51	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).
52	2. Set env (and optional config):
53	- `KNOWTATION_VAULT_PATH` — path to the vault (required).
54	- Optionally `config/local.yaml` or other env (e.g. `QDRANT_URL`, `KNOWTATION_DATA_DIR`).
55	For read-only (search, list-notes, get-note), vault path and index are enough; for write/export, config may be needed (e.g. AIR).
56	3. Invoke from the agent:
57	- `knowtation search "auth flow" --project myapp --limit 3 --json`
58	- Parse JSON; then `knowtation get-note <path> --json` for the 1–2 paths you need.
59	- To write back: `knowtation write vault/projects/myapp/decisions/phase-1.md --stdin --frontmatter source=agentception date=2026-03-13` (body from stdin).
60
61	Same tiered retrieval pattern: use `--limit`, `--fields path`, `--count-only` to keep payloads small; then fetch full content only for selected paths.
62
63	---
64
65	## 🎯 Patterns
66
67	### 📖 Vault as knowledge backend (read)
68
69	- 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.
70	- 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.
71
72	### ✍️ Write-back (plans and summaries)
73
74	- 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).
75
76	### 💸 Token and cost
77
78	- 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.
79
80	---
81
82	## 🔗 AgentCeption specifically
83
84	For integration patterns with external orchestrators, see [AGENT-INTEGRATION.md](./AGENT-INTEGRATION.md) and [GETTING-STARTED.md](./GETTING-STARTED.md) (agents section).
85
86	[AgentCeption](https://github.com/cgcardona/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.
87
88	- 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.
89	- 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.
90	- 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.
91
92	No change to AgentCeption’s core flow; Knowtation is an optional context and memory layer that agents call via CLI or MCP.
93
94	---
95
96	## 🗂️ Muse and MuseHub (version control for this repo)
97
98	This codebase is tracked with [Muse](https://staging.musehub.ai/muse/getting-started) and pushed to MuseHub (staging). Git / GitHub remain for mirrors, PRs, Actions, and collaborators who are not on Muse yet.
99
100	### Default workflow (Muse first)
101
102	When you change source in this repository and the goal is to record history on MuseHub, use the Muse CLI (not `git commit`):
103
104	1. `muse status`
105	2. `muse code add <paths>` or `muse code add .` (respects `.museignore`)
106	3. `muse commit -m "type: summary"`
107	4. `muse push staging <branch>` — staging remote is named `staging` (owner/slug: `aaronrene/knowtation` on `staging.musehub.ai`).
108
109	Say “Muse commit” when you mean `muse commit`; say “Git commit” when you mean `git commit`.
110
111	### When to use Git instead
112
113	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.
114
115	If the user says only “commit” and does not specify, prefer Muse for this tree or ask once which remote they want updated.
116
117	### Ignores and secrets
118
119	- `.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.).
120	- Never commit `config/local.yaml` or other gitignored / museignored secret paths.
121
122	### Vault vs repo
123
124	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.
125
126	---
127
128	## 📋 Summary
129
130	\| Goal \| Use \|
131	\|------\|-----\|
132	\| Agents in Cursor / Claude (MCP) \| Option A: configure Knowtation MCP server; use tools search, get_note, list_notes, write, etc. \|
133	\| Agents in containers / worktrees (no MCP) \| Option B: install Knowtation CLI, set `KNOWTATION_VAULT_PATH`, run `knowtation ... --json` and parse output. \|
134	\| Write-back (plans, summaries) \| `knowtation write <path> --stdin --frontmatter source=... date=...`; optional script in `scripts/` to wrap this. \|
135	\| Keep token cost low \| Tiered retrieval: small limit, path/snippet only, then get-note for 1–2 paths. See [RETRIEVAL-AND-CLI-REFERENCE.md](./RETRIEVAL-AND-CLI-REFERENCE.md). \|
136	\| Record code changes for MuseHub (staging) \| `muse status` → `muse code add` → `muse commit` → `muse push staging <branch>`. See Muse / MuseHub section above. \|
137	\| GitHub-only work (PR, CI, mirror) \| `git` workflow as usual; coordinate with the human so Muse and Git do not diverge unintentionally. \|
138
139	Spec and CLI/MCP semantics: [docs/SPEC.md](./SPEC.md). Retrieval and token levers: [docs/RETRIEVAL-AND-CLI-REFERENCE.md](./RETRIEVAL-AND-CLI-REFERENCE.md).

AGENT-ORCHESTRATION.md file-level

`AGENT-ORCHESTRATION.md` file-level