Troubleshooting

Files Not Processing

You dropped a file into INGEST/ but nothing happened — it just sits there.

Check the file watcher

On the Home page, look at the Vault Status section. The watcher indicator should show Running. If it shows Stopped or Error:

• Verify the vault directory exists on disk
• Verify the INGEST/ subfolder exists inside it
• Check you have read/write permissions on both folders
• Try clicking Rebuild Index to restart the watcher

Check the file format

The AI enrichment pipeline only processes .md files (Markdown). If you dropped a PDF, DOCX, or XLSX, it should be auto-converted first. If that conversion fails, the file stays in INGEST/ without becoming a .md file and won't be processed.

Non-supported formats (.pptx, .odt, etc.) are moved to the vault but won't receive AI enrichment. Convert them to PDF or plain text first.

Check API settings

Go to Settings → AI Provider and click Test Connection. If it fails:

• Verify the endpoint URL is correct and ends with /v1
• Re-enter your API key (it may have expired)
• Make sure you have a model selected

Check for failed files

On the Home page → Queue → Failed Files. Any files that encountered errors during AI processing appear here. You can retry them individually or in bulk.

Quick Notes Hotkey Not Working

macOS: Accessibility permission required

The ⌥ + ⌥ global hotkey requires macOS Accessibility permission to detect key presses system-wide.

Windows / Linux

The Alt + Alt hotkey should work without any special permissions. If it doesn't:

• Check whether another application has registered the same hotkey
• Try running Wikori as administrator temporarily to test
• On Linux, check if your desktop environment is intercepting Alt key combinations

API Errors

Office File Extraction Failing

Your PDF, DOCX, or XLSX file landed in the vault but wasn't converted to Markdown and wasn't enriched.

• Password-protected files cannot be extracted. Remove the password before dropping into INGEST/.
• Corrupted files will fail silently. Try opening the file in its native app to verify it's intact.
• Scanned PDFs (images of text) have no text layer for extraction. Run OCR on them first using Preview, Adobe Acrobat, or an online tool.
• Unsupported formats (PPTX, ODT, ODS, ODP): convert to PDF or DOCX manually, then re-ingest.

Encryption & Settings Issues

API token not working after moving to a new machine

Wikori encrypts your API key and email credentials using a key derived from your machine's hardware ID. Encrypted credentials cannot be decrypted on a different machine — this is a security feature.

If you've moved Wikori to a new computer or replaced your hardware, simply re-enter your API key and email password in Settings. They will be re-encrypted for the new machine automatically.

Settings file location

MCP Server Issues

Agent can't connect to the server

• Verify the server is running: the status badge on the Connect page should show Running
• Check the port — default is 8787. If something else is using port 8787, the server will fail to start.
• Make sure your agent config uses http://127.0.0.1:8787 (not localhost, which can resolve differently)
• Verify the AUTH_TOKEN or Authorization header matches your MCP secret exactly

Server starts but returns no results

• Make sure you have at least one vault configured with a directory
• Process some files first — empty vaults return empty results
• Rebuild the index on the Home page to refresh the index

Knowledge Map is Empty

The graph shows "No entities found" even though you have files in your vault.

• Go to the Home page and click Rebuild Index. The graph only updates after a rebuild.
• Make sure your files have been processed by the AI pipeline (they should have YAML frontmatter at the top). Unprocessed files won't appear in the graph.
• Entities are extracted by the AI model. If your model returns minimal metadata, few nodes may appear. Consider using a more capable model.

Agent Memory Issues

Agent observations not appearing in vault

After the agent calls memory_save, the file is written but may not appear immediately in search results.

• Memory entries are indexed on the next index rebuild. Go to Status and click Rebuild Index to force an immediate update.
• Check the vault directory for a file named MCP_{timestamp}_{type}.md — if it exists, the write succeeded and the issue is only with indexing.
• If the file doesn't exist, check that the MCP server is running and the agent has write access to the vault directory.

SCHEMA.md is missing or out of date

SCHEMA.md is generated automatically on every wiki rebuild. If it's missing or stale:

• Click Rebuild Index on the Home page. The schema regenerates as part of every rebuild.
• If the file exists but appears empty, your vault may have no entries with sufficient confidence scores. Process at least a few files through the AI pipeline first.
• The Ground Truth section of the schema only appears when entries with confidence ≥ 0.9 and source_authority: high exist. These fields come from AI enrichment — if your model is returning low confidence scores, consider switching to a more capable model in Settings.

Smart search returning unexpected rankings

If memory_smart_search returns results in an order that seems wrong:

• Check the source_authority field in the returned metadata — entries ranked lower may have authority: low which applies a 0.75× score penalty.
• Source authority is set during AI enrichment. If all your entries have authority: medium (the default), differentiation comes entirely from confidence scores.
• Agent-written observations (memory_save) default to source_type: observation. Their authority weight depends on the confidence score the agent supplies — pass a high confidence value for decisions you want surfaced prominently.

memory_consolidate returns nothing to consolidate

The consolidation tool groups observations by 24-hour windows. If it returns no suggestions:

• Ensure there are memory_tier: working entries in the vault. Use memory_sessions to check what working memories exist.
• Consolidation requires at least 2 working-tier entries within the same 24-hour window. Single entries are not consolidated.
• If entries exist but consolidation still returns nothing, rebuild the wiki so the index is current.

Still Stuck?

If you've worked through this guide and the issue persists, you can reach the Wikori team at contact@wikori.com. Please include:

• Your operating system and Wikori version
• A description of what you expected vs. what happened
• The file type and approximate size (if it's a file processing issue)
• Any error messages shown in the app