# 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**:
   ```bash
   nano /home/serversdown/project-lyra/.env
   ```

2. **Add/Update Trilium Configuration**:
   Find or add these lines:
   ```env
   # 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:

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

Or if running with Docker directly:
```bash
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.