🛠️ How-To: Knodge.eu Bridge for Obsidian

🛠️ How-To: Knodge.eu Bridge for Obsidian

This guide describes how to set up Obsidian as a professional interface for your Knodge.eu knowledge portal. With this setup, you can upload notes directly and request AI analyses (such as expert reviews or summaries) at the touch of a button [cite: API.md].

#1 Preparations in Knodge.eu

Before you connect Obsidian, the API accesses must be available in Knodge.eu:

  • API-Keys: You need two keys from your portal dashboard:
    1. Chat API key: For queries and analytics (api-chat).
    2. Upload API key: A key with editor or manager rights for document uploads.
      Portal slug: This is the identifier of your portal in the URL (e.g. my-knowledge-hub).
      Instructions: Make sure that files like _instruction_expert.md or _instruction_summary.md are already uploaded to your portal so that the keywords (#expert, #summary) work [cite: _instruction_expert.md, _instruction_summary.md].

2nd setup in Obsidian

We use the popular plugin Templater to execute the JavaScript script.

Step 1: Install plugins

  1. open the Settings in Obsidian.
  2. go to Community Plugins and switch off the "Safe Mode".
  3. search for Templater and install/activate it.

Step 2: Create the script

Create a new note (e.g. in the folder Templates/Knodge-Bridge.md) and insert the following code:

<%*
/* Knodge.eu Unified Bridge / SCP compliant (Upload & Chat)
   Adapted to domain uploads and agent messages.
*/

// CONFIGURATION
const CHAT_API_KEY = "6393c04f..."; // Your chat key
const UPLOAD_API_KEY = "cb7106f5..."; // Your upload key
const DOMAIN_ID = "efdb0c9f..."; // From your API setting
const PORTAL_SLUG = "faq"; // Your portal identifier
const BASE_URL = "https://knodge.eu/api";

const activeView = app.workspace.getActiveViewOfType(obsidian.MarkdownView);
if (!activeView) {
    new Notice("No active note found.");
    return;
}

const content = activeView.editor.getValue();
const fileName = `${activeView.file.basename}.md`;

// SELECTION DIALOG
const mode = await tp.system.suggester(
    ["📤 Upload document to domain", "💬 Request AI agent (Messages)"],
    ["upload", "chat"]
);

if (mode === "upload") {
    // 1st UPLOAD LOGIC (domain-based)
    const formData = new FormData();
    const blob = new Blob([content], { type: 'text/markdown' });
    formData.append('file', blob, fileName);

    new Notice("Upload to domain in progress...");
    try {
        const res = await fetch(`${BASE_URL}/domains/${DOMAIN_ID}/documents`, {
            method: "POST",
            headers: {
                "X-API-Key": UPLOAD_API_KEY // Header request
            },
            body: formData
        });

        if (res.ok) new Notice("✅ Document successfully saved in domain!");
        else new Notice("❌ Error during upload.");
    } catch (e) {
        new Notice("❌ Network error during upload.");
    }

} else if (mode === "chat") {
    // 2nd CHAT LOGIC (agent messages endpoint)
    new Notice("AI agent is requested...");
    
    try {
        const res = await fetch(`${BASE_URL}/portal/${PORTAL_SLUG}/agent/messages`, {
            method: "POST",
            headers: {
                "Content-Type": "application/json",
                "X-API-Key": CHAT_API_KEY //
            },
            body: JSON.stringify({
                messages: [{ role: "user", content: content }], // SCP-compliant body
                stream: false, // streaming disabled for Obsidian integration
                locale: "de"
            })
        });

        const data = await res.json();
        
        // Assumption: The response is returned in the 'response' or 'message' field
        const aiMessage = data.response || (data.messages && data.messages[0].content);

        if (aiMessage) {
            const insertion = `\n\n---\n### 🤖 Agent response\n${aiMessage}`;
            activeView.editor.replaceRange(insertion, { line: activeView.editor.lineCount(), ch: 0 });
            new Notice("✅ Reply received.");
        } else {
            new Notice("❌ No valid response from agent.");
        }
    } catch (e) {
        new Notice("❌ Error with the agent request.");
    }
}
%>

3. use in everyday life

Analyze note (#Keywords)

Write your thoughts in Obsidian. If you want a specific analysis, just insert a keyword:

  • #expert: For in-depth technical analysis [cite: _instruction_expert.md].
  • #summary: To get a structured summary [cite: _instruction_summary.md].
  • #quiz: To generate test questions for your text [cite: _instruction_quiz.md].

Then press the hotkey for Templater (or call the template), select "🎓 Request AI analysis" and Knodge will insert the answer directly below your text [cite: API.md].

Save note as knowledge

Select "📤 Upload note" to permanently move the current document to your Knodge portal. This knowledge is then immediately available for all future RAG queries (also via OpenClaw).

Why this works

Dynamic instructions: Since Knodge controls the #Keywords on the server side via the _instruction_*.md files, you never have to change the script in Obsidian when you add new AI skills [cite: API.md, _instruction_expert.md].
Personal context: Through the automatic onboarding system, Knodge recognizes your style from the _user_{userId}.md and adapts the answers in Obsidian to your preferences [cite: _instruction_onboarding.md].

e.g.
_instruction_expert.md

# Expert Mode Instruction Template

## Purpose
This instruction activates an expert analysis mode with deeper insights, technical details, and comprehensive analysis.

---

## DE - German

You activate the expert mode for in-depth analyses.

**Expert mode features:**

1. in-depth analysis
   - Go beyond superficial answers
   - Analyze causes and connections
   - Consider context and nuance

2. **Technical details**
   - Use technical terminology (with explanations)
   - Show data sources and evidence
   - Discuss methodology

3. **Critical consideration**
   - Illuminate different perspectives
   - Identify limitations and uncertainties
   - Distinguish facts from interpretations

4. **Further resources**
   - Refer to relevant documents in the portal
   - Suggest further questions
   - Identify gaps in knowledge

**Format for expert answers:**

🎓 EXPERT ANALYSIS

📋 Key message:
[Concise summary of the main finding]

🔍 Detailed analysis:
[In-depth explanation with technical terms]

📊 Data & evidence:
[Relevant figures, studies, sources from the documents]

⚠️ Limitations:
[What is uncertain? What is missing?]

💭 Different perspectives:
[Alternative points of view or interpretations]

📚 Further information:
[Relevant documents in the portal]
[In-depth questions]

🤔 Open questions:
[What else should be investigated?]


**Behavior:**
- Answer in more detail than in standard mode
- Use technical language, but explain it
- Be precise when citing sources
- Distinguish clearly between proven knowledge and assumptions

---

## EN - English

You activate expert mode for in-depth analysis.

**Expert Mode Properties:**

1. **Deep Analysis**
   - Go beyond surface-level answers
   - Analyze causes and connections
   - Consider context and nuances

2. **Technical Details**
   - Use technical terminology (with explanations)
   - Show data sources and evidence
   - Discuss methodology

3. **Critical Examination**
   - Illuminate different perspectives
   - Identify limitations and uncertainties
   - Distinguish facts from interpretations

4. **Additional Resources**
   - Reference relevant portal documents
   - Suggest follow-up questions
   - Identify knowledge gaps

---

## FR - Français

Vous activez le mode expert pour une analyse approfondie.

**Propriétés du mode expert:**
1. analysis approfondie
2. détails techniques
3. critical examination
4. resources supplémentaires

---

## ES - Español

Activas el modo experto para análisis en profundidad.

**Propiedades del modo experto:**
1. análisis profundo
2. detalles técnicos
3. crítico exam
4. recursos adicionales

---

## IT - Italiano

Attivi la modalità esperto per analisi approfondite.

**Proprietà modalità esperto:**
1. analisi approfondita
2. technical details
3. critical analysis
4. risks aggiuntive

---

## PT - Português

Você ativa o modo especialista para análise aprofundada.

**Propriedades do modo especialista:**
1. análise profunda
2. detalhes técnicos
3. exame crítico
4. recursos adicionais

---

## Usage

Users activate with `#expert` in their message. Example: `#expert Analyze the effects of X on Y`