# Mnemosyne Integration — Pallas Reference

This document summarises the Pallas-specific changes required for Mnemosyne knowledge integration. The full specification lives in [`daedalus/docs/mnemosyne_integration.md`](../../daedalus/docs/mnemosyne_integration.md).

---

## Overview

Pallas agents gain access to Mnemosyne's content-type-aware knowledge graph as a downstream MCP server. Agents can search documents, browse libraries, retrieve items, and traverse the concept graph — all via standard MCP tool calls.

---

## Configuration Changes

### fastagent.config.yaml

Add the Mnemosyne MCP server:

```yaml
mcp:
  servers:
    # ... existing servers (argos, neo4j_cypher, kernos, rommie, gitea, grafana) ...
    mnemosyne:
      transport: http
      url: "http://puck.incus:22091/mcp"
```

### Agent Definitions

#### Research Agent (port 23031)

The `knowledge` agent in the research chain gains Mnemosyne access:

```python
@fast.agent(name="search", servers=["argos"])
@fast.agent(name="knowledge", servers=["neo4j_cypher", "mnemosyne"])
@fast.chain(name="research", sequence=["search", "knowledge"], default=True)
```

The `knowledge` agent's system instruction should guide tool selection:

> Use `mnemosyne.search_knowledge` for document content retrieval — it handles chunking, vector search, re-ranking, and content-type-aware context. Use `neo4j_cypher` for graph topology queries, relationship exploration, and data not managed by Mnemosyne.

#### Infrastructure Agent (port 23032)

No changes — Infrastructure does not use Mnemosyne.

#### Orchestrator (port 23033)

```python
@fast.agent(name="research_sub", servers=["argos", "neo4j_cypher", "mnemosyne"])
@fast.agent(name="infra_sub", servers=["kernos", "gitea", "rommie"])
@fast.orchestrator(name="orchestrator", agents=["research_sub", "infra_sub"],
                   plan_type="iterative", default=True)
```

### Registry Update

Update agent descriptions to reflect Mnemosyne access:

```json
{
  "server": {
    "name": "ca.helu.ouranos/pallas-research",
    "title": "Research Agent",
    "description": "Web search via Argos, knowledge graph via Neo4j, and content library search via Mnemosyne",
    "version": "1.1.0",
    "remotes": [
      { "type": "streamable-http", "url": "http://puck.incus:23031/mcp" }
    ]
  }
}
```

---

## Available Mnemosyne MCP Tools

These tools become available to agents with `mnemosyne` in their `servers` list:

| Tool | Purpose | When to Use |
|------|---------|-------------|
| `search_knowledge` | Hybrid vector + full-text + graph search with re-ranking | Document content retrieval, question answering over stored knowledge |
| `search_by_category` | Search scoped to a library type (fiction, technical, etc.) | When the user specifies or implies a content domain |
| `list_libraries` | List all knowledge libraries | Discovering what knowledge domains exist |
| `list_collections` | List collections within a library | Browsing a specific knowledge domain |
| `get_item` | Retrieve item metadata + chunk previews + concept links | Deep dive on a specific document/item |
| `get_concepts` | Traverse concept graph | Exploring relationships between topics, people, places |

---

## Downstream MCP Servers (Updated)

| Server | Host | URL | Used by |
|--------|------|-----|---------|
| argos | miranda.incus | `http://miranda.incus:25534/mcp` | Research, Orchestrator |
| neo4j_cypher | circe.helu.ca | `http://circe.helu.ca:22034/mcp` | Research, Orchestrator |
| **mnemosyne** | **puck.incus** | **`http://puck.incus:22091/mcp`** | **Research, Orchestrator** |
| kernos | caliban.incus | `http://caliban.incus:22021/mcp` | Infrastructure, Orchestrator |
| gitea | miranda.incus | `http://miranda.incus:25535/mcp` | Infrastructure, Orchestrator |
| rommie | caliban.incus | `http://caliban.incus:22031/mcp` | Infrastructure, Orchestrator |
| grafana | miranda.incus | `http://miranda.incus:25533/mcp` | Infrastructure |