User guide

The daily loop: three operations

Karpathy reduces the daily life of a knowledge base to three operations, and the interface follows them:

• Ingest. After a source lands in raw/, the agent reads it, writes a summary page, updates related pages and index.md, and appends to log.md. One source can touch a dozen pages. "Pending" means a raw/ source that no wiki page links back to yet; the banner, the Lint page and Stats all list them.
• Query. Chat in the top bar opens the right-hand panel. The agent reads index.md first to find relevant pages, then reads them and answers with page paths as citations; answers can be tables, Mermaid diagrams or Marp slides. Press Save as wiki page on a valuable answer and it becomes a page under wiki/queries/, so explorations stay in the knowledge base. At 1280 px the chat panel temporarily replaces the right rail.
• Lint. Lint in the top bar. First the deterministic checks: orphans, broken links, pages missing from the index, pending sources, log format, missing index.md or log.md; then Ask the agent for a deep lint (local AI) or Copy prompt for Cursor (remote agent) finds contradictions, stale claims and concepts that deserve their own page, and writes wiki/lint/date.md. The deterministic checks do not count as agent runs.

Discuss first, then ingest (Karpathy's preferred flow)

Karpathy says he prefers one source at a time with himself in the loop: the agent summarises, they discuss what to emphasise, and only then does it write. With a remote agent, simply have that conversation in your client before asking it to ingest. With the optional local AI, Central LLM Wiki turns it into four steps:

1. Open a pending source and press Discuss with local AI (optional) in the banner. The chat panel opens with a prepared prompt asking the agent to read the source, list the key points, explain how it relates to existing wiki pages, and propose how to file it.
2. Press Send. The agent reads the source and index.md and replies. Steer it: "point three doesn't matter", "compare this with page X", "use the argument-page format". As many rounds as you like.
3. Once the agent has replied, the pale-green bar above the input shows Compile as discussed. Pressing it starts an ingest job with the whole conversation as instructions; the agent creates the summary page, updates related pages, index.md and log.md, and progress shows above the source page.
4. You can also skip the discussion and press Auto-ingest locally (optional); the agent follows the schema rules in one pass. Either way the results land in wiki/, index.md and log.md.

Rules and templates

Templates. The Knowledge step of the setup wizard offers General, Researcher, Project manager and Book, in German and English, or an intentionally empty start. A template is schema/ rule pages + starter folders + an opening prompt for the agent; it shapes content, not the interface. Under Settings → Templates you can apply further templates (added, never overwriting), preview every page, duplicate a template as your own and save the current rules as a template.

index.md and log.md. In Central LLM Wiki they are wiki/index.md and wiki/log.md; the template creates them, the agent updates them on every ingest, and Lint checks them, so you never maintain them by hand. index.md is the content catalog, one line per page with a link and a one-line summary; log.md is append-only, each entry starting with "## [date] ingest | title", recording every ingest, filed answer and lint.

How to write rules. schema/instructions.md holds the rules for the agent in plain language; save it and the next ingest follows it. Rules can apply to the whole workspace or to General or a single project; an agent receives the layers it may read through get_instructions. Automatic ingest jobs cannot write to schema/, so the rules stay under human control. Typical rules:

• "Write wiki pages in English; give the original term on first use."
• "Paper summaries go under wiki/sources/ named by citation_key; end every page with a 'Related pages' list."
• "When sources contradict, mark both pages with '⚠ contradicts page X' instead of picking a side."

The agent got it wrong? Three levels: fix small errors directly on the page (Version history on the right restores any old version); tell the agent in the chat what is wrong and ask it to fix the page and index.md; if the same mistake keeps happening, write the rule into schema/instructions.md.

Views and tools

• Notes. Read and edit (Markdown with live preview, Ctrl/⌘+S to save, insert or paste images); backlinks and version history on the right, any version viewable and restorable. If a page is edited from both sides at once, the later save receives the current version and keeps its own draft.
• Graph. raw grey, wiki celadon, schema amber; links are written by the agent during ingest, not extracted from sources. Drag, zoom, play the timeline to watch the base grow; Filter narrows to a layer or folder, searches titles, hides isolated pages, or focuses on the current page and one or two hops of neighbours.
• Table. Lists each page's front-matter (the property block at the top of a page: authors, year, tags…) as a table with filter, sort, group and CSV copy. The Researcher template presets it as a literature table.
• Search. The top-bar search matches substrings of titles and bodies; it is also the MCP search_notes tool.
• Projects. The project selector switches between General and the projects you can access; Settings → Projects creates, edits, archives and restores projects. Archiving keeps notes and history but revokes share links.
• Share. Share on a page creates a public read-only link to that one page; Stop sharing invalidates it immediately.
• Import. ＋ Add has four tabs: write, paste URL, upload file (PDF, Word, HTML, Markdown, plain text, plus .bib / CSL-JSON bibliography files, one entry per page), paste text. Paper URLs get authors, year, venue and DOI filled in; ordinary pages keep title, URL and fetch time; images inside pages are stored as attachments. Pages that need JavaScript to show their content are fetched with the built-in browser; sites behind bot checks or logins still cannot be fetched, so paste the text or upload a PDF.
• Bibliography and citations. Write [@citation_key] in a wiki page and it renders as (Author, Year) linked to the source, with an automatic reference list; the exported Markdown and .bib work with pandoc.
• Stats. Pages per layer, source types, pages per day, an editing heatmap, and agent tokens and cost per day.

REST API (an MCP credential as API key)

To read and write from scripts, cron jobs, Claude Code hooks or any program without going through MCP, use an MCP credential from Settings → Connect an agent as an API key. Send it as Authorization: Bearer; no cookie or Origin header is needed. The same grants apply: a Reader can only send GET requests, and writes need a Librarian with a write grant for the target. Select the target with project_key=… or scope=general; reads also accept scope=all, which covers only content the credential can already read. Revoking the credential disables both uses; versions written this way are attributed to mcp:<label>. Administration endpoints (members, credentials, templates, AI settings, chat, ingest, lint) remain browser-session only. The full reference is in docs/rest-api.md.

# Set this to the public URL of your instance.
APP_URL=https://orakel.marcobartsch.de
# tree of a project (three layers plus the pending list)
curl -H "Authorization: Bearer $TOKEN" "$APP_URL/api/notes/tree?project_key=research"
# read one page in General
curl -H "Authorization: Bearer $TOKEN" "$APP_URL/api/notes?scope=general&path=wiki/index.md"
# create (201); 409 if the path exists (Librarian)
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"project_key":"research","path":"wiki/notes/idea.md","content":"# Title\n\nBody"}' "$APP_URL/api/notes"
# update with the optimistic lock (a stale if_version returns 409)
curl -X PUT -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"project_key":"research","path":"wiki/index.md","content":"...","if_version":3}' "$APP_URL/api/notes"
# search everything this credential can read
curl -H "Authorization: Bearer $TOKEN" "$APP_URL/api/search?scope=all&q=keyword"
# upload a source file into raw/sources/ (Librarian; the destination is never inferred)
curl -X POST -H "Authorization: Bearer $TOKEN" -F 'file=@./paper.pdf' "$APP_URL/api/import/file?project_key=research"
# export the readable content (zip)
curl -H "Authorization: Bearer $TOKEN" -o wiki.zip "$APP_URL/api/export?scope=all"