Agent integration — one page

What this page is: Knowtation is your note vault + search index. This page explains the three ways software—including AI assistants—can talk to it: command line, MCP (a standard plug-in protocol many IDEs use), and Hub REST API. You do not need to understand all three; pick the one your tool supports.

Integrate Knowtation with any agent (OpenAI, Claude, LangChain, LlamaIndex, custom runners). Precise retrieval = fewer tokens: use filters and limits so agents fetch only what they need; see RETRIEVAL-AND-CLI-REFERENCE.md for token levers. Three entry points: CLI, MCP, Hub API.

Coming from Supabase? Start with Migrating from Supabase → Knowtation below, then wire agents using sections 2–3.

Migrating from Supabase → Knowtation

Many teams store AI memories, chat snippets, or app content in Supabase (Postgres). Knowtation’s model is Markdown files you own plus an optional search index and structured memory. This section is the supported path to move table rows into your vault and then use the same agent surfaces (CLI, MCP, Hub API) as everyone else.

What you can migrate

General Postgres → Markdown flows that are not row-per-memory (e.g. arbitrary schemas) are not a single CLI flag; use SQL views that expose the column names this importer expects, or export to CSV and use another importer where applicable (IMPORT-SOURCES.md).

Step 1 — Import table rows into the vault

Run the supabase-memory importer. From the repo root, knowtation resolves to cli/index.mjs via npm install / npx; you can also call node cli/index.mjs import … explicitly.

# Dry run first (no writes)
knowtation import supabase-memory '{"url":"'"$SUPABASE_URL"'","key":"'"$SUPABASE_SERVICE_ROLE_KEY"'","table":"memories"}' --dry-run --json

# Write notes under the vault (default: one .md per row)
knowtation import supabase-memory '{"url":"'"$SUPABASE_URL"'","key":"'"$SUPABASE_SERVICE_ROLE_KEY"'","table":"memories"}' --project migrated-from-supabase --json

You can pass a path to a JSON file instead of inline JSON (keep that file out of git; it contains secrets):

{
  "url": "https://YOUR_PROJECT.supabase.co",
  "key": "YOUR_SERVICE_ROLE_KEY",
  "table": "memories",
  "vault_notes": true
}

knowtation import supabase-memory ./config/supabase-import.secret.json --dry-run --json

Config fields

Row → note mapping (current importer behavior)

• Body: first of memory, content, text; otherwise JSON of the whole row.
• source_id: id or memory_id, else a generated id.
• date: created_at or updated_at (supports ISO strings or numeric epoch seconds).

If your columns use different names, create a SQL view in Supabase that aliases them to memory/content/text, id, and created_at, then set "table": "your_view_name".

Dependency: @supabase/supabase-js (see repo package.json). After import, run knowtation index / npm run index so search sees new notes.

Step 2 — Point agents at Knowtation (not at raw Supabase for vault reads)

After migration, agents should use MCP or Hub API for search / get-note-outline / get-note / write / propose so retrieval goes through Knowtation’s filters and token levers (§2 MCP, §3 Hub API).

You may still run a second MCP server (e.g. generic SQL or an internal Supabase tool) alongside Knowtation for legacy queries during transition — see Dual MCP (interop) under §2.

Step 3 — (Optional) Keep new memory events in Supabase

If you want semantic memory stored in Postgres while the vault stays canonical Markdown:

1. Run scripts/supabase-memory-migration.sql in the Supabase SQL editor (creates knowtation_memory_events + match_memory_events).
2. Set in config/local.yaml (or env):

memory:
  enabled: true
  provider: supabase
  supabase_url: https://YOUR_PROJECT.supabase.co
  supabase_key: YOUR_KEY   # prefer KNOWTATION_SUPABASE_URL / KNOWTATION_SUPABASE_KEY in env

Details and event model: MEMORY-AUGMENTATION-PLAN.md.

This is not required to use the vault or MCP; it is an optional backend for memory_* tools.

1. CLI (agents in containers / worktrees)

• Binary: knowtation (Node; run from repo or install globally).
• Env: KNOWTATION_VAULT_PATH (required), optional KNOWTATION_DATA_DIR, embedding keys (e.g. OPENAI_API_KEY).
• Config: config/local.yaml (vault_path, embedding, vector_store). No secrets in config; use env.

Read vault:

knowtation search "query" --limit 5 --json
knowtation search "exact phrase" --keyword --limit 5 --json
knowtation list-notes --project my-project --limit 20 --json
knowtation get-note-outline "path/to/note.md" --json
knowtation get-document-tree "path/to/note.md" --json
knowtation get-metadata-facets "path/to/note.md" --json
knowtation get-note "path/to/note.md" --json

Write vault:

knowtation write "inbox/capture.md" --body "content" --json

Propose (review-before-commit via Hub):

knowtation propose "path/to/note.md" --hub https://hub.example.com --intent "Add summary" --json

Token levers: --limit, --fields path or path+snippet, --count-only, get-note-outline --json, get-document-tree --json, or get-metadata-facets --json before full note reads, --body-only, --frontmatter-only, --snippet-chars, --keyword / --match for literal text search (no index required). See RETRIEVAL-AND-CLI-REFERENCE.md.

JSON shapes: CLI-JSON-SCHEMA.md and SPEC.md §4.2.

2. MCP (Cursor, Claude Code, etc.)

• Start: knowtation mcp (stdio transport) or MCP_TRANSPORT=http knowtation mcp (Streamable HTTP, default port 3334).
• Tools: Same operations as CLI — search, get-note-outline, get-document-tree, get-metadata-facets, get-note, list-notes, index, write, export, import where the transport phase has shipped. Use get-note-outline / get_note_outline or get-document-tree / get_document_tree to inspect heading structure before loading a full note body; use get-metadata-facets / get_metadata_facets to inspect bounded metadata hints without note body or full frontmatter. get_document_tree and get_metadata_facets are available on self-hosted MCP and hosted MCP as body-free read tools. Hosted: admins also get import_url (JSON to POST /api/v1/import-url, same as Hub “Import from URL”) and import with file_base64 + filename + source_type (same bridge contract as Hub POST /api/v1/import, including pdf and docx). Multiple files in one agent run: use import repeatedly (one base64 file per call); the Hub can batch the same work with 4B (sequential HTTP) and 4A₂ (in-browser ZIP) — there is no separate import_batch tool. Self-hosted MCP: use import with source_type: "url" and input = https URL; optional url_mode: auto | bookmark | extract. Same filters and JSON shapes where applicable. The search tool accepts mode: semantic (default) or keyword plus optional match (phrase | all_terms) for keyword mode, aligned with POST /api/v1/search. The search tool also supports rerank (Phase F4) — when the client supports sampling, results are reranked by the client LLM for better relevance.
• Enrich (Phase F2): The enrich tool auto-categorizes a note: suggests project slug, tags, and title via sampling (client LLM) or server-side LLM fallback. Use apply: true to write suggestions to frontmatter.
• Index enrichment (Phase F3): The index tool accepts enrich: true to generate per-note AI summaries after indexing (opt-in, expensive). Summaries are stored in ai_summary frontmatter.
• Scope hint: On connect, the server sends MCP instructions naming your vault and data directory as file:// URIs (Phase G). Add those folders as workspace roots in your MCP host when supported so the assistant's context matches Knowtation.
• Bootstrap resource (prime): After connect, resources/read knowtation://prime (self-hosted MCP) for a compact JSON bootstrap: redacted config, suggested follow-on resource URIs (knowtation://config, knowtation://vault/, …), and pointers to docs/TOKEN-SAVINGS.md / this file. On hosted MCP, use knowtation://hosted/prime for the same schema class plus mcp_prompts_registered_for_role for the current session (no JWT in the resource body). In the Hub, Settings → Integrations → Copy prime copies a small JSON blob (mcp_read_resource_uri, gateway base URL, vault id) with a one-line instructions pointer to this file; secrets come only from Copy Hub URL, token & vault.
• Sampling: Tools that benefit from LLM intelligence (summarize, enrich, search rerank) delegate to the host's LLM when the client supports sampling; otherwise they use Ollama/OpenAI on the server. Prompts (search-and-synthesize, project-summary, knowledge-gap) may include a sampling-based assistant prefill. Code: mcp/sampling.mjs and tool modules under mcp/tools/.
• Use case: When the agent runtime speaks MCP; no need to shell out to CLI.

Prompt catalog and copy-paste starters: A single reference for MCP prompt names, “paste in any LLM” instruction blocks, and high-value CLI lines (search, list, propose, memory consolidate) — including wiki / synthesis / research patterns — is POPULAR-PROMPTS-AND-STARTERS.md. The Hub in-app help (How to use → Knowledge & agents) summarizes this and links to the same file on GitHub.

See AGENT-ORCHESTRATION.md.

Hosted MCP (Phase D2/D3)

Hub web UI vs hosted MCP: they are separate programs; align them via shared bridge/canister APIs. See docs/PARITY-MATRIX-HOSTED.md.

Remote MCP clients (Claude Desktop, Cursor, custom agents) can connect to the Hub's MCP endpoint:

• Endpoint: POST /mcp on the Hub gateway (e.g. https://hub.example.com/mcp).
• Auth: OAuth 2.1 (Phase D3) via dynamic client registration + PKCE flow. Discovery: GET /.well-known/oauth-authorization-server. Or pass a Hub JWT as Authorization: Bearer <token>.
• Session management: Each authenticated user gets an isolated MCP session with role-based tool access (viewer: read-only; editor and evaluator: same write-class tools, including direct write and hub_create_proposal when the gateway supplies its public API base URL; admin: + index/export/import). hub_create_proposal calls POST /api/v1/proposals on the gateway with your JWT and X-Vault-Id (see HUB-API.md §3.4). Idle TTL defaults to 8 hours (was 30 minutes) so remote clients (Cursor) keep tools/resources across breaks; override with MCP_SESSION_TTL_MS (milliseconds, clamped 5m–24h). MCP_MAX_SESSIONS_PER_USER caps concurrent sessions per user (default 8, clamped 2–20; oldest evicted when exceeded).
• Prompts (Track B1 + B2 + B3): Use prompts/list after connect — the server only registers prompts your role can use. Full inventory (hosted): daily-brief, search-and-synthesize, project-summary, temporal-summary, content-plan, meeting-notes, knowledge-gap, causal-chain, extract-entities, write-from-capture (minimum editor — hidden for viewers), memory-context, memory-informed-search, resume-session. Same IDs exist on self-hosted MCP (mcp/prompts/register.mjs). For a session-accurate subset (after auth), read knowtation://hosted/prime on hosted MCP. Parity notes: PARITY-MATRIX-HOSTED.md § Hosted MCP prompts. maybeAppendSamplingPrefill may run on knowledge-gap and several B1 prompts; without sampling, message lists still return without a draft assistant turn.
• Summarize arbitrary pasted blob (hosted): Evaluated and not shipped — see MCP-BLOB-SUMMARIZE-EVALUATION.md. Use summarize on a vault path, the meeting-notes prompt for pasted transcripts, or local summarization for terminal output (per TOKEN-SAVINGS.md).
• Rate limiting: 60 requests/min per user on the /mcp endpoint.
• Vault isolation: Each session is scoped to the user's allowed vaults via getHostedAccessContext().
• Canister user parity: Session creation uses effective_canister_user_id from that hosted-context response as X-User-Id on all MCP → canister calls (same rule as the Hub gateway’s GET /api/v1/notes proxy). Without this, delegated/workspace users could see many notes in the Hub but only their actor partition over MCP.
• Files: hub/gateway/mcp-proxy.mjs, hub/gateway/mcp-hosted-server.mjs, hub/gateway/mcp-tool-acl.mjs, hub/gateway/mcp-oauth-provider.mjs.
• Netlify / serverless gateway: When the gateway process has NETLIFY set, the repo does not mount the full stateful /mcp session router on that host—it answers /mcp with 503 and MCP_NETLIFY_UNSUPPORTED (see hub/gateway/server.mjs). Cursor will then show errors or no tools for a remote url ending in /mcp. Workarounds: use Hub REST with the same copied JWT (POST /api/v1/search, etc.), or point knowtation-hosted at a persistent gateway deployment where /mcp is actually mounted (Node on a VPS/PM2, etc.—not the Netlify-only entrypoint).
• EC2 / VPS deploy (clone, git pull, npm ci, PM2): Operator runbook for the MCP gateway lives in hub/gateway/README.md (deploy + verification).
• Concrete example: a Hub base URL like https://knowtation-gateway.netlify.app is this pattern. Do not point Cursor’s knowtation-hosted (url … /mcp) at that host—it will flap red / green with zero tools or log fetch failed / transient errors. Keep knowtation (stdio + local vault) for Cursor in the repo; use REST + copied JWT (or Abacus HTTP actions) for the hosted vault until a non-Netlify MCP gateway URL exists.

Cursor + hosted Knowtation MCP (step-by-step)

What you are doing: telling Cursor to open a remote MCP connection to your gateway’s /mcp URL, using the same token and vault id you copied from Settings → Integrations → Hub API (not the local node … mcp + disk vault path).

Proposals: On a persistent gateway where /mcp is mounted, editor, evaluator, and admin sessions can use hub_create_proposal (same POST /api/v1/proposals contract as the Hub UI). Editor and evaluator are separate roles in hosted-context; both receive the tool. Viewers do not.

Where to put it in Cursor

1. Option A — Settings UI: Cursor → Settings (Cmd + , on macOS, Ctrl + , on Windows/Linux) → search MCP → open MCP / Tools & MCP (wording varies by Cursor version) → Add server or Edit in mcp.json. Cursor opens or creates the JSON file it uses for MCP.

2. Option B — File directly (same result): edit one of:

   • All projects: ~/.cursor/mcp.json on your machine
   • This repo only: .cursor/mcp.json at the git root of the project you opened in Cursor

   Official overview: Model Context Protocol (MCP) — Cursor Docs.

What to paste (shape only — use your real values from the Hub copy button; do not commit secrets)

The Hub copy gives KNOWTATION_HUB_URL (the REST gateway, e.g. Netlify). When your deployment sets HUB_MCP_PUBLIC_URL in web/hub/config.js, the same paste includes KNOWTATION_MCP_URL, which is the full URL to use for remote MCP (e.g. https://mcp.example.com/mcp). Do not assume KNOWTATION_HUB_URL + /mcp works for every deployment: serverless gateways return 503 for /mcp (see §2). When KNOWTATION_MCP_URL is absent, self-hosted Node Hub on one process often uses {KNOWTATION_HUB_URL}/mcp.

The Authorization header value must be the full Bearer <token> string. The variable KNOWTATION_HUB_TOKEN from the copy block is only the JWT; in JSON headers, prefix with Bearer (or use ${env:KNOWTATION_HUB_TOKEN} after Bearer as below).

{
  "mcpServers": {
    "knowtation-hosted": {
      "url": "https://YOUR-MCP-HOST/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_HUB_TOKEN_FROM_COPY_BUTTON",
        "X-Vault-Id": "YOUR_VAULT_ID_FROM_COPY_BUTTON"
      }
    }
  }
}

Safer pattern (recommended): put the token in a shell / OS env var and reference it so the JSON file does not contain the raw JWT:

{
  "mcpServers": {
    "knowtation-hosted": {
      "url": "https://YOUR-MCP-HOST/mcp",
      "headers": {
        "Authorization": "Bearer ${env:KNOWTATION_HUB_TOKEN}",
        "X-Vault-Id": "${env:KNOWTATION_HUB_VAULT_ID}"
      }
    }
  }
}

Then export KNOWTATION_HUB_TOKEN and KNOWTATION_HUB_VAULT_ID in the environment from which you launch Cursor (or use your OS secret store if your Cursor build documents another interpolation syntax).

After saving

1. Reload MCP (Cursor usually has a refresh on the MCP screen, or restart Cursor).
2. Open View → Output (or Output panel) → choose MCP / Cursor MCP in the dropdown if logs do not appear — see Cursor MCP docs for troubleshooting.
3. In chat, try a tiny vault action (e.g. ask the agent to list_notes or search with a low limit).

If Cursor ignores headers: some MCP hosts prefer OAuth when the server advertises discovery (GET /.well-known/oauth-authorization-server). Your gateway supports OAuth for MCP (see Hosted MCP (Phase D2/D3) above). In that case use Cursor’s OAuth / Sign in flow for that MCP server instead of static Bearer headers, if the UI offers it.

Dual MCP (interop): Knowtation + another server

Cursor, Claude Desktop, and other MCP hosts can load multiple MCP servers in one app. A common pattern during or after a Supabase → Knowtation migration:

• Knowtation MCP — vault search, notes, proposals, memory tools, imports (canonical knowledge).
• A second MCP — legacy Postgres/Supabase dashboards, internal tools, or another “second brain” product.

Cursor (.cursor/mcp.json): use a top-level mcpServers object with two entries (names are arbitrary):

{
  "mcpServers": {
    "knowtation": {
      "command": "node",
      "args": ["/ABS/PATH/TO/knowtation/cli/index.mjs", "mcp"],
      "env": {
        "KNOWTATION_VAULT_PATH": "/ABS/PATH/TO/your-vault"
      }
    },
    "other": {
      "command": "npx",
      "args": ["-y", "some-other-mcp-package"]
    }
  }
}

Claude Desktop: merge a second server into mcpServers in claude_desktop_config.json the same way (OS-specific path — see AGENT-ORCHESTRATION.md).

Operational tips

• Give servers distinct names so the model can choose knowtation-scoped tools vs the other package.
• Secrets: put Supabase service role keys in env vars or host-specific secret stores, not in committed JSON.
• Hosted Knowtation MCP uses OAuth or Hub JWT against your gateway URL instead of a local node … mcp command — same dual-server idea: one config block for Knowtation hosted, one for the other tool.

3. Hub API (REST)

Where “Copy Hub URL, token & vault” is used

Local CLI uses KNOWTATION_VAULT_PATH to markdown on disk—not the Hub token. See §1. The copy button adds a blank line after the env vars, then two # lines (doc link + curl header reminder); full examples stay in this page.

• Base URL: e.g. https://hub.example.com (REST paths are under /api/v1/...).
• Auth: JWT via OAuth (Google/GitHub). Header on every protected request: Authorization: Bearer <token>.
• Vault: For vault-scoped routes, send header X-Vault-Id (e.g. default or the id shown in the Hub header). Match the vault you intend to act on.
• Copy or move a note to another vault: POST /api/v1/notes/copy with JSON from_vault_id, to_vault_id, path, and optional delete_source (move). Same JWT and hosted allowlist rules as other writes; Hub UI exposes this as Copy to vault… on a note. See HUB-API.md §3.3.
• Obtain URL + token + vault (no DevTools): In the Hub, open Settings → Integrations → Hub API and click Copy Hub URL, token & vault. That pastes KNOWTATION_HUB_URL, KNOWTATION_HUB_TOKEN, and KNOWTATION_HUB_VAULT_ID, and, when the deployment sets window.HUB_MCP_PUBLIC_URL in web/hub/config.js, also KNOWTATION_MCP_URL, then a blank line, then two short # lines: a link to this document, and a reminder of the three headers to add to curl (full examples below). KNOWTATION_HUB_TOKEN is the raw JWT; always compose Authorization: Bearer <token> in HTTP. Treat the paste as a secret. The token is time-limited (default 24 hours on the hosted gateway unless your deployment sets HUB_JWT_EXPIRY); on 401, copy fresh lines again—your browser session and the API block are separate.
• Hub REST vs remote MCP URL: Use KNOWTATION_HUB_URL for /api/v1/.... For HTTP MCP clients, set url to KNOWTATION_MCP_URL when the paste includes it (see §2 for Netlify vs persistent /mcp). For large or scripted writes, REST POST /api/v1/notes is often the most reliable path; MCP is for interactive tools.
• Not the same button: Settings → Agents → Copy embedding env copies only embedding-related lines (e.g. Ollama URL / model comment) so local indexers match the Hub—it does not copy the Hub JWT.

Example curl (create proposal): .env alone does not attach headers; you must pass the bearer token explicitly.

curl -sS -X POST "${KNOWTATION_HUB_URL}/api/v1/proposals" \
  -H "Authorization: Bearer ${KNOWTATION_HUB_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-Vault-Id: ${KNOWTATION_HUB_VAULT_ID:-default}" \
  -d '{"path":"inbox/example.md","body":"# Proposed content","intent":"optional"}'

Endpoints (same contract as CLI where applicable):

Machine-readable spec: openapi.yaml. Use it for OpenAPI-based tool definitions (e.g. OpenAI function calling, LangChain tools).

Human-readable contract: HUB-API.md.

4. Proposals (review-before-commit)

• Create: CLI knowtation propose, Hub POST /api/v1/proposals, or the Hub UI (Suggested → New proposal, or open a note and Propose change). Agents use the same API contract.
• Review: In Hub UI: Suggested = proposals to review; Discarded = rejected; Activity = timeline.
• Apply: Approve in Hub (or API POST /proposals/:id/approve); content is written to vault.

Metadata you can rely on: Proposals support intent (why the change exists), base_state_id (optimistic concurrency against a known vault snapshot), and optional external_ref (stable id in another system after approve). Same fields in REST and MCP; full shapes in HUB-API.md and PROPOSAL-LIFECYCLE.md.

Optional external lineage (Muse)

Not required for sign-in, search, or normal proposal workflows. The vault and Hub stay canonical.

Some teams run Muse alongside Knowtation for structural / Git-replayed history (read-only lineage queries). If you do, keep Muse on operator-controlled credentials—never on an unauthenticated public URL for end users. When you approve a proposal, you may set external_ref to a Muse commit or branch id so the approved change is traceable across systems.

A full Knowtation domain plugin inside Muse (variations stored in Muse’s DAG, merge engine owned by Muse) is not a supported product path unless a concrete partner or deployment needs it. The thin bridge and operator flow are documented in MUSE-THIN-BRIDGE.md and in §4 of this file.

5. Capture (ingest into vault)

• Hub: POST /api/v1/capture with { "body": "...", "source_id?", "source?", "project?", "tags?" }. Optional X-Webhook-Secret if configured.
• Standalone webhook: Use scripts/capture-webhook.mjs or adapters (Slack, Discord). See MESSAGING-INTEGRATION.md and CAPTURE-CONTRACT.md.

6. Function-calling / tool definitions

• OpenAPI: Use docs/openapi.yaml to generate client or tool schemas for Hub endpoints.
• CLI: Use CLI-JSON-SCHEMA.md for request/response shapes of search, list-notes, get-note, write, propose.
• MCP: MCP server exposes tools with the same semantics; schema can be derived from CLI/SPEC.

References