Eugen Ullrich / OKF Hub
Guide & FAQ

Guide & FAQ

Turn individual documents into a searchable, visual knowledge base that you can query with AI. This guide explains how to upload a ready-made OKF bundle, import content from Notion, Obsidian, Logseq, or Confluence, edit concepts, read the Knowledge Graph, and chat with your knowledge using source references.

In short: sign in, upload your knowledge or start with the demo, select a source, and work in three views: Concept Library, Knowledge Graph, and AI RAG Assistant.

1. What is OKF Knowledge Hub?

OKF Knowledge Hub is a workspace for knowledge stored in Open Knowledge Format. It combines four jobs in one tool:

  1. Import and structure: turn ready-made OKF files or ZIP exports from existing knowledge systems into individual concepts.
  2. Read and maintain: search, filter, open, edit, mark, export, or delete concepts.
  3. Understand relationships: use an interactive graph to inspect categories, shared tags, topic clusters, and weakly connected content.
  4. Query the knowledge: ask a RAG assistant questions about the selected knowledge base and open the OKF concepts used for the answer.

The Hub does not automatically publish your content and is not a content management system. Uploading a knowledge base does not by itself make it visible in Google or AI search. The Hub helps you manage knowledge in a portable structure, analyze it, and use it in controlled AI queries.

2. Quick start: your first answer in five steps

Step 1: Sign in with Google

Select “Sign in” or “Google Login” and choose your Google account. The Hub uses the Google account ID to associate your private knowledge bases with your account. Your name, email address, and profile picture are used for account display and management.

Without signing in, you can view the public landing page. The app, demo database, private uploads, and private queries require sign-in.

Step 2: Start with the demo or upload your own data

If you do not have an OKF yet, choose “Load demo data.” The demo is added to your account as a knowledge base and does not count against the monthly upload limit.

For your own content, choose “Upload OKF.” You then have two options:

  • Ready-made OKF bundle: a structured .zip, .md, or .json file.
  • Import from another service: a ZIP export from Notion, Obsidian, Logseq, or Confluence.

Step 3: Select a knowledge source

Each main view has a “Source” field. Select the knowledge base you want to use. Concept Library, Knowledge Graph, and AI RAG Assistant each use the source selected in that view.

After an upload, the Hub normally selects the newest knowledge base by default. Check the selection before searching or sending an AI query.

Step 4: Review and structure your content

Open a few concepts in Concept Library. Review the title, description, type, category, tags, body, and original source link where available. Good metadata improves filters, graph relationships, and retrieval.

Step 5: Ask a question and check the sources

Open AI RAG Assistant, choose a source and model, and ask a focused question. Open the source references in the response to inspect the underlying OKF content inside the Hub.

3. What can I upload?

Ready-made OKF files

The Hub supports:

  • .zip — an archive containing multiple Markdown files;
  • .md — one concept with optional YAML frontmatter;
  • .json — one concept object or a list of structured concept objects.

The maximum upload size is 20 MB per file.

For ZIP bundles, the Hub reads Markdown files. System files and macOS resource files are skipped. Aggregate files named README.md, INDEX.md, and okf.md are not imported as separate concepts.

Recommended OKF concept structure

---
type: "Guide"
title: "Concept title"
description: "A short, self-contained summary of the content."
resource: "https://example.com/original-source"
domain: "example.com"
category: "topic-area"
tags: ["tag-one", "tag-two"]
word_count: 1200
---

# Concept title

The complete content in Markdown.

The most useful fields in the Hub are:

  • title: a unique, understandable title;
  • description: a short summary that makes sense on its own;
  • type: for example Article, Guide, Tool, or CaseStudy;
  • category: the primary topic area used in the Knowledge Graph;
  • tags: specific terms used by filters and similarity links;
  • resource: the original source URL, where available;
  • body: the actual knowledge content.

A basic Markdown document without complete frontmatter can be read, but missing metadata receives generic defaults and should be completed in the editor.

