name: knowtation description: Query and search a personal knowledge vault (Obsidian-style) via the knowtation CLI or MCP. Use when the user wants to find notes, get note content, list notes by folder/tag, trigger re-indexing, write, export, or import from other platforms. CLI with subcommands; optional MCP server (knowtation mcp) for runtimes that speak MCP. Knowtation = know + notation (notation for what you know). compatibility:

• Cursor
• Claude Code
• Any runtime that can run a CLI and read this skill (e.g. Windsurf, GNO, custom) allowed-tools: []

Knowtation — Use the knowledge vault via CLI or MCP

Knowtation (know + notation) is a personal knowledge and content system. The vault is Markdown (Obsidian-style); search is semantic (vector store). Use the knowtation CLI for terminal and agent environments, or the MCP server (knowtation mcp) when the runtime speaks MCP (Cursor, Claude Desktop). See docs/AGENT-ORCHESTRATION.md for MCP config.

When to use this skill

• User asks to search their notes, find something in their vault, or get content of a specific note.
• User wants to list recent or filtered notes (e.g. from inbox, by project, or by tag).
• User wants to re-index the vault (after adding or changing notes).
• User wants to create or update a note (write), export notes to a file/dir, or import from ChatGPT, Claude, Mem0, MIF, markdown, or audio/video.

Commands (run in project root or where knowtation is installed)

• Search (semantic):
  knowtation search "your query"
  Optional: --json, --folder <path>, --project <slug>, --tag <tag>, --since, --until, --chain, --entity, --episode, --order date|date-asc, --limit <n>, --fields path|path+snippet|full, --snippet-chars <n>, --count-only.

• Get one note:
  knowtation get-note <vault-relative-path>
  Optional: --body-only, --frontmatter-only, --json. Example: knowtation get-note vault/projects/default/notes.md.

• List notes:
  knowtation list-notes
  Optional: --folder, --project <slug>, --tag <tag>, --since, --until, --chain, --entity, --episode, --limit, --offset, --order date|date-asc, --fields path|path+metadata|full, --count-only, --json.

• Re-index vault:
  knowtation index
  (Runs the indexer: vault → chunk → embed → vector store. Optional: --json for { ok, notesProcessed, chunksIndexed }. Requires Qdrant and embedding provider in config.)

• Write note:
  knowtation write <path> with optional --stdin, --frontmatter k=v, --append, --json. Inbox and non-inbox; AIR may apply to non-inbox (see spec).

• Export:
  knowtation export <path-or-query> <output-dir-or-file> with optional --format, --project, --json. Records provenance; AIR when enabled.

• Import (from other platforms):
  knowtation import <source-type> <input> with optional --project, --output-dir, --tags, --dry-run, --json. Source types: chatgpt-export, claude-export, mem0-export, notebooklm, gdrive, mif, markdown, audio, video. See docs/IMPORT-SOURCES.md.

Introspection

To see current usage and options, run:

• knowtation --help
• knowtation search --help

Output is JSON when you pass --json, so you can pipe to jq or parse in code.

Tiered retrieval (token-optimal)

To minimize token use: (1) Use list-notes or search with a small --limit and --fields path or default path+snippet; (2) From the paths or snippets, pick one or two notes; (3) Call get-note only for those paths. Token levers: --fields (path | path+snippet | full for search; path | path+metadata | full for list-notes), --snippet-chars <n>, --count-only; for get-note use --body-only or --frontmatter-only when you need only one part. Use --count-only when you only need "how many?" before deciding to run a full search. See docs/RETRIEVAL-AND-CLI-REFERENCE.md for all levers.

Config

The CLI reads vault path and vector store from config/local.yaml or env vars (KNOWTATION_VAULT_PATH, QDRANT_URL). Vector store is Qdrant (sqlite-vec available when so configured; see config and README). Do not commit secrets; ensure the project has a vault and has been indexed at least once before searching.