Your notes, searchable. One place for you and your agents.
Portable vault, semantic search, and a single place for proposals—so you and your agents stay in context.
Sign in with Google or GitHub above to open your vault. Your first sign-in is your account—no separate sign-up.
— setup and how agents use your vault.
OAuth is not configured yet. The Hub only accepts login through Google or GitHub. Add credentials to your project .env, then restart the Hub.
http://localhost:3333/api/v1/auth/callback/google → set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET.http://localhost:3333/api/v1/auth/callback/github → set GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET.See hub/README.md (section “Log in (OAuth)”).
If you're on a hosted Knowtation site, the provider has already set this up—just sign in above.
Proposal timeline: created → approved/discarded. Proposals are created by the CLI (knowtation propose --hub ...) or by an agent; you review them here.
Proposals needing your review. They are created by the CLI or an agent (not by a button in the Hub). Click one, then Approve (writes to vault) or Discard.
Proposals you (or someone) discarded. They were not applied to the vault. You can still open them to read.
Saves to inbox with today’s date.
Temporal and hierarchical (optional):
Backup connects your vault to a Git repo (e.g. GitHub) so your notes are versioned and safe. Follow the checklist and configure steps below.
Get from zero to using the Hub and (optionally) backing up. Complete each step; optional steps can be skipped.
Current vault and backup state. To change where the vault lives or which Git repo is used, use Configure backup below (admins only).
—
Admins add this to data/hub_roles.json to assign you a role (viewer / editor / admin). It is provider:id (e.g. github:12345), not your email or username.
To turn on Git backup, follow these steps:
https://github.com/you/repo-name.git) so Connect GitHub can push; private is recommended for notes../vault, run once from project root: cd vault && git init && git add -A && git commit -m "Initial vault". If you use a different folder that is already a Git repo, skip this.Only admins can save setup. Your role is shown under Status above.
Changes are saved to data/hub_setup.yaml and applied immediately. Vault path can be absolute or relative to the project root.
Team lets you invite others and set roles (viewer, editor, admin). Only admins see this tab. Use User ID or invite links to connect teammates.
Add a user by their User ID (e.g. github:12345). They find it in their own Settings → Backup under "Your user ID" — they copy it and send it to you.
Create a link to invite someone. They sign in with Google or GitHub and get the role you choose. Link expires in 7 days. Share the link; they open it, sign in, and are added.
Integrations connect external tools to your vault: capture (Slack, Discord, etc.), imports (ChatGPT, Notion, etc.), and agents (AgentCeption). Each block below explains how to connect.
Send messages or events into the vault as notes. When the Hub is running, the capture URL is POST /api/v1/capture (e.g. http://localhost:3333/api/v1/capture). Optional: set CAPTURE_WEBHOOK_SECRET in the server and send header X-Webhook-Secret.
Run an adapter (or Zapier/n8n) that converts platform events to the capture format, then POSTs to the Hub. Body format: {"body": "text", "source": "slack", "project": "optional"}. Full format: How to use → Step 4.
node scripts/capture-slack-adapter.mjs --port 3132. Set env CAPTURE_URL (Hub URL), SLACK_SIGNING_SECRET, and optionally CAPTURE_WEBHOOK_SECRET. Point Slack Events API at the adapter URL.node scripts/capture-discord-adapter.mjs --port 3133. Set CAPTURE_URL and CAPTURE_WEBHOOK_SECRET. Point your Discord webhook or bot at the adapter.node scripts/capture-telegram-adapter.mjs --port 3134. Set CAPTURE_URL and CAPTURE_WEBHOOK_SECRET. Or any bot that POSTs to /api/v1/capture with {"body": "...", "source": "telegram"}.https://your-hub/api/v1/capture with {"body": "message text", "source": "whatsapp"}. See docs/MESSAGING-INTEGRATION.md.Bring data into the vault from exports and platforms using the CLI.
From a terminal: knowtation import <source-type> <input>. Use --project, --output-dir, --tags as needed. Source types:
chatgpt-export, claude-export, mem0-export — point at exported folder or file.notion, jira-export, notebooklm, gdrive, linear-export — use API keys or export files as required.markdown, mif, audio, video — folders or files.Full list and options: How to use (Import data) or docs/IMPORT-SOURCES.md.
Use Knowtation as the shared context for planner and engineer agents. One vault path for the whole setup.
Set the same vault path in the planner and every engineer. Copy the env snippet below into each environment.
KNOWTATION_VAULT_PATH=/path/to/shared/vault
Appearance controls how the Hub looks in your browser. Changes are saved locally (no server config).
Switch between night and day. Saved in your browser; applies as soon as you click.
Choose an accent for links, buttons, and highlights. Pick a preset or use the custom color picker. Saved in your browser.
Agents shows the embedding config the Hub uses. Use the same config in your orchestrator or agent runtime so search behaves the same. Copy the env block below into the agent environment.
Current embedding provider and model. Read-only here; edit config/local.yaml to change. Match this in agents so they use the same embeddings.
In your orchestrator or agent config: set KNOWTATION_HUB_URL and KNOWTATION_HUB_TOKEN (get the token after logging in to the Hub). Use "Copy env for orchestrators" below to copy a full env snippet. For AgentCeption and MCP, see Integrations → AgentCeption and How to use.
Follow the steps below in order. Each step unlocks the next. Diagrams show how data and agents connect.
What this does: Tells Knowtation where your notes live so the Hub and CLI can read and write them.
~/knowtation-vault).config/local.yaml set vault_path: ./vault (or a path to that folder). Or set the env var KNOWTATION_VAULT_PATH.vault_path: ./vault data_dir: data
What this does: Starts the web app you’re using now so you can browse, search, and approve changes.
npm run hub.http://localhost:3333 (or the port you set with HUB_PORT).$ npm run hub Knowtation Hub listening on http://localhost:3333
What this does: Proves who you are so the Hub can show your vault and let you approve proposals.
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET (and callback http://localhost:3333/api/v1/auth/callback/google) or the same for GitHub in your .env, then restart the Hub.What this does: Brings in notes from Slack, files, ChatGPT, or other tools so they appear in the Hub and can be searched.
Capture (messages → vault): Slack, Discord, Telegram, WhatsApp (via webhook or Zapier/n8n). Import (exports → vault): ChatGPT, Claude, Mem0, Notion, Jira, NotebookLM, Google Drive, Linear, and generic Markdown/files. Expand each source below for setup steps.
Hub capture (easiest): POST to /api/v1/capture with JSON {"body": "your text", "source": "slack", "project": "myproject"}. Optional: CAPTURE_WEBHOOK_SECRET and header X-Webhook-Secret. Per-service steps below.
Run node scripts/capture-slack-adapter.mjs --port 3132. Set CAPTURE_URL (default Hub), SLACK_SIGNING_SECRET, and optionally CAPTURE_WEBHOOK_SECRET. Point Slack Events API at the adapter URL; it responds to url_verification and forwards message events to capture. Or use Zapier/n8n: Slack trigger → HTTP POST to /api/v1/capture.
Run node scripts/capture-discord-adapter.mjs --port 3133. POST with JSON { "content": "message text", "id?", "channel_id?", "project?", "tags?" }. Set CAPTURE_URL and CAPTURE_WEBHOOK_SECRET. Or Zapier/n8n: Discord trigger → HTTP POST to Hub capture.
Run node scripts/capture-telegram-adapter.mjs --port 3134. Accepts Telegram Bot API webhook payloads or simplified { "body": "message text", "source_id?", "project?", "tags?" }. Set CAPTURE_URL and CAPTURE_WEBHOOK_SECRET. Or any bot that POSTs to /api/v1/capture with source: telegram.
No dedicated adapter. Use Zapier/n8n: WhatsApp trigger → HTTP POST to https://your-hub.example.com/api/v1/capture with {"body": "<message text>", "source": "whatsapp", "source_id": "<id>"}. Or run a small webhook that normalizes WhatsApp payloads and POSTs to capture. See Settings → Integrations and docs/MESSAGING-INTEGRATION.md.
Export from ChatGPT: Settings → Data Controls → Export Data. Extract the ZIP; then knowtation import chatgpt-export /path/to/extracted-folder --output-dir imports/chatgpt --tags chatgpt. Folder must contain conversations.json.
Export chat history from Claude (Settings → Privacy → Export). If you have a folder of .md or JSON from a third-party exporter: knowtation import claude-export /path/to/folder --project myproject.
knowtation import mem0-export /path/to/mem0-export.json --project memories. Each memory becomes a vault note with source: mem0.
CLI: knowtation import <source-type> <input> with notion, jira-export, notebooklm, gdrive, linear-export. See docs/IMPORT-SOURCES.md and Settings → Integrations for full list and options (--project, --output-dir, --tags).
Files / generic: scripts/capture-file.mjs for stdin or files. Or drop Markdown into vault/inbox/ or vault/imports/ with frontmatter source, date, project, tags. knowtation import markdown <path> for folders.
What this does: You browse and filter notes here; agents and LLMs can read and propose changes via the API or CLI, and you approve in the Hub.
Vault and backup: You have one vault (your notes) and optionally one GitHub repo to back it up (Settings → Backup). Projects are folders or tags inside the vault so you and agents can filter—they are not separate GitHub repos. Agents read and write the vault (CLI/MCP/API); they do not push to GitHub. You approve their changes (proposals) in the Hub and you control backup (Back up now or auto-sync).
Projects and filters: Organize notes by project (e.g. vault/projects/myapp/ or frontmatter project: myapp) and tags. Agents use --project and --tag to read only what’s relevant. See the Knowledge & agents tab above for the full picture.
Proposals are not created by a button in the Hub. They are created by the CLI or by an agent/LLM calling the Hub API. The Hub is where you review them.
knowtation propose --hub http://localhost:3333 --path inbox/idea.md --body "..." (with KNOWTATION_HUB_TOKEN set), or have an agent send POST /api/v1/proposals with the same kind of data. The proposal then appears in the Hub.There is no "Add proposal" button in the Hub by design: proposals are created by tools and agents. You use the Hub to approve or discard them before anything is written to the vault.
project: slug and tags: [a, b] in frontmatter, or live under projects/slug/. Use the project, tag, and folder dropdowns, then Apply filters. Quick chips (e.g. project:myproject, folder:inbox) jump to a view. Save a view with Save view as and click a preset pill later.knowtation index from the CLI.Give your agent or LLM a way to talk to Knowtation: either the Hub API (with a JWT) or the CLI. Agents can list notes, search, and create proposals; you review and approve in the Hub.
Open CLAW can call tools. Configure it with the Knowtation Hub as a tool endpoint: set the Hub base URL and a JWT (from this Hub after login). It can then call GET /api/v1/notes, POST /api/v1/search, and POST /api/v1/proposals. For writes, use proposals and approve them here.
KNOWTATION_HUB_URL=http://localhost:3333 KNOWTATION_HUB_TOKEN=<paste JWT from Hub after login>
Abacus agents can use the Knowtation CLI or Hub API. Point Abacus at the Hub URL and token so it can search and read notes; use knowtation propose --hub <url> (or the API) to create proposals. You review in the Hub's Suggested tab and approve or discard.
# In your Abacus tool config, add Knowtation Hub: # - Hub URL + KNOWTATION_HUB_TOKEN for API calls # - Or shell tool: knowtation search "query" --json
Use the Knowtation CLI from a wrapper or script the LLM can trigger: knowtation search "..." --json, knowtation list-notes --limit 20 --json. For write flows, use knowtation propose --hub http://localhost:3333 with a token; the LLM's proposed change becomes a proposal you approve in the Hub.
# CLI (read-only, no Hub needed): knowtation search "meeting notes" --json knowtation list-notes --project myproject --limit 10 --json # With Hub (propose + review): export KNOWTATION_HUB_TOKEN=<JWT> knowtation propose --hub http://localhost:3333 --path inbox/idea.md --body "..."
Knowtation is the shared vault and two-step fetch layer for AgentCeption’s planner and engineer agents. One vault path for the whole org; agents search with --limit and --fields path, then get-note only for the paths that matter. Phase summaries write back to the vault.
Prerequisites: AgentCeption repo/setup; a folder for the shared vault (e.g. inside the AgentCeption project or a dedicated repo).
KNOWTATION_VAULT_PATH to that path for the planner and for every engineer agent (same path). Optionally set vault_path in config/local.yaml.knowtation mcp or add the Knowtation MCP server to the Cursor/Claude config used by the planner. Tools: search, get_note, list_notes, write.KNOWTATION_VAULT_PATH. Use knowtation search "..." --project <project> --limit 3 --fields path --json, then knowtation get-note <path> --json for the 1–2 paths that matter.echo "Phase 1: ..." | knowtation write vault/projects/<project>/decisions/phase-1.md --stdin --frontmatter source=agentception project=<project> or use scripts/write-to-vault.sh with --source agentception --project <project>.knowtation index after writes so new content is searchable.Optional — Hub and proposals: If the orchestrator uses the Hub, set KNOWTATION_HUB_URL and KNOWTATION_HUB_TOKEN; agents can create proposals for human review before commit.
Full reference: docs/AGENTCEPTION-HACKATHON-SUBMISSION.md in the repo.
MCP (e.g. Cursor): If your environment supports MCP, enable the Knowtation MCP server to search and read notes. For writes, combine with the Hub and proposals as above.
What this does: Keeps your vault in a Git repo and syncs to GitHub (or another remote) for backup and version history. This is strongly recommended so your knowledge is safe and portable.
Your vault can live in a Git repository and sync with a remote like GitHub. That gives you:
When you create the repo on GitHub, use these settings so backup works smoothly:
https://github.com/username/repo-name.git. HTTPS is required if you use Connect GitHub in Settings (token-based push); SSH URLs work only if you use a deploy key or SSH agent.git init?The folder that holds your vault (whatever you set as Vault path, e.g. ./vault) must be the root of a Git repository for backup to work. Knowtation does not create that repo for you.
If you use the built‑in vault folder (e.g. ./vault), it is just a normal folder — not a Git repo. Run a one-time init and first commit inside the vault folder.
cd vault && git init && git add -A && git commit -m "Initial vault"
If your vault path is different, replace vault with that folder name. Do not run git init from the project root — that would make the whole Knowtation project the repo; backup is only for the vault folder.
If you point Vault path at a folder that is already a Git repository (e.g. an existing Obsidian vault or notes repo), you do not need to run git init.
git push -u origin main (or master if that's your default branch).Or edit config/local.yaml with vault.git.enabled: true and vault.git.remote: https://github.com/you/your-repo.git. Then run Back up now in Settings, or knowtation vault sync from the CLI.
Connect GitHub (push without a deploy key): uses the same GitHub OAuth App; add callback URL …/api/v1/auth/callback/github-connect in your app settings. Optional: vault.git.auto_commit and vault.git.auto_push for automatic sync. See PROVENANCE-AND-GIT.md.
Proposals are created by the CLI (knowtation propose --hub <url>) or by an agent/LLM calling POST /api/v1/proposals. There is no "Add proposal" button in the Hub by design—you use the Hub to approve or discard what tools and agents suggest.
Settings → Backup: set vault path and Git remote URL, click Save setup, then Connect GitHub (so the Hub can push with your token), then Back up now. Or run knowtation vault sync from the CLI. The vault folder must be a Git repo (run git init inside the vault folder once if needed).
Today, one Hub = one vault. Everyone you invite sees the entire vault (viewers read-only, editors can edit). Project and folder filters in the Hub only narrow the list; they do not hide notes from teammates.
To keep personal and shared separate: Use two vaults and two Hub instances—e.g. one Hub for a shared team vault (invite people there) and a separate Hub or local-only CLI for your personal vault. No code change needed; run each Hub with its own KNOWTATION_VAULT_PATH and port.
Scoped access (e.g. "teammate only sees project X") and multi-vault in a single Hub are not implemented yet. See docs/MULTI-VAULT-AND-SCOPED-ACCESS.md for details and options.
Log in to the Hub; the app can provide a token for API access (see Settings → Agents or Integrations for "Copy env" or token instructions). Use KNOWTATION_HUB_URL and KNOWTATION_HUB_TOKEN in your agent or orchestrator config.
How your vault feeds agents and how agents interact with Knowtation. One vault, one backup repo; you control what gets into the vault and what gets backed up to GitHub.
Every note can carry optional frontmatter. None of this is auto-extracted by an LLM—you or an agent add it when creating or editing a note (Hub + New note full form, CLI, or API). When present, the index and search use it.
| Field | Used for |
|---|---|
date, updated | Time-bounded search: Hub filters Since/Until; CLI --since, --until. Scope results to a date range. |
project | Project slug. Filter by project in Hub and CLI (--project). |
tags | Tags. Filter in Hub and CLI (--tag). |
folder (path) | Inferred from path (e.g. inbox/, projects/…). Filter in Hub and CLI (--folder). |
causal_chain_id | Causal chains: Groups notes in the same decision/event chain. CLI --chain. Enables "what led to this?" |
entity | Entity labels (person, concept). CLI --entity. Relational queries across time. |
episode_id | Hierarchical memory: Groups notes into an episode/session. CLI --episode. Project → episode → note → chunk. |
follows | Vault path(s) this note follows (causal or sequential). Links notes in a chain. |
summarizes, summarizes_range, state_snapshot | State compression: summary notes for a range or snapshot at a point in time. Optional. |
In the Hub: The + New note full form lets you set date, project, tags, causal chain, entity, episode, and follows. Search bar has Since and Until for time. Agents and humans can set the same fields via CLI or API.
Add notes to your vault the usual way (Hub + New note, capture, import). Use project (folder vault/projects/<slug>/ or frontmatter project: slug) and tags so agents can filter. Optionally add causal_chain_id, entity, episode_id, or follows for temporal and hierarchical retrieval. Agents then read only what's relevant.
Agents use the same vault via CLI, MCP, or Hub API: knowtation search "query" --project myapp --limit 5 --json, knowtation list-notes --project myapp --json, then get-note for full content. See RETRIEVAL-AND-CLI-REFERENCE.md and INTENTION-AND-TEMPORAL.md in the repo. Filters: --project, --tag, --folder, --since, --until, --chain, --entity, --episode.
Agents do not push to GitHub. They read and write the vault. For writes, they can create proposals (CLI knowtation propose --hub <url> or API POST /api/v1/proposals). You approve or discard in the Hub (Suggested / Discarded). You control backup: Settings → Back up now or auto-sync to your one GitHub repo.
Point any orchestrator at this vault and the same project slugs. Use CLI in worktrees or MCP where available. For local models (e.g. Ollama), use the same embedding URL and model as Knowtation—see Settings → Agents for the current config and a copyable env snippet.