AI Developer Documentation

Connect MCP clients, skills, and local agents

Knight Note can act as a local AI memory vault for Claude Code, Claude Desktop, Cursor, OpenAI Codex, Gemini CLI, OpenCode, and other MCP-compatible tools. The app exposes an Obsidian-readable Markdown mirror for agent context while keeping JSON as the canonical sync-safe source of truth.

1. Prepare the vault

Create an AI Memory vault during onboarding, or open Settings > AI Search and enable the AI Markdown Mirror for an existing vault. AI Memory vaults enable the mirror automatically.

  • Mirror folder: `AI Markdown Mirror/` inside the vault folder.
  • MCP map: `.knightnote/ai-map.json` inside the vault folder.
  • Canonical data: `note_*.json`, `folders.json`, `vault.json`, and `.knightnote/` metadata.

2. Pick a permission preset

Use the smallest preset that fits the agent job. Every preset can still read the Markdown mirror; the difference is which JSON-backed write tools Knight Note exposes to the MCP client.

Read-only

Search, list, read, inspect frontmatter, read sections, find backlinks, list recent notes, inspect deleted notes, and view vault stats. No JSON writes.

Append-only

Everything in read-only, plus append to an existing note, research note, or daily note. No new notes, moves, metadata edits, wiki-link edits, deletes, or restores.

No destructive tools

Everything except soft delete. Agents can create notes, clip sources, append content, update metadata, move notes, append wiki links, and restore deleted notes.

Full read/write

All JSON-aware read and write tools, including soft delete. Best for trusted local agents and maintenance workflows.

Preset read-only
Allowed write tools

None.

Typical use

Research, recall, summarization, citations, and project context.

Preset append-only
Allowed write tools

append_to_note, append_to_daily_note, append_to_research_note.

Typical use

Meeting notes, cited research updates, daily logs, durable memory capture, and safe agent journaling.

Preset no-destructive
Allowed write tools

save_note, clip_url, create_source_card, create_note, append_to_note, append_to_daily_note, append_to_research_note, update_frontmatter, move_note, append_wiki_link, restore_deleted_note.

Typical use

Organizing AI memory, clipping cited sources, and building a research inbox without allowing the agent to delete notes.

Preset full-write
Allowed write tools

All write tools, including soft_delete_note.

Typical use

Trusted cleanup, refactoring, and full local memory maintenance.

3. AI capture and clipping tools

Trusted MCP clients can now save research directly into Knight Note while preserving source provenance. These tools write canonical Knight Note JSON first, then refresh the Markdown mirror so the captured material is immediately available to Obsidian-style readers and future AI sessions.

save_note

Create a new AI-authored research or memory note. Supports title, Markdown body, optional source URL, tags, and a target folder path. Defaults to Research Inbox.

clip_url

Create a clipped source note with URL, timestamp, summary, captured content, domain tag, and duplicate detection. Defaults to AI Clips.

create_source_card

Create a compact citation card with URL, summary, and excerpt for later review. Defaults to Research Inbox/Sources.

append_to_research_note

Append cited Markdown to an existing research note using a note ID or mirror path. This is available in append-only mode for safer agent workflows.

append_to_daily_note

Append a dated agent journal entry, creating the note when needed. Agent-created daily notes are stored as visible notes in Daily Notes.

Example: let an agent save a clipped source

clip_url({
  "url": "https://example.com/research",
  "title": "Research source",
  "summary": "Short AI-written summary.",
  "markdown": "Readable page excerpt or notes gathered by the agent.",
  "tags": ["research", "project-x"]
})

Example: append evidence to an existing note

append_to_research_note({
  "path": "Research Inbox/Project X.md",
  "heading": "New evidence",
  "sourceUrl": "https://example.com/report",
  "markdown": "The relevant finding, with the agent's concise interpretation."
})

4. Commands from Knight Note settings

Settings > AI Search generates exact commands for your installed app path, vault path, and selected preset. The examples below use placeholders. Replace them with the copied values from the app.

Preset stdio commands

Use one of these values after --knightnote-mcp-preset.

"C:\Path\To\Knight Note.exe" --knightnote-mcp "C:\Users\you\Knight Note Vaults\ai_vault" --knightnote-mcp-preset "read-only"
"C:\Path\To\Knight Note.exe" --knightnote-mcp "C:\Users\you\Knight Note Vaults\ai_vault" --knightnote-mcp-preset "append-only"
"C:\Path\To\Knight Note.exe" --knightnote-mcp "C:\Users\you\Knight Note Vaults\ai_vault" --knightnote-mcp-preset "no-destructive"
"C:\Path\To\Knight Note.exe" --knightnote-mcp "C:\Users\you\Knight Note Vaults\ai_vault" --knightnote-mcp-preset "full-write"

Claude Code preset commands

Use the server name that matches the preset so it is clear which permissions are active.

claude mcp add knight-note-read-only -- "C:\Path\To\Knight Note.exe" --knightnote-mcp "C:\Users\you\Knight Note Vaults\ai_vault" --knightnote-mcp-preset "read-only"
claude mcp add knight-note-append-only -- "C:\Path\To\Knight Note.exe" --knightnote-mcp "C:\Users\you\Knight Note Vaults\ai_vault" --knightnote-mcp-preset "append-only"
claude mcp add knight-note-no-destructive -- "C:\Path\To\Knight Note.exe" --knightnote-mcp "C:\Users\you\Knight Note Vaults\ai_vault" --knightnote-mcp-preset "no-destructive"
claude mcp add knight-note-full-write -- "C:\Path\To\Knight Note.exe" --knightnote-mcp "C:\Users\you\Knight Note Vaults\ai_vault" --knightnote-mcp-preset "full-write"

Claude Desktop JSON template

Paste into a Claude Desktop MCP server configuration and set the final argument to read-only, append-only, no-destructive, or full-write.

{
  "mcpServers": {
    "knight-note-read-only": {
      "command": "C:\\Path\\To\\Knight Note.exe",
      "args": [
        "--knightnote-mcp",
        "C:\\Users\\you\\Knight Note Vaults\\ai_vault",
        "--knightnote-mcp-preset",
        "read-only"
      ]
    }
  }
}

Cursor, Codex, Gemini, and OpenCode JSON template

Use in MCP clients that accept an mcpServers JSON block. Change the server name and preset together.

{
  "mcpServers": {
    "knight-note-append-only": {
      "command": "C:\\Path\\To\\Knight Note.exe",
      "args": [
        "--knightnote-mcp",
        "C:\\Users\\you\\Knight Note Vaults\\ai_vault",
        "--knightnote-mcp-preset",
        "append-only"
      ]
    }
  }
}

Legacy full-write command

Older builds used --knightnote-mcp-write. New setups should prefer explicit presets.

"C:\Path\To\Knight Note.exe" --knightnote-mcp "C:\Users\you\Knight Note Vaults\ai_vault" --knightnote-mcp-write

5. OpenAI Codex project memory plugin

The Knight Note Codex plugin is for Codex users who want project memory without manually wiring vault paths. It launches a local auto-discovery MCP wrapper, finds active AI Markdown Mirror vaults, and gives Codex project-memory tools that prefer the newest AI Vault.

Auto-discovery

knightnote-mcp-auto.cjs scans common Knight Note roots, finds vaults with AI Markdown Mirror/ and .knightnote/ai-map.json, and exposes list_vaults.

Project memory

find_project_memory, read_project_memory, and search_project_memory let Codex load repo context by project name instead of searching every note manually.

Append-only updates

The optional knight-note-append server exposes append_project_memory for controlled outcome logging. Codex still asks for approval before using it.

GitHub marketplace install

Add the Knight Note Codex marketplace from GitHub, then open Codex Plugins, search for Knight Note, and install it.

Install command

codex plugin marketplace add https://github.com/Sorterx/Vault.git --ref codex-plugin-marketplace

Plugin MCP config

{
  "mcpServers": {
    "knight-note": {
      "command": "node",
      "args": [
        "C:\\Path\\To\\Knight Note\\scripts\\knightnote-mcp-auto.cjs"
      ]
    },
    "knight-note-append": {
      "command": "node",
      "args": [
        "C:\\Path\\To\\Knight Note\\scripts\\knightnote-mcp-auto.cjs",
        "--permission-preset",
        "append-only"
      ]
    }
  }
}

Recommended Codex prompt

Use Knight Note first. Read project memory for my repo, then proceed.
When finished, append a short outcome to the project memory.

6. Skill and agent guidance

  • Start read-only for research, summarization, and memory recall.
  • Use append-only for durable memory capture and daily-note workflows.
  • Use no-destructive when agents should create folders, save article sets, clip web sources, or create source cards without delete access.
  • Use dry-run before create, append, metadata, folder, wiki-link, delete, or restore operations.
  • Ask agents to include source URLs when saving externally sourced claims.
  • Ask agents to cite note titles or mirror paths when answering from memory.
  • Never create notes by writing Markdown files directly into `AI Markdown Mirror/`; use MCP write tools so Knight Note creates canonical JSON and refreshes the mirror.
  • Never edit `note_*.json`, `folders.json`, `vault.json`, or `.knightnote/` directly from an agent.