Your notes, searchable. One place for you and your agents.
Precise token use mean speed & savings.
Two ways to use Knowtation
Use in the decentralized cloud (beta) — Sign in with Google or GitHub; we host your vault. Open usage during beta while we learn.
Run it locally — Clone, set KNOWTATION_VAULT_PATH and HUB_JWT_SECRET, npm run hub. Quick start (self-hosted).
Beta: open usage for now. Later: free tier + paid plans, dollar-clear credits (1 = $1), metering focused on index + search + writes (no hosted transcription—bring Markdown or exports). Rollover add-ons and usage charts when billing ships.
— setup and how agents use your vault.
📁Knowtation
✏️
🤖
🦌
🏄
🔌
💻
🔍
📥
🏷️
📂
🔗
⏱️
📋
🐙
📡
🔐
🎙️
🔄
📝
📤
OAuth is not configured yet. The Hub only accepts login through Google or GitHub. Add credentials to your project .env, then restart the Hub.
Google: Cloud Console → OAuth client (Web) → redirect URI http://localhost:3333/api/v1/auth/callback/google → set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET.
GitHub: OAuth App → Authorization callback URLs (add both for local Hub): http://localhost:3333/api/v1/auth/callback/github (login) and http://localhost:3333/api/v1/auth/callback/github-connect (Connect GitHub for backup). Set GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET in .env.
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.
Notes changed since the last Re-index. Meaning search may be out of date until you run it again.
Browse
▲
One vault for people and agents (Hub UI, CLI, MCP, API). The same notes, imports, and proposal queues apply to both; what you can open follows your role and tokens. Use whichever you prefer.
Notes & import
Notes — Markdown files in your vault (List / Calendar / Overview). Search results land under Notes.
Import — Brings chats, exports, and files in as normal notes (same search and filters afterward).
Quick — Next to the browse key; click the arrow to show or hide chips (projects, tags, folders, nets). Row filters and content scope apply either way.
All / Clear — Reset Quick and filters to see the full list again.
Meaning — Semantic search over the index; Keyword scans note text on the server.
Images & video — Use links or uploads per your setup; media files live with the vault and can be included when you back up to GitHub (paths stay consistent in the repo).
Proposals & agents
Suggested — Proposals waiting for review (from you, CLI, or agents). Open one to Evaluate (pass / fail / needs changes), then Approve (writes the vault) or Discard.
Activity — Timeline of proposal events (created, approved, discarded). The Notes search bar does not filter this tab.
Discarded — Rejected proposals for reference; not applied to the vault.
Evaluations — Policy and optional review hints / enrich (LLM) tie to the same Suggested queue; admins may require evaluation before approve (see Settings → Proposal policy).
Agents — Use the same APIs as humans: search, read notes, create proposals. Nothing merges to canonical notes until approval when you use the proposal flow.
Re-index rebuilds the search index from your vault. Run it after large imports, many edits, or path renames so Meaning search and snippets match what is stored.
Memory
Memory consolidation — Optional jobs that merge memory events into compact facts so future agent context stays smaller; scheduled or triggered outside the Notes list (see docs / Settings).
Discover — Optional pass during consolidation that adds cross-topic “insight” links between themes; augments memory, not a separate Hub screen.
Attestation — Signing (and optional Internet Computer anchoring) for audit trails on approved changes; complements proposals after commit, not day-to-day browsing.
Connection helpers
Copy prime — Settings → Integrations → Hub API → Copy prime. A short “you are here” for your tool after it connects; not your login token.
Doctor — With the CLI on your computer: knowtation doctor checks the vault folder and (optionally) the Hub. See docs/RETRIEVAL-AND-CLI-REFERENCE.md.
Your vault is empty. Pick up where the walkthrough left off — same three moves as on the homepage:
1Note / import — capture or import into your indexed vault.
2Add agents — MCP or Hub API from Settings → Integrations.
3Ask your AI — phased prompts in the docs when you want your assistant to drive setup.
SunMonTueWedThuFriSat
Memory Consolidation
● Not configured
Last pass: —
Next pass: —
Activity lists proposal records (same data as Approve/Discard)—not semantic search hits. Vault approvals/*.md logs: open Notes, set content to Approval logs only, Apply filters or Search.
Use the proposal filters row (shown above when this tab, Suggested, or Discarded is active) to narrow by label, source, path, evaluation, queue, or severity. Sort (top right) applies here too.
Sources: Hub (New proposal / Propose change), CLI, API.
Proposals needing your review. Create one with New proposal or from a note (Propose change in the detail panel); the CLI and agents can still create them via the API. Open a row, 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.
Add to vault
If set, saves under projects/<slug>/inbox/… and sets project in frontmatter. Leave empty to save to inbox/ only.
Saves to inbox with today’s date.
Duplicating from . Choose a new path (same pickers as New note). Saving at the same path would overwrite the original.
Uncheck to keep two copies if agents, automation, or bookmarks might still need the old path.
Choose a Project or use Custom (type full path) for anything else.
Choose a subfolder or use Custom to type any path.
Choose a Folder on this vault. Pick Custom to type any path.
Choose ‘Custom’ in Project, Folder, or Path to change your final path.
Frontmatter project for filters and charts. If your path starts with projects/slug/, this field follows that slug automatically.
Temporal and hierarchical (optional):
Similar project already exists
New proposal
Submit a proposed file change for review (same as POST /api/v1/proposals). Admins approve in this tab.
Import into vault
Pick a source type, then a URL and/or files (dashed area or Choose folder). Sign in first. ~100 MB per request.
No file upload. The bridge must have a Google service account; share the sheet with that account (Viewer). See IMPORT-SOURCES.
Use Bookmark for paywalled or login-only pages. Extract requires readable HTML.
Drop files or a folder here, or use the file picker below.
Multi-select or folder. See More under the form for batch limits.
Folder selection will build one in-browser ZIP (folder-shaped source types only, not PDF/DOCX).
Choose a Project or use Custom (type full path) for anything else.
Choose a subfolder or use Custom to type any path.
Choose a Folder on this vault. Pick Custom to type any path.
Choose ‘Custom’ in Project, Folder, or Path to change your final path.
More: folder/ZIP, multi-file, PDF, audio, and hosted
Tree-style source types (e.g. Markdown, ChatGPT, many exports) can use a .zip, the drop zone, Choose folder (in-browser ZIP), or multi-file. PDF and DOCX are one file per import (use multiple files for many documents). Audio needs a transcribe-capable Hub; ~25 MB per file for OpenAI. Video is not in this dialog; use the CLI.
Hosted import needs the operator to set BRIDGE_URL on the gateway. If you see that import is unavailable, ask your host or use self-hosted Hub. Full options and limits: IMPORT-SOURCES.
Get started
Prefer an AI assistant?AI-assisted setup — phased, copy-paste prompts for Cursor, Windsurf, and similar tools.
Projects on hosted Knowtation
On hosted Knowtation, a project is just a name you put on your notes so they stay grouped together.
To start a project: create a note (for example with + New note) and add a project name on that note. That first note starts the project. Add the same project name on other notes to keep them in the same group.
The name then shows up in the project menu and in quick filter chips. It is not a folder path like on self-hosted.
Self-hosted: path projects/ vs field project
On disk, many vaults group files under projects/<slug>/… (note the plural projects). In the Hub, if a note’s path starts with projects/<slug>/, the Project field stays aligned with that folder name on save.
You can also set project in frontmatter on notes anywhere (for example inbox/idea.md) — that label is for filters and charts and does not create a folder. A common typo is typing project/… instead of projects/… in the path; the Hub warns you when that happens.
Technical: YAML project field
In the note editor, the project is stored as a project field in the YAML block at the top of the file (frontmatter). Example:
---
project: my-team
title: Kickoff
---
Your note body here.
Settings
Hosted users: we keep your notes in the cloud; GitHub is an optional copy so you “own the repo” and have history. Self-hosted users: the vault is a folder on this machine, and the same screen wires Git. Status below always shows Mode so you know which world you are in.
Setup checklist
Get from zero to using the Hub and (optionally) backing up. Complete each step; optional steps can be skipped.
— short walkthrough (hosted and self-hosted).
Vault path setSet below under Configure backup
✓Hub is runningYou’re here
✓Logged inYou’re here
Backup configured (optional)Git enabled + remote below; then Connect GitHub and Back up now
At a glance:Hosted (beta) — “Canister” in the Vault line means cloud-stored; optional GitHub export. Self-hosted — Vault line shows a disk path. Admins: expand How to connect backup for the Git path + remote you maintain.
Status
Current vault and backup state.
Your role—
Your user ID—
Admins set roles in Team. Your ID is provider:id (e.g. google:…) — it is not your email.
Self-hosted — optional roles on disk
Some installs also read data/hub_roles.json.
Mode—
Vault—
Git backup—
Proposal evaluation gate—
Review hints (LLM)—
Proposal enrich (LLM)—
You may approve proposals—
Admins: Turn proposal features on or off here when they are not forced by server environment variables (disabled checkboxes are env-locked on the host).
Proposal review: Suggested edits from people or tools wait in the Suggested tab. When the evaluation gate is on, a reviewer records pass / fail / needs work before (most) approves. Review hints and Enrich are optional assistive text — never merge gates, and on some hosts proposal text is sent to a model. Evaluator may approve is set in Team and shown in Status. More context: How to use → Knowledge & agents and docs/TEAMS-AND-COLLABORATION.md.
Technical details — env and file locations
Grade is for your records only. Evaluator fallback: server may use HUB_EVALUATOR_MAY_APPROVE=1 if no per-user flag exists. Self-hosted files:data/hub_evaluator_may_approve.json, data/hub_proposal_policy.json. Greyed checkboxes in policy usually mean the host set HUB_PROPOSAL_* or KNOWTATION_HUB_PROPOSAL_* environment variables.
API base—
GitHub—
Connects in this browser tab (you may leave Settings). Each signed-in user authorizes their own GitHub account for pushes. You need an empty GitHub repo and its owner/repo in the field below before Back up now.
For hosted backup, enter the GitHub repository as owner/repo. A brand-new empty repo (no README yet) is fine — the first Back up now creates the initial commit. This is sent with Back up now; after a successful push the repo is remembered for next time.
Back up now backs up the currently selected vault (use the Vault dropdown in the header to switch). Each vault can have its own Git remote.
Self-hosted:Connect GitHub saves a token so pushes can authenticate — it does not run git init in your vault. If backup says the folder is not a Git repo, click Initialize Git in this vault (appears after a failed backup) or run git init manually in that folder.
Danger zone
These actions permanently remove data from Knowtation. There is no undo.
Projects
Path prefix is the note’s file path in the vault (same string as in POST /notes), not the Hub Project filter. Example: notes in inbox/foo.md match prefix inbox, not your frontmatter project: slug. On hosted (canister), paths are still stored strings — there is no disk folder, but the rule is the same.
Delete by project slug removes every note whose effective project matches (frontmatter project: and/or path under projects/<slug>/, same as list/search). Rename project and delete-by-project slug run on hosted (gateway) and self-hosted Hub. Delete by path prefix below needs the Node Hub with a filesystem vault — not the hosted gateway. See docs/HUB-METADATA-BULK-OPS.md.
Pick from disk + note paths, or choose Custom and type the exact prefix.
Projects from this vault’s notes (facets). Custom if yours is not listed.
Same project list as above. To slug is still typed (new name).
Path-prefix and project-slug deletes discard matching proposed proposals (same vault). Rename-project only updates YAML frontmatter project:; it does not move files between folders. On hosted, the gateway runs these against your canister vault (same effective-project rules as list/search).
Vault
Deleting a vault removes everything stored in that notebook: all notes, project labels and paths, media and other files in that vault, and related Hub data (including search index entries for that vault). The default vault cannot be deleted. This does not delete your GitHub backup repository — only the copy Knowtation holds.
Only non-default vaults are listed. Self-hosted: admins only. Hosted: same rules as creating a new cloud vault (workspace owner when a shared workspace is set).
How to connect backup
To turn on Git backup, follow these steps:
Create a new repository on GitHub. Leave it empty (do not add README, .gitignore, or license). Use the HTTPS URL (e.g. https://github.com/you/repo-name.git) so Connect GitHub can push; private is recommended for notes.
Ensure your vault folder is a Git repo. With the default path ./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.
Below, check Git backup enabled and paste that repo’s URL into Git remote URL.
Click Save setup. Optionally click Connect GitHub (under Status) so the Hub can push with your token. Then use Back up now.
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, evaluator). Only admins see this tab. Use User ID or invite links to connect teammates.
How to add someone
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.
How to invite by link
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.
Pending invites
Loading…
Current roles
Loading…
Vaults, access, and scope · admin
Hosted (cloud) — A vault id is a separate cloud notebook (not a folder on your computer). The header Vault menu switches notebooks you’re allowed to open.
Shared workspace — One setting: workspace owner (whose cloud notes the team uses). This deployment does not offer multiple separate “workspaces” in the UI—one owner id, many vault ids inside that cloud. Teammates: Team → roles, then Vault access (and optional Scope).
Who creates vaults? If a workspace owner is set, only that person can create new vault ids here; admins still assign who may open which vault. Solo / no owner: you can add vaults yourself.
Projects — A project is a label on notes (for filters and grouping). It is not the same as a vault. Notes still have paths like inbox/… in the cloud; you don’t browse a real disk—use project names and filters the same way you use tags.
Self-hosted — Each vault is a folder on this machine (data/hub_vaults.yaml lists id + path). Use Vault list or Advanced JSON. There is no cloud “workspace owner” field here—this install is your environment.
Who adds vaults? Any user with admin role can add or change vault folders and save the vault list.
Projects — Same idea as hosted: group notes by project: in frontmatter and/or by putting files under projects/<name>/ on disk. Paths are real folders you can open in the OS.
Header Vault menu appears when you have two or more vault ids you’re allowed to use. Another “world” entirely = another sign-in (Google/GitHub) or another Hub deployment—not a second workspace row here.
Vault list
Keep id default for your primary vault. Folder path is the note directory on disk (absolute or relative). Save after editing.
New vault: choose New vault, then id + path. Edit: pick a row, change path or label, then Add or update in list.
Advanced: edit vault list as JSON
Loading…
Add a vault (hosted)
A vault id is a separate notebook in the cloud (different from a project folder inside a vault). Use letters, numbers, hyphens, and underscores only. You already have default — pick another id (e.g. work).
Creates one starter note under inbox/ in the new vault. Agents can also use header X-Vault-Id with the same id.
You’re using a shared workspace. Only the workspace owner can create new cloud vault ids (separate notebooks). Ask them to add the vault here, then an admin can grant access under Vault access below.
Shared workspace owner (hosted teams)
Imagine one shared filing cabinet in the cloud. The workspace owner is whose cabinet everyone opens when they’re on the team. Paste the owner’s User ID (same format as Settings → Backup → Your user ID—usually your ID if you’re the lead). Until this is set, each person only sees their own empty cloud space. After you set it, invited teammates (with roles from Team) read and write that owner’s notes.
Vault access
People not listed only get the default vault. Use Team roles to fill the Person menu. Tick vaults · Apply to rules · then click Save vault access (required — rules are not saved until then).
Who may open which vault.
From Team · Apply, then save below.
Preview
Advanced: edit access as JSON
Scope (per user per vault)
Optional limits inside a vault (projects / folders). Leave empty for full vault. Same person picker as access; then Save scope.
Limit folders or projects per person.
Fill fields · Add to scope · then save.
Advanced: edit scope as JSON
Hub as a flexible network: Many users, many vaults, many repos, and agents (MCP, AgentCeption, and optionally linked tools such as Muse) from one Hub—Knowtation does not require Muse to be running.
Integrations connect external tools to your vault: capture (Slack, Discord, etc.), imports (ChatGPT, Notion, etc.), and agents. Hub API (REST + optional MCP)
How?
Uses the same sign-in as this tab on hosted and self-hosted gateways—copy URL, JWT, and vault id for scripts and tools outside the browser.
The Hub API block is at the bottom of this tab (above Agent Configuration). Advanced Ecosystems (Muse, AgentCeption) stay collapsed until you open them.
Capture (messages → inbox)
What this is: turns chats and automations into new notes in your Inbox. Most teams set up a small bridge (or Zapier/n8n) once. Walkthrough: How to use → Setup → Self-hosted setup → Step 5 (same capture path on hosted; only the host URL changes).
💬SlackTeam chat → Inbox
🎮DiscordServer messages → Inbox
✈️TelegramBot or webhook → Inbox
📱WhatsAppAutomation → Inbox
Technical: capture API, ports, and secrets
Endpoint: POST /api/v1/capture with JSON {"body": "text", "source": "slack", …}. Optional shared secret: CAPTURE_WEBHOOK_SECRET + X-Webhook-Secret header. Default adapter examples in the repo: Slack 3132 (SLACK_SIGNING_SECRET), Discord 3133, Telegram 3134. See docs/MESSAGING-INTEGRATION.md.
Import sources (files → vault)
What this is: one-time (or scheduled) imports from files and apps (Chat exports, Notion, CSV, and more) into your vault. Use the Hub Import button when available, or the CLI for large batches. Full list: docs/IMPORT-SOURCES.md.
CLI pattern knowtation import …
Common options: --project, --output-dir, --tags. Exact source names: see the doc above.
🤖ChatGPTZIP or folder export
🧠ClaudeChat + memory export
💾Mem0JSON memory export
📝NotionAPI; page IDs + key
🎫JiraCSV export
📓NotebookLMMarkdown or JSON
📁Google DriveMarkdown folder
📋LinearCSV export
🔗MIFMemory Interchange Format
📄MarkdownFile or folder
🎙️AudioWhisper transcription
💰Wallet CSVTx history; 11 formats
🗄️SupabaseMemory table import
🦞OpenClawAgent memory + chats
💻Local ImportsFiles from disk
👥Team ImportsTeammates contribute
Token savings: Use memory consolidation (Settings → Consolidation) to compress activity into facts. Use tiered retrieval in agents—search with a small limit and short fields, then open only the notes you need. Optional Discover adds cross-topic insights inside the same consolidation run on hosted plans (one pass per run, not two).
Meetings and transcripts: Hosted Knowtation does not run transcription for you. Export text or Markdown from your recorder (Otter, Zoom, Granola, etc.) or paste into a note, then index—same outcome for search and agents.
Self-hosted only — long audio and ffmpeg
Whisper is limited to about 25 MB per file. If ffmpeg is installed on the host (ffmpeg.org, or the Docker image we ship), very large files can be compressed first. Toggles: transcription.transcode_oversized: false in config/local.yaml or KNOWTATION_TRANSCODE_OVERSIZED=0; FFMPEG_PATH if not on PATH. Hosted: export transcript text; we do not run this pipeline in the browser.
Advanced Ecosystems
Muse (optional link)
When enabled on the server, Knowtation can attach a small cross-reference id (external_ref) to approved proposals so the same change can be looked up in Muse / MuseHub (structure, lineage, blast radius). Your notes still live in Knowtation; nothing is moved automatically.
Not your Git backup URL. Enter the HTTP base URL of the Muse service (the API root your operator exposes), e.g. https://muse.yourcompany.com — same host that serves GET …/knowtation/v1/lineage-ref per docs/MUSE-THIN-BRIDGE.md. The ref stored on the proposal is a short opaque string (letters, numbers, common safe punctuation; no control characters), up to 512 characters.
—
AgentCeption (self-hosted — shared disk vault)
Hosted beta users: you typically connect tools with Hub API above; skip this unless you run multi-agent setups against a shared local vault path.
Self-hosted: Use Knowtation as shared context for planner and engineer agents — one on-disk vault path for the whole setup.
How to connect AgentCeption
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
Hub API
There is no separate “API signup.” You already signed in above — tools outside the browser (Cursor, scripts, curl, API clients) need a copy-paste block from this page. After you log in, click Copy Hub URL, token & vault and treat that paste like a password (do not share it). The same token works for Hub REST and for remote MCP (with the same headers); the paste includes a link to the full guide (not a long comment block in the clipboard).
Technical details — Hub URL vs MCP URL, Bearer, hosted vs self-hosted
REST and MCP are explained in the doc linked from the copy button (and on this project’s docs/AGENT-INTEGRATION.md). In short: KNOWTATION_HUB_URL is the REST API; KNOWTATION_MCP_URL (when your host sets it) is the remote MCP endpoint; the token is the same JWT with Authorization: Bearer … and X-Vault-Id. Your browser session is separate from the pasted API block.
Troubleshoot: API token, automations, and HTTP headers
The copied JWT expires on a schedule (security). Automations (cron, CI, static MCP JSON) fail with 401 only if they still send an old pasted token after expiry—click Copy Hub URL, token & vault again and update the secret where you pasted it. Your browser session in this Hub tab is separate and usually keeps working.
Reduce surprises: Prefer ${env:KNOWTATION_HUB_TOKEN} in MCP config (see docs/AGENT-INTEGRATION.md) so you rotate one env var instead of editing JSON. Long-running servers may need an occasional re-copy after policy or rotation changes.
For HTTP calls, send Authorization: Bearer … and X-Vault-Id on vault-scoped routes. JSON MCP headers must use the fullAuthorization value: Bearer <KNOWTATION_HUB_TOKEN>, not the token alone. Full shapes: docs/AGENT-INTEGRATION.md.
Copy prime saves a small JSON reminder to the clipboard: which Hub you are on and which vault. It does not contain your sign-in secret — use Copy Hub URL, token & vault for that.
Technical details — MCP readResource and prime URI
The JSON includes the MCP readResource URI knowtation://hosted/prime, this gateway’s base URL, and the current vault id — not your JWT. After your MCP client connects with valid Authorization and X-Vault-Id headers, it may read that resource for session context and which MCP prompt names are registered for your role (or use prompts/list).
Full agent reference (CLI, MCP, Hub API, no separate signup): docs/AGENT-INTEGRATION.md.
Agent Configuration
Embedding config the Hub uses. Match this in your agent runtime so search behaves the same.
Provider—
Model—
Ollama URL—
Use Copy Hub URL, token & vault (Hub API section above) for connection secrets. The button below copies only embedding-related lines so a local indexer matches this Hub.
Technical details — embedding env lines
Those lines align Ollama / provider URL and model with this deployment; they are separate from KNOWTATION_HUB_URL / token / vault id.
Theme
Accent color
Choose an accent for links, buttons, and highlights. Presets on the left; any exact color on the right.
Classic
Pastels
Earth
Vivid
Muted
Custom
#89CFF0
Dashboard color theme
Each preview is Night (left) then Day (right), four bands each: background, surface, border, secondary text—so you can see the real tint.
Your Knowtation plan and usage. Indexing tokens are consumed each time you Re-index your vault. Semantic search is included on all plans.
Plan—
Usage this period
Searches
— / —
Index jobs
— / —
Consolidations
— / —
Pack balance: 0
Notes—
Period—
Legacy credits—
Token pack add-ons
Extra indexing tokens that roll over. Consumed after your monthly grant runs out. Available on paid plans.
Self-hosted Hub (no gateway) does not expose this API — use the hosted Hub or GET /api/v1/billing/summary for operators.
Knowtation is presented by Born Free Communities. We developed this for our use and thought we should share it with everyone.
Memory Consolidation
Knowtation is built to reduce wasted context: consolidation merges noisy memory events into facts; agents should search narrowly then open specific notes. · docs/TOKEN-SAVINGS.md (repo)
Self-hosted runs on your machine. Hosted uses the Hub's LLM (included in your plan).
Open the in-app walkthrough to create your first notes, see optional GitHub backup, and learn where AI-suggested edits appear (Suggested). Best for hosted users; self-hosted operators can use it too, then read Setup → Self-hosted setup for machine install details.
Start over from step 1: Settings → Backup → Setup guide.
Hosted Hub — start here
If Settings → Backup → Mode shows Hosted (beta), you do not install a server or pick a folder on your laptop. Your vault lives in the cloud; we handle search indexing.
Notes — Import or write notes; use the header Vault menu if you have more than one notebook.
Optional backup — Create an empty GitHub repo, connect your account under Backup, enter owner/repo, then Back up now.
Connect an AI assistant — Settings → Integrations → Hub API has copy buttons. Read Knowledge & agents for a plain-English explanation of the two copy types.
Edits from tools — Appear under Suggested until you approve (nothing applies to your vault until you approve).
Running the Hub on your own machine instead? Open Self-hosted setup below.
Self-hosted setup — install the Hub on your computer
Self-hosted in one sentence
You run npm run hub, point it at a folder of Markdown notes on disk, sign in with OAuth you configure, and (for meaning-based search) run an indexer once. Settings → Backup → Mode shows “Self-hosted”.
Full developer docs (install, config, MCP, checklist)
Self-hosted: follow the numbered steps below in order. Skip this whole block if you are on hosted only.
1Vault & config
→
2Run Hub
→
3Log in
→
4Index & search
→
5Import data
→
6Use & automate
→
7GitHub backup
Step 1 Vault and config
What this does: Tells Knowtation where your notes live so the Hub and CLI read and write the same folder. The vault is just Markdown files — not the Knowtation source code.
Create a folder for notes (any path you like). Example in your home directory:
Terminal
mkdir -p ~/knowtation-vault
Set the same absolute path in two places: (1) env var KNOWTATION_VAULT_PATH in .env at the project root, and (2) vault_path: in config/local.yaml (so CLI, indexer, and Hub agree).
For semantic search without a separate database server, add vector_store: sqlite-vec and data_dir: data/ — vectors are stored in a local SQLite file under data/, not in Qdrant. (Optional: use qdrant + qdrant_url if you run Qdrant yourself.)
Example config/local.yaml (paths must be absolute)
Already developing Knowtation? You can skip git clone — use your existing repo. Create the vault folder outside the repo (e.g. ~/knowtation-vault) so your personal notes stay separate from the app source.
Step 2 Run the Hub
What this does: Starts the web app (this UI) and the API on your machine. You do not clone a separate “site” — the Hub process serves both.
One-time: cd hub && npm install && cd .. from the Knowtation project root.
From the project root run npm run hub.
Open http://localhost:3333 (or the port you set with HUB_PORT). Use http:// — not https://localhost.
Example
$ npm run hub
Knowtation Hub listening on http://localhost:3333
Step 3 Log in (OAuth)
What this does: Proves who you are so the Hub can show your vault and let you approve proposals.
Click “Continue with Google” or “Continue with GitHub” on the login screen.
No OAuth secrets ship in the repo. Each self-hosted install registers its own Google/GitHub OAuth app and puts GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and/or GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET in .env. Add redirect URIs in the provider’s console (e.g. http://localhost:3333/api/v1/auth/callback/google).
If you see “OAuth is not configured”, add those variables, restart the Hub, and try again.
Hosted users (knowtation.store) use our gateway’s OAuth — you do not add client IDs on your machine.
Step 4 Index and semantic search (self-hosted)
What this does: Turns your notes into searchable vectors. Listing and opening notes works without this. Search vault in the Hub (and CLI knowtation search) needs an index.
Hosted: skip this — we run indexing for you.
Two separate choices (simple mental model)
Where vectors are stored:sqlite-vec (default in examples) = one SQLite file under data/, no extra server. Orqdrant + qdrant_url = a separate Qdrant service (Docker or cloud). Same job; different deployment.
How text becomes vectors (embeddings):Ollama locally (e.g. ollama pull nomic-embed-text) orOpenAI (OPENAI_API_KEY in .env + embedding.provider: openai in config). This is not a chat “LLM” — it’s the model that encodes text for search.
After config/local.yaml matches Step 1, run once from project root:
Terminal
npm run index
Or in the Hub: Re-index (same operation). After big imports, run index again. Full detail: setup.md § Index.
Step 5 Import data into the vault
What this does: Brings in notes from Slack, files, ChatGPT, or other tools into your vault folder as Markdown. They show up in the Hub list immediately. For semantic search to include new files, run Step 4 again (index or Re-index).
Integrations at a glance
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.
Where data comes from → where it goes
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.
Capture (messages → vault)
Slack
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.
Discord
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.
Telegram
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.
WhatsApp
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.
Import (LLM / platform exports → vault)
ChatGPT export
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.
Claude export
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.
Mem0 export
knowtation import mem0-export /path/to/mem0-export.json --project memories. Each memory becomes a vault note with source: mem0.
Notion, Jira, NotebookLM, GDrive, Linear
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).
Transcripts, meetings, and video (bring text in)
Hosted: We do not transcribe audio or video in the cloud. Get a transcript from your tool (Otter, Zoom, Granola, Descript, etc.), save as Markdown or paste into a note, then re-index so search and agents can use it.
Self-hosted: You can use knowtation import audio … with your own OPENAI_API_KEY (Whisper). video is CLI-first; Hub UI for video is planned.
Why: Fewer moving parts, predictable costs, and you keep control of where transcription happens.
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.
Step 6 Use the Hub and automate with agents
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.
Notes: project, path, and tags (two ways)
Project can come from (1) path — a note under vault/projects/Launch/ is in project “Launch”; or (2) frontmatter — project: Launch in the note’s YAML. Both count for filters and scope. Tags and date, causal_chain_id, entity, episode_id go in frontmatter (or are set in the Hub when you create the note).
Where the file lives:Quick capture always saves to inbox/; you can set project and tags in the form — they’re written into frontmatter, so the note is “in” that project for filtering even though the file is in inbox. To put the file in a specific folder, use + New note → New note (not Quick capture): choose Folder (lists directories under your vault, including empty ones) or Custom and edit the full path — e.g. projects/Launch/my-note.md. Then fill title, body, project, tags as needed. So: project from path = file under projects/<name>/; project from frontmatter = file anywhere (e.g. inbox) with project: <name> in the note.
Multiple vaults and multiple users
On self-hosted you can have multiple vaults (Settings → Vaults): define a vault list (data/hub_vaults.yaml), then map each user to the vaults they can see (data/hub_vault_access.json). Optionally restrict a user to certain projects or folders within a vault (data/hub_scope.json). See docs/MULTI-VAULT-AND-SCOPED-ACCESS.md for full setup.
User ID is provider:id — e.g. google:104164334692309763642 if you signed in with Google, or github:12345678 if you signed in with GitHub. You see yours in Settings → Backup (“Your user ID”). Each sign-in identity is one user; if you have several Gmail or GitHub accounts, each account that signs in gets its own user ID. Admins add each ID to roles and vault access as needed. So the same Hub can serve many users, each with access to their assigned vaults (and optionally scoped to certain projects/folders).
Hosted vs self-hosted: workspace, vaults, projects
Self-hosted — One Hub install (often one machine) with one or more vaults, each vault = a folder on disk. There is no “shared workspace owner” setting. Any admin can add or change vault folders in Settings → Vaults. Projects group notes by path (e.g. projects/Launch/…) and/or by project: in note frontmatter.
Hosted (beta) — Vaults live in the cloud (vault ids like default, work), not as folders on your laptop. Workspace owner (Settings → Vaults) is optional: if set, the team shares that person’s cloud notes; only that owner can create new vault ids, while admins still control Vault access / Scope for others. This site has one workspace-owner setting—not multiple separate workspaces in the UI. A fully separate “world” = another Google/GitHub account or another deployment.
Projects on hosted — Same idea as self-hosted (group and filter notes), but you don’t rely on OS folders: put a project name on the note (see the (i) next to the project filter). Notes still have paths like inbox/note.md in storage—that’s not the same as picking a separate vault.
Why not identical to self-hosted? Cloud storage is keyed by user and vault id; letting every admin spawn new partitions without tying it to the account that “owns” that data would blur ownership and backups. Self-hosted is just files—any admin may point the Hub at another folder. See Settings → Vaults → (i) for the short version anytime.
Backup: “Connect GitHub” and “Back up now” are per logged-in user. Each user can connect their own GitHub account and push to their own repo (or to the repo configured for the vault they’re in). Different users can back up to different repositories; they could also point to the same repo if you set remotes that way (e.g. different branches), but the Hub UI stores one token per user and pushes the current vault’s folder to that vault’s remote.
Hub as a flexible network
One Hub can coordinate many users (each sign-in = one identity), many vaults (each with its own path and optional scope), and many backup repos (per user or per vault). The same Hub is flexible enough for many agents to use it in many different ways: different agents or workflows can talk to different vaults, or the same vault, while you keep one coordination layer and one URL.
Why multiple vaults and scoped access help
You keep all information under your control in separate vaults (e.g. personal vs team, or project A vs project B).
Filter access so each user only sees the vaults they're allowed. Scope so a user or agent only sees certain projects or folders within a vault. The right people—and the right agents—get only the context they need.
Examples: A planner agent uses vault A for product context while engineer agents use vault B for technical decisions. Or one vault for personal notes and another for the team, with scope so each identity sees only the right one. Or one vault with projects "Launch" and "Q1 roadmap," and agents filtered by --project so they only read what's relevant.
AgentCeption and Muse
Today: AgentCeption’s planner and engineer agents use the same Hub API and proposals as other clients; proposal payloads use Muse-aligned fields (base_state_id, intent, optional external_ref) without running Muse on the Hub.
Optional: If you operate a Muse instance, you can use a thin bridge for read-only structural / Git-replayed history and set external_ref when approving proposals—canonical vault and login still live in Knowtation. See docs/AGENT-INTEGRATION.md §4 (Optional external lineage).
Advanced / deferred: A full Knowtation domain plugin inside Muse (Muse as the variation backend) is a separate, heavy integration; see the same doc §6.2.
Point different AgentCeption agents at different vaults for different issues—all through the same Hub. One Hub URL, one coordination layer so you don’t run separate systems per vault or per tool.
Many users, many vaults, many repos, many agents
Agents and LLMs → Hub → you
Proposals: where they come from and where to see them
You review proposals in the Hub. They can come from the Suggested tab actions (New proposal, or Propose change on an open note), from the CLI, or from an agent calling POST /api/v1/proposals.
Create a proposal: In the Hub: Suggested → New proposal, or open a note and click Propose change. From a terminal: knowtation propose --hub http://localhost:3333 --path inbox/idea.md --body "..." with KNOWTATION_HUB_TOKEN set (copy from Settings → Integrations → Hub API). Agents use the same API with Authorization: Bearer … and X-Vault-Id.
Suggested tab: Lists proposals waiting for your decision. Click one to open it. Use Evaluation to record a pass, fail, or needs-changes outcome (checklist + optional grade + comment). Then Approve writes the content to the vault, or Discard rejects it. If your Hub requires evaluation before approve, you must pass or enter an approve waiver reason. Filter with Pending evaluation only when triaging.
Discarded tab: Lists proposals you (or someone) discarded. You can open them to read; they are not applied to the vault.
Activity tab: Timeline of all proposals (proposed, approved, discarded) so you can see what changed and when.
Nothing is written to the vault until you Approve (or an admin does). Human-created proposals use the same queue as CLI and agent proposals.
Reviewing proposals (evaluation, triggers, roles)
Outcome vs grade: Saving evaluation uses an outcome (pass / fail / needs changes) plus checklist; optional grade is for culture or reporting and does not replace outcome.
Pending: New proposals may start as pending when your Hub requires evaluation for every proposal, or when review triggers match (phrases, path prefixes, labels). Filter with Pending evaluation, Review queue, or Severity on the Suggested tab.
Who does what:evaluator users record evaluation; admin always approves and discards. Evaluators may approve only when an admin grants it per user in Team (or the host sets HUB_EVALUATOR_MAY_APPROVE=1 as a fallback when no per-user entry exists). Waivers on approve remain admin-side when evaluation has not passed.
LLM review hints: If enabled on the Hub, short async hints may appear on a proposal. They are not a merge gate; treat them as untrusted.
Hub UI: filters and views
Projects, tags, folders: Notes can have 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:launch) load a filtered list from the server — not the same as green Search (semantic / meaning). Quick chips clear the semantic search field so the two modes don’t fight. Save a view with Save view as and click a preset pill later.
Semantic search: Type a phrase, then green Search or Enter. It searches the indexedcurrent vault by meaning (embeddings), not keyword match — you can get results that don’t contain your word. The project/tag/folder/date dropdowns narrow semantic search when set. Clear empties the box and returns to the list. Requires indexing (Step 4) on self-hosted.
List / Calendar / Overview: List = filtered rows; Calendar = month grid (click a day for that day's notes); Overview = dashboard and charts.
+ New note: Quick capture (inbox) or full form (path, title, body, project, tags). Use "Copy path" in the detail panel to copy the note path for CLI/API use.
Re-index: After importing notes or changing many files, click Re-index so semantic search reflects the latest vault (same as Step 4 / npm run index).
Keyboard shortcuts:/ focus search; Enter runs semantic search when the search field has text (otherwise Enter opens the selected note in the list); j / k move in the notes list; Esc close panel or modal.
Connecting agents and other tools
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
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.
Example env
KNOWTATION_HUB_URL=http://localhost:3333
KNOWTATION_HUB_TOKEN=<JWT after login>
KNOWTATION_HUB_VAULT_ID=default
# Or use Settings → Integrations → "Copy Hub URL, token & vault" (one click)
Abacus
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.
Example
# In your Abacus tool config, add Knowtation Hub:
# - Hub URL + KNOWTATION_HUB_TOKEN for API calls
# - Or shell tool: knowtation search "query" --json
Common LLMs (Claude, ChatGPT, etc.)
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.
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.
Show full setup steps
Prerequisites: AgentCeption repo/setup; a folder for the shared vault (e.g. inside the AgentCeption project or a dedicated repo).
Vault and env: Create or choose vault path. Set KNOWTATION_VAULT_PATH to that path for the planner and for every engineer agent (same path). Optionally set vault_path in config/local.yaml.
Orchestrator / CTO (MCP): Run knowtation mcp or add the Knowtation MCP server to the Cursor/Claude config used by the planner. Tools: search, get_note, list_notes, write.
Engineer agents (CLI): In each worktree/agent environment, install the Knowtation CLI and set 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.
Write-back: After phases, pipe summaries into the vault: 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>.
Index: Run 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/GETTING-STARTED.md and docs/AGENT-INTEGRATION.md in the repo.
Muse (protocol alignment and optional linkage)
Muse is a domain-agnostic version control system: snapshots, DAG history, domain plugins, and Git replay into structural history. Default Knowtation Hub: proposals follow the same lifecycle and identifiers as the Muse-aligned variation protocol (base_state_id, intent, optional external_ref)—no Muse runtime required.
Optional thin bridge: Operators can link a Muse instance for read-only lineage queries and set external_ref on approve. See docs/AGENT-INTEGRATION.md §4 (Optional external lineage).
Full plugin (deferred): Running Muse as the merge/variation engine for the vault is a large, optional product path. Maintainer context: docs/AGENT-INTEGRATION.md §4 and docs/MUSE-THIN-BRIDGE.md.
Public integration entry point: docs/AGENT-INTEGRATION.md; gateway deploy: hub/gateway/README.md.
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.
Step 7 GitHub backup and version control (crucial)
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.
Hosted vs self-hosted: On hosted (knowtation.store), you don’t run git init — create an empty repo on GitHub, then use Connect GitHub and Back up now; we push your vault there via the API. On self-hosted, the vault folder must be a Git repo (run git init inside it once if needed); then Save setup, Connect GitHub, and Back up now.
Your vault can live in a Git repository and sync with a remote like GitHub. That gives you:
Backup: A copy of your notes in GitHub; if your machine is lost, you can clone the repo and point Knowtation at it again.
Version history: Every commit is a snapshot; you can see diffs and revert changes. Proposals you approve in the Hub can be committed and pushed as part of your workflow.
Portability: The vault is a normal Git repo; clone it on another machine, use GitHub’s UI to browse, or hook in CI/CD.
Creating the backup repository (GitHub)
When you create the repo on GitHub, use these settings so backup works smoothly:
Leave the repo empty — do not add a README, .gitignore, or license when creating. An empty repo avoids merge conflicts on the first push.
Use the HTTPS URL — e.g. 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.
Private is recommended for personal notes; public works if you want the repo visible.
When do I need to run 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.
Step A Default setup (typical)
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.
From project root
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.
Step B You already have a Git repo for notes
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.
Set that path and the backup remote in Settings.
Use Back up now.
After the vault is a Git repo — connect and push
In the Hub: Settings → Backup. Set vault path and backup repo URL, then click Save setup.
Click Connect GitHub so the Hub can push with your token.
Click Back up now. If the first push fails with "no upstream branch", run once from the vault folder: git push -u origin main (or master if that's your default branch).
Alternative: config file
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.
More answers (proposals, backup, sharing, AI tokens)
Common questions
Where do proposals come from?
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.
How do I back up the vault?
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).
What if I want to share only some projects or keep personal notes private?
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.
Where is the JWT for agents?
Log in to the Hub, then open Settings → Integrations → Hub API and click Copy Hub URL, token & vault. That copies KNOWTATION_HUB_URL, KNOWTATION_HUB_TOKEN, and KNOWTATION_HUB_VAULT_ID for curl and orchestrators. Copy prime (next to it) copies a non-secret JSON pointer so agents know to readResourceknowtation://hosted/prime after MCP connects—use it together with the JWT copy, not as a replacement. Settings → Agents → Copy embedding env is separate: it only copies Ollama/embedding lines, not the JWT. See docs/AGENT-INTEGRATION.md for CLI and MCP.
Your notes are the memory agents see. You stay in charge: tools suggest edits as proposals until you approve. One optional GitHub backup is separate from what agents read.
Linked notes, synthesis, research — and “popular starters”
Linked notes — Use [[name of another note]] in plain Markdown so ideas connect. The app can show who links to a note and a simple graph of links.
Synthesis pages — A short “what I think so far” note that points to your sources (clips, articles, meeting notes) instead of pasting them again. You refresh that page as you learn. Raw material stays in its own files.
Research and long projects — Same vault: add a project name and a folder you like (for example projects/your-book/sources/ and …/synthesis/). That is a habit, not a separate app. Optional skill packs in the repo give agents a longer recipe if you use Cursor or similar.
When two sources disagree — You can say so in a small “tensions” or “open questions” note, use the optional Discover pass after memory consolidation (see the Memory consolidation tab), or paste a ready-made starter from the doc below into any chat and attach your own excerpts.
Popular and powerful — The repo has a full list of: MCP prompt names, copy-paste blocks for any LLM, and CLI one-liners (search, list, propose, consolidate). Includes daily brief, search-and-synthesize, project summary, knowledge gap, meeting notes, session resume, and more — not only wiki and research.
Notes can include small labels at the top of the file (frontmatter)—things like project, tags, and dates. Nothing is guessed by an AI; you or your agent set these when creating or editing. They power filters and smarter search.
In the Hub: Use + New note (full form) for date, project, tags, and advanced fields. The search bar can narrow by time (Since / Until).
Technical reference — frontmatter fields and CLI flags
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.
Add notes normally (write, import, capture). Use projects and tags so assistants can fetch a small slice instead of everything. Optional extra fields (chains, episodes, entities) help advanced workflows.
How agents find it
Agents talk to the same vault through the Hub API, MCP, or the CLI. The usual pattern is: search or list with a tight limit, then open only the notes that matter—saves tokens and avoids noise.
Technical details — example commands and filter flags
Examples: knowtation search "query" --project myapp --limit 5 --json, knowtation list-notes --project myapp --json, then fetch full content for chosen paths. Filters include --project, --tag, --folder, --since, --until, --chain, --entity, --episode. See docs/RETRIEVAL-AND-CLI-REFERENCE.md and docs/AGENT-INTEGRATION.md.
Hosted MCP: secrets vs “prime” bootstrap
If you use an AI assistant (for example Cursor) with this Hub, you’ll use two different “copy” buttons in Settings → Integrations → Hub API:
1) Copy Hub URL, token & vault — This is the sensitive one. Think of it like handing someone the key card to your workspace: it proves who you are and which vault to open. Guard it like a password; it expires on a schedule, so if something stops working with a “not authorized” error, come back and copy fresh keys.
2) Copy prime — This is a small, non-secret sticky note for you or your assistant: it says which Hub you’re on and which vault, and reminds the tool to pull a tiny “you are here” summary after the assistant is already connected the normal way. It does not replace the key card — it just saves you from retyping addresses by hand.
On your own computer with a folder vault? You can run knowtation doctor in a terminal to sanity-check that folder and (optionally) whether the Hub still answers.
Technical details (MCP, URIs, CLI)
When you connect Cursor (or another MCP client) to this Hub’s gateway, you use two different kinds of copy/paste:
Secrets (JWT):Settings → Integrations → Hub API → Copy Hub URL, token & vault. That provides KNOWTATION_HUB_URL, KNOWTATION_HUB_TOKEN, and KNOWTATION_HUB_VAULT_ID for Authorization: Bearer … and X-Vault-Id on POST …/mcp and REST. Treat like a password; refresh on 401.
Bootstrap clip (no JWT): Same screen → Copy prime. JSON includes gateway base URL, current vault id, and MCP resource URI knowtation://hosted/prime. After MCP connects with valid headers, the client may read resource that URI for session context and which MCP prompt IDs are registered for the role (or use prompts/list).
CLI: On the machine with the vault folder, knowtation doctor (optional --json) checks vault path readability and optional Hub env probes. See docs/RETRIEVAL-AND-CLI-REFERENCE.md and docs/TOKEN-SAVINGS.md (vault retrieval vs terminal tooling).
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.
Proposal review hints and Enrich (optional AI)
Optional helpers on the proposal screen only. They never auto-approve changes and never replace your judgment. Admins turn them on under Settings → Backup (Save proposal policy).
Review hints — Short suggestions that may appear after a new proposal (async). Treat as untrusted tips, not a gate.
Enrich — Optional button on a proposal for a short summary and label ideas when enabled.
Using them — Copy text into your evaluation comment if useful; add labels to the note yourself after approve if you agree.
Hosted — Stored with the gateway (e.g. Netlify Blob).
Greyed-out checkboxes — The host locked the feature with HUB_PROPOSAL_EVALUATION_REQUIRED, KNOWTATION_HUB_PROPOSAL_REVIEW_HINTS, or KNOWTATION_HUB_PROPOSAL_ENRICH (1/0 or true/false); change env on the server to unlock.
Models — Review hints need chat model config (Ollama, OpenAI, or Anthropic) on the Node Hub or gateway that runs the job.
Orchestrators
Any orchestrator can use the same vault and project names. Match embedding settings to this Hub so search behaves the same: Settings → Integrations → Agent Configuration (copy snippet).
Connection helpers
Copy prime — Settings → Integrations → Hub API → Copy prime. Small “where to point” JSON after the tool is connected; not your JWT.
Doctor — knowtation doctor on the machine with the vault (optional --json). See docs/RETRIEVAL-AND-CLI-REFERENCE.md and the Hosted MCP section above.
How to embed images and videos in notes — what works inline, what shows as a link, and what you need for each.
Inline images
Use standard Markdown image syntax. The image loads directly from the URL you provide.
The URL must be publicly accessible (no login required). The Hub does not proxy images — the browser fetches them directly.
Supported formats: JPEG, PNG, GIF, WebP, SVG (any format your browser can render).
To embed an image from your GitHub vault repo, use the Upload Image button in edit mode — see below.
Inline video players (.mp4, .webm, .mov)
Paste a direct video file URL on its own line. The Hub automatically renders it as a native <video> player.
https://example.com/demo.mp4
The URL must end in .mp4, .webm, or .mov (a direct link to the file, not a streaming page).
Put the URL on its own line with a blank line above and below it — or use the Insert Media URL button which handles spacing automatically.
The video must be publicly hosted (no authentication). samplelib.com has free test videos.
Adjacent content tip: If you add text or an image right after a video URL without a blank line, the video player may not render. Always leave a blank line between the video URL and whatever comes next.
YouTube, Vimeo, and other streaming links
These show as clickable links, not embedded players. Embedding streaming services requires iframes, which are blocked for security (iframe injection is a common XSS vector). Click the link to open the video in its own tab.
If you need video to play inline in the note, host the file as an .mp4 (e.g. on GitHub, Cloudflare R2, or another public host) and use the direct file URL.
Upload Image button (GitHub-backed)
In edit mode (click Edit on a note), the toolbar shows an Upload Image button when GitHub is connected. It commits the file to your vault's GitHub repo and inserts the correct Markdown.
Accepted formats: JPEG, PNG, GIF, WebP — up to 25 MB.
Files are committed to media/images/YYYY-MM/ in your repo.
Works with both public and private GitHub repos. When viewing in the Hub, images load through a secure proxy that uses your connected GitHub token — no authentication is exposed in the note source.
The raw raw.githubusercontent.com URL is stored in the note markdown, so the note remains portable (images display in any viewer for public repos; in the Hub for private repos).
If the button is not visible: make sure you are in Edit mode and GitHub is connected (Settings → Backup → Connect GitHub).
Insert Media URL button (preview & insert)
In edit mode, the Insert Media URL button opens a small dialog where you can paste any public URL and see a live preview before inserting.
Paste an image URL (https://…/photo.jpg) → a preview image appears.
Paste a direct video URL (https://…/demo.mp4) → a preview video player appears.
Click Insert to add the correct Markdown at the cursor position.
Images are inserted as ; videos are inserted as a bare URL on its own line (which renders as a player in read view).
AI assistants reading your note
When a compatible assistant reads a note through Knowtation’s MCP connection, images you linked can be passed to vision-capable models automatically. You do not configure this per note.
Technical details — MCP resource URIs
Embedded image URLs become typed image/* resources (knowtation://vault/…/image/0, …). Direct video file URLs become video/* resources. No extra Hub settings required.
Your knowledge vault accumulates activity events over time — searches, notes created, topics explored. After weeks of use, you may have thousands of events, many redundant. Memory consolidation uses an AI model to periodically clean this up automatically.
What consolidation does
Merge — redundant observations become concise facts. Thousands of raw events become hundreds of distilled knowledge entries.
Verify — stale references to renamed or deleted notes are detected and flagged, keeping your memory index accurate.
Discover — hidden connections across your topics are surfaced as new insight events (optional, uses more LLM tokens).
Quick Start — Hosted users
Open Settings → Consolidation, switch Mode to "Hosted", choose your schedule, and click Save. The Hub handles the rest — no API key needed. Your plan includes a monthly consolidation pass allowance; see the billing panel for usage.
Quick Start — Self-hosted users
Add to config/local.yaml:
daemon:
enabled: true
llm:
model: gpt-4o-mini # or any OpenAI-compatible model
Then run: knowtation daemon start
Or configure via the Hub: Settings → Consolidation → Self-Hosted (daemon) → Save.
What does it cost?
Using gpt-4o-mini, a typical pass costs $0.003–$0.009.
At every-2-hours frequency, that's roughly $0.04–$0.11/day.
Hosted plans include a monthly pass allowance; see your billing panel.
Using a local Ollama model is free.
Set a Daily Cap in Settings → Consolidation → Cost Guard to stay within budget. The daemon skips passes once the cap is reached, then resets the next calendar day.
Privacy
Consolidation sends memory events (activity summaries) to the model—not your whole vault as one file. Small text snippets from those events (for example search text or titles) can still appear in the prompt unless you tighten settings.
Hosted: see Settings → Consolidation and your plan docs. Self-hosted: you can run a local model (Ollama), turn consolidation off, or reduce what gets logged to memory events.
Technical details — encryption flags and config keys
Default lines include a capped JSON snippet of each event’s data. With memory.encrypt: true in config/local.yaml (self-hosted) or CONSOLIDATION_MEMORY_ENCRYPT=true on the hosted bridge, raw event payloads are omitted from the model prompt (timestamps and types only). See TOKEN-SAVINGS.md.
Knowtation is designed so agents and humans spend fewer tokens while still getting the right context. Use the three levers below together.
1. Compress memory (consolidation)
Recent activity is stored as many small memory events. Consolidation groups them by topic and calls the model once per topic to produce a few fact lines. Verify checks paths (no extra model call). Discover (optional, default off) adds one more model pass to suggest connections and open questions across topics.
Hosted:Settings → Consolidation → Hosted, pick a schedule, choose passes, Save. Each automated or manual run uses one consolidation pass from your plan. Discover does not consume a second pass—it runs inside the same run and uses more tokens on our side.
Self-hosted: Same screen writes config/local.yaml, or use knowtation daemon start. Details: .
2. Tiered retrieval (agents & CLI)
Do not pull huge context by default. Search with a small limit and paths or snippets only, then get-note for the one or two files that matter. Same idea for MCP tools. Reference: RETRIEVAL-AND-CLI-REFERENCE.md and AGENT-INTEGRATION.md.