project-lyra/TRILIUM_SETUP.md

Trilium ETAPI Integration Setup

This guide will help you enable Lyra's integration with your Trilium notes using the ETAPI (External API).

What You Can Do with Trilium Integration

Once enabled, Lyra can help you:

• 🔍 Search through your notes
• 📝 Create new notes from conversations
• 🔄 Find duplicate or similar notes
• 🏷️ Suggest better organization and tags
• 📊 Summarize and update existing notes

Prerequisites

• Trilium Notes installed and running
• Access to Trilium's web interface
• Lyra running on the same network as Trilium

Step 1: Generate ETAPI Token in Trilium

1. Open Trilium in your web browser (e.g., http://10.0.0.2:4292)

2. Navigate to Options:

   • Click the menu icon (≡) in the top-left corner
   • Select "Options" from the menu

3. Go to ETAPI Section:

   • In the Options sidebar, find and click "ETAPI"
   • This section manages external API access

4. Generate a New Token:

   • Look for the "Create New Token" or "Generate Token" button
   • Click it to create a new ETAPI token
   • You may be asked to provide a name/description for the token (e.g., "Lyra Integration")

5. Copy the Token:

   • Once generated, you'll see a long string of characters (this is your token)
   • IMPORTANT: Copy this token immediately - Trilium stores it hashed and you won't see it again!
   • The token message will say: "ETAPI token created, copy the created token into the clipboard"
   • Example format: 3ZOIydvNps3R_fZEE+kOFXiJlJ7vaeXHMEW6QuRYQm3+6qpjVxFwp9LE=

6. Save the Token Securely:

   • Store it temporarily in a secure place (password manager or secure note)
   • You'll need to paste it into Lyra's configuration in the next step

Step 2: Configure Lyra

1. Edit the Environment File:

   nano /home/serversdown/project-lyra/.env
   

2. Add/Update Trilium Configuration: Find or add these lines:

   # Trilium ETAPI Integration
   ENABLE_TRILIUM=true
   TRILIUM_URL=http://10.0.0.2:4292
   TRILIUM_ETAPI_TOKEN=your_token_here
   
   # Enable tools in standard mode (if not already set)
   STANDARD_MODE_ENABLE_TOOLS=true
   

3. Replace your_token_here with the actual token you copied from Trilium

4. Save and exit (Ctrl+O, Enter, Ctrl+X in nano)

Step 3: Restart Cortex Service

For the changes to take effect, restart the Cortex service:

cd /home/serversdown/project-lyra
docker-compose restart cortex

Or if running with Docker directly:

docker restart cortex

Step 4: Test the Integration

Once restarted, try these example queries in Lyra (using Cortex mode):

1. Test Search:

   • "Search my Trilium notes for topics about AI"
   • "Find notes containing 'project planning'"

2. Test Create Note:

   • "Create a note in Trilium titled 'Meeting Notes' with a summary of our conversation"
   • "Save this to my Trilium as a new note"

3. Watch the Thinking Stream:

   • Open the thinking stream panel (🧠 Show Work)
   • You should see tool calls to search_notes and create_note

Troubleshooting

"Connection refused" or "Cannot reach Trilium"

• Verify Trilium is running: curl http://10.0.0.2:4292
• Check that Cortex can access Trilium's network
• Ensure the URL in .env is correct

"Authentication failed" or "Invalid token"

• Double-check the token was copied correctly (no extra spaces)
• Generate a new token in Trilium if needed
• Verify TRILIUM_ETAPI_TOKEN in .env is set correctly

"No results found" when searching

• Verify you have notes in Trilium
• Try a broader search query
• Check Trilium's search functionality works directly

Tools not appearing in Cortex mode

• Verify ENABLE_TRILIUM=true is set
• Restart Cortex after changing .env
• Check Cortex logs: docker logs cortex

Security Notes

⚠️ Important Security Considerations:

• The ETAPI token provides full access to your Trilium notes
• Keep the token secure - do not share or commit to git
• The .env file should be in .gitignore (already configured)
• Consider using a dedicated token for Lyra (you can create multiple tokens)
• Revoke tokens you no longer use from Trilium's ETAPI settings

Available Functions

Currently enabled functions:

search_notes(query, limit)

Search through your Trilium notes by keyword or phrase.

Example: "Search my notes for 'machine learning' and show the top 5 results"

create_note(title, content, parent_note_id)

Create a new note in Trilium with specified title and content.

Example: "Create a note called 'Ideas from Today' with this summary: [content]"

Optional: Specify a parent note ID to nest the new note under an existing note.

Future Enhancements

Potential additions to the integration:

• Update existing notes
• Retrieve full note content by ID
• Manage tags and attributes
• Clone/duplicate notes
• Export notes in various formats

---

Need Help? Check the Cortex logs or open an issue on the project repository.