What should I check before uploading?

  • Does every file have a unique title?
  • Is the description specific and more useful than a repetition of the title?
  • Are categories and tags consistent?
  • Do internal and external links work?
  • May the content be stored on the server and, when using AI chat, shared with the named AI services?
  • Does the bundle contain passwords, API keys, or other secrets?
  • Do you have the necessary rights to the content?

4. Importing from Notion, Obsidian, Logseq, or Confluence

In the upload dialog, choose “Import from another service” and upload the relevant ZIP export. The source can be detected automatically or selected manually.

Notion

Export the required area as Markdown & CSV and upload the ZIP. Markdown and HTML pages become concepts. Rows from CSV databases become individual Collection Item concepts.

Obsidian

Compress the vault folder as a ZIP. Markdown files, YAML metadata, tags, and wiki links are processed. The technical .obsidian folder is ignored.

Logseq

Export the graph as Markdown and upload a ZIP containing pages/ and, where relevant, journals/. Journal files become Journal Entry concepts. Simple block references are not preserved as interactive references in the current version.

Confluence

Export the space as HTML and upload the ZIP. The importer converts basic headings, paragraphs, lists, links, code blocks, and emphasis to Markdown. Confluence labels are used as tags where they can be detected.

What does the importer preserve?

  • page titles and text;
  • detectable tags or labels;
  • folder structure as OKF paths and categories;
  • local Markdown links and wiki links when the destination is unambiguous;
  • simple existing metadata such as type or source URL;
  • an automatically generated description from the first suitable paragraph.

Current import limitations

  • The importer focuses on text-based content.
  • Images, PDFs, and other attachments are not stored as separate content.
  • Complex Confluence layouts, macros, tables, or embedded apps may be simplified.
  • Internal links that cannot be resolved are counted as broken links in the import result.
  • If automatic source detection fails, select the source manually.
  • An import counts toward the monthly upload limit.

After import, the Hub reports the number of concepts created, links rewritten, and broken links found. Review a sample of the imported structure and content before relying on it.

5. Using Concept Library

Concept Library is the readable and editable view of your knowledge base.

Search

The global search covers titles, descriptions, and tags. Use ⌘K on macOS or Ctrl+K on Windows and Linux to move focus directly to search.

Search does not currently provide reliable full-text matching across entire article bodies. Use descriptive titles, summaries, and tags.

Filter

Filter the library by the OKF types present in the selected source. The tag cloud shows the twelve most frequent tags in that knowledge base. Select a tag to apply or remove the filter.

Sort

  • relevance or original order;
  • title A–Z;
  • word count descending;
  • word count ascending.

Up to 24 concepts are shown first. Select “Load more concepts” to display additional entries.

Read a concept

Select a card to open the reader. It shows:

  • type, domain, word count, and estimated reading time;
  • verification state;
  • tags;
  • rendered Markdown content;
  • the original source link, if present;
  • edit, export, and delete actions.

Reading time is estimated at 200 words per minute.

6. Editing, verifying, exporting, and deleting concepts

Edit

The reader lets you change title, description, type, category, tags, and the Markdown body. Saving updates the encrypted knowledge base, recalculates word count, and rebuilds the semantic search index.

Mark as verified

“Mark as verified” adds a timestamp and a marker based on your user profile, such as human:eugen.

This is a self-declared review marker inside your knowledge base. It is not external certification and does not independently confirm factual accuracy, freshness, rights clearance, or legal approval.

Export one concept

“Export as OKF” downloads the open concept as a Markdown file with OKF frontmatter. If you export directly from the editor, the downloaded file includes the current editor values even if they have not yet been saved back to the bundle.

The current Hub exports individual concepts. A complete bundle download is not currently available in the interface.

Delete one concept

Deleting a concept permanently removes it from the selected knowledge base and saves the reduced version. This cannot be undone in the app.

Delete a complete knowledge base

Open the “My OKF” dashboard from your profile and delete the required bundle. This removes the stored encrypted file, its vector index, and bundle metadata.

Deleting a concept or bundle does not restore upload quota already used during the month.

7. Reading and controlling the Knowledge Graph

The Knowledge Graph turns categories and shared tags into an interactive map. It is a navigation and analysis aid, not an automatically generated expert ontology.

What the elements mean

  • Circles represent articles or concepts.
  • Diamonds represent categories.
  • Colors identify categories.
  • Solid lines connect concepts to their category.
  • Dashed lines connect concepts that share tags.
  • Colored areas outline visible category clusters.
  • Larger nodes have more connections.

The dashed links labelled “similarity” are based on shared tags. They are not a language-model judgment and do not guarantee subject-matter similarity.

Controls

  • Select a node: focus the node and its neighborhood up to two connection levels.
  • Drag a node: temporarily reposition it.
  • Scroll or use the trackpad: zoom in or out.
  • Select empty space: clear the current focus.
  • Search: highlight nodes whose title contains the query.
  • Category legend: show or hide whole categories.
  • Hierarchical: show or hide category links.
  • Similarity: show or hide shared-tag links.
  • Link density: require a selected minimum number of shared tags for a similarity edge.
  • Clusters: show or hide colored category areas.
  • Reset view: clear query, focus, and hidden categories.

Detail card

For a concept, the side card shows description, word count, reading time, connection count, tags, related articles, and the original source where available. For a category, it lists up to twelve concepts.

Why are some concepts missing?

For performance, the graph shows up to 800 concepts. In larger knowledge bases, it prioritizes concepts with more tags. Concept Library remains the authoritative complete content list.

What does “isolated” mean?

An isolated concept has no similarity link through shared tags. This may indicate a knowledge gap, but it can also be caused by missing or inconsistent tags. Review metadata before drawing a content conclusion.

8. Using AI RAG Assistant

RAG means Retrieval-Augmented Generation. Before each response, the Hub retrieves relevant concepts from the selected knowledge base and sends excerpts together with your question to the selected AI model.

Ask a useful question

  1. Select the correct Source.
  2. Select a model.
  3. Ask a focused question with context and a clear desired output.
  4. Open and check the sources used in the answer.

Examples:

  • “Which three rules does our policy specify for approving new content?”
  • “Summarize the differences between topic A and topic B in a table.”
  • “Which concepts discuss technical SEO problems, and what actions do they recommend?”
  • “This question is not answered by the knowledge base. What information is missing?”

Available models

  • Google Gemini 2.5 Flash;
  • DeepSeek V3;
  • Llama 3.3 70B.

Model names and availability may change. Gemini is the default named in the heading, but the actual request uses the model selected in the model field.

How are relevant sources selected?

For private bundles, the server first attempts semantic retrieval using locally computed multilingual embeddings. If the semantic index is not ready, it automatically falls back to weighted keyword search. Titles and descriptions receive more weight than body text.

The model receives a small selection of relevant concepts, not the full bundle by default. Focused questions and strong metadata therefore work better than very broad prompts.

How do citations work?

The model is instructed to use numbered OKF sources only. The Hub turns those numbers into clickable references. Selecting one opens the cited OKF excerpt in the internal reader. The AI response does not automatically create external URLs.

If the selected OKF content does not answer a question, the assistant is instructed to say so rather than add outside knowledge.

Can the assistant still be wrong?

Yes. RAG reduces unsupported responses but cannot eliminate them. Errors can come from:

  • incomplete or outdated source content;
  • ambiguous questions;
  • selecting the wrong bundle;
  • retrieval failing to select the best passage;
  • passages being interpreted or cited incorrectly;
  • limitations of the selected model.

Treat AI output as a working draft. Open the cited concepts and verify important claims in the full content.

What is sent to the AI service?

For each chat request, your question and relevant excerpts from the selected OKF are sent to OpenRouter and then to the selected model provider. Do not use chat for content that must not be shared with those services.

Uploading, reading, filtering, editing, or viewing the graph does not by itself send an AI chat request.

Chat history

The Hub stores the latest 25 questions and answers per signed-in user locally in the browser. Reopening an entry displays the saved answer without sending a new model request. “Clear history” removes that local history from the current browser profile. History is not automatically synchronized across devices or browsers.

9. Privacy and security

Sign-in and ownership

Google Sign-In provides the Hub with your Google account ID, name, email address, and profile picture. A signed session token is stored in browser local storage. The session currently lasts up to 30 days unless it is ended or removed earlier.

Encryption at rest

Uploads and semantic vector indexes are encrypted with AES-256-GCM before persistent storage. The server derives the key from a master key and the owner’s stable Google account ID. API endpoints also check whether the signed-in user owns the requested bundle.

This protects stored files from straightforward plaintext access in the storage backend and separates bundles by user account. It is not end-to-end or zero-knowledge encryption: the server application holds the required key material and decrypts content for authorized functions.

Processing in server memory

The server decrypts a bundle during an authorized session to provide library, graph, editing, semantic search, and RAG functions. Decrypted concepts may be held in a bounded in-memory cache to improve performance.

Local semantic search

Embeddings are computed by a local model on the server. Content is not sent to an external embedding service to create the vector index. The index is stored encrypted.

Third-party AI processing

Only when you use AI RAG Assistant are your question and selected relevant excerpts sent to OpenRouter and the chosen model provider. Review the privacy terms and conditions of the involved providers before processing confidential content.

Deletion and retention

Your OKF and vector indexes remain stored until you delete the bundle. To delete the complete account and related data, contact [email protected].

Sensitive content

Do not upload passwords, private keys, access tokens, or data that may not be stored on the server. Do not use AI Assistant for content that may not be transmitted to OpenRouter and the selected model provider.

See the Privacy Policy for further details.

10. Free access and limits

The service is currently free. By default, each user has 3 uploads or imports per calendar month. The value shown in the app is authoritative because the server-side limit can be configured.

The upload quota includes:

  • uploading a ready-made .zip, .md, or .json bundle;
  • importing a ZIP export from Notion, Obsidian, Logseq, or Confluence.

The upload quota does not include:

  • loading the demo database;
  • reading, searching, or filtering concepts;
  • using the Knowledge Graph;
  • editing or deleting existing concepts;
  • exporting one concept;
  • sending questions to RAG Assistant.

The quota resets at the start of a new month. Deleting a previously uploaded bundle does not reduce usage for the current month.

Other current technical limits:

  • 20 MB maximum per uploaded file;
  • up to 800 concepts visible in the Knowledge Graph;
  • up to 25 locally stored chat exchanges per user and browser;
  • import focuses on supported text files; attachments are not retained.

11. Troubleshooting

“Please sign in with Google first”

Open the login dialog and sign in. If sign-in does not complete, check whether your browser blocks pop-ups, third-party scripts, or Google Identity Services.

My file is not accepted

Check file type and size. A ready-made OKF accepts .zip, .md, and .json. Import from another service accepts ZIP only. The file must be 20 MB or smaller.

“No OKF concepts found in the file”

A ZIP must contain importable Markdown files. An archive containing only images, PDFs, or attachments is not sufficient. Also check whether it contains only README.md, INDEX.md, or okf.md, because those aggregate files are skipped.

The import source was not detected

Select Notion, Obsidian, Logseq, or Confluence manually in the upload dialog. Confirm that the ZIP came from that product’s export and retains its original folder structure.

Some links are broken after import

The importer can only rewrite targets that it can identify unambiguously by filename or page title. Check renamed pages, duplicate titles, absolute local paths, and links to content that was not exported.

Search does not find a term in the article body

Library search uses title, description, and tags. Add the term to a useful description or tag. Use RAG Assistant for questions about full content.

The graph does not show all concepts

The graph is capped at 800 concepts. Hidden categories, active search, focus, or a high link-density setting can also visually suppress elements. Reset the view and use Concept Library for the complete list.

A concept appears isolated

Check whether it has consistent tags. Graph similarity links come from shared tags. An isolated node does not automatically mean the topic is unrelated.

The assistant cannot find information that exists

Check the selected source first. Ask using terms from the relevant title, description, or content. Split broad requests into smaller questions. If needed, improve the concept’s title, description, and tags, then allow a short time for the semantic index to rebuild.

The answer contains no sources

The Hub lists only sources that the model actually cited by number. Ask a more focused question and do not rely on an important uncited response.

The response does not include an external URL

This is intentional. AI citations open the relevant OKF concept inside the Hub. If the concept contains an original source URL, you can open it from Concept Library or Knowledge Graph.

My recent questions are missing on another device

History is stored in local browser storage and is not synchronized with your account.

I deleted a concept or bundle by mistake

Deletion cannot be undone in the app. Upload an existing backup again. A new upload counts toward the monthly limit.

12. FAQ

What does OKF mean?

OKF stands for Open Knowledge Format. In the Hub, a concept combines Markdown content with structured metadata such as title, description, type, category, tags, and source. The same content can then be read by people, analyzed in the graph, and used for AI retrieval.

Do I need to know OKF or YAML?

No. You can import an export from a supported knowledge service and maintain the generated concepts in the visual editor. A basic understanding of metadata is still useful when creating clean, reusable bundles.

Can I try the app without my own data?

Yes. Sign in with Google and load the demo database. Demo data does not count toward the monthly upload limit.

Does uploading make my content public?

No. Uploaded bundles are account-bound and can only be retrieved through the API by their owner. The Hub does not automatically publish them as a website, llms.txt, or public download.

Are my files encrypted?

Yes. Bundles and vector indexes are stored with AES-256-GCM encryption. Encryption is server-side and tied to the account. It is not zero-knowledge encryption because the server application can decrypt content for authorized features.

Does the AI provider receive my entire bundle?

Not by default. For each question, the Hub selects relevant concepts and sends limited excerpts with your prompt. Those excerpts may still contain confidential information, so only use Assistant when this processing is permitted.

Are my data used to train the models?

The Hub cannot make one blanket promise about data use across every model provider available through OpenRouter. The current terms and privacy rules of OpenRouter and the selected provider apply.

Does Assistant answer only from my OKF?

The system instruction requires answers only from the selected OKF excerpts and asks the model to state when evidence is missing. A language model can still follow instructions imperfectly, so verify the cited sources.

Which language does Assistant use?

Assistant is instructed to match the language of your question. The interface language can be switched between German and English independently.

What is the difference between a category and a tag?

A category is the concept’s primary assignment and creates its category hub in the graph. Tags are additional topic markers. Shared tags create similarity links between concepts.

What does “verified” mean?

It records that a signed-in user marked a concept as reviewed at a particular time. It is not independent quality assurance or legal approval.

Can I export a complete bundle?

The current interface exports individual concepts as OKF Markdown. Complete bundle export is not currently available. Keep your original files or exports as a backup.

Can I undo changes?

The Hub currently has no version history or undo function for saved edits and deletions. Export or back up important content before making major changes.

Are images and attachments imported?

No. The current importer focuses on Markdown, HTML, and CSV content. Images, PDFs, and other attachments are not stored as separate OKF materials.

Why does a deleted upload still count toward my quota?

The limit measures upload and import operations completed during the current month, not the number of bundles currently stored.

How do I delete my account?

Delete individual bundles from the dashboard. To delete the account and other associated data, email [email protected].

Where can I report a bug or request a feature?

Use the feedback field in the sidebar or email [email protected]. The feedback form stores your message, timestamp, and account email address.