How Mnemonic Works

Mnemonic makes routing decisions with code, not the LLM.

The Core Insight

The problem with LLM-based routing is simple: LLMs are non-deterministic. Ask Claude to "write BATS tests" ten times and you might get the bats-test-agent eight times, Claude doing it itself once, and the shell-script-agent once. That's not coordination - that's gambling.

Mnemonic moves the routing decision out of the LLM entirely. The routing engine evaluates rules in priority order using code. Same input, same output, every time.

Architecture Overview

graph TB
    subgraph Workstation["User Workstation"]
        CLI[Mnemonic CLI]
        CC[Claude Code]
    end

    subgraph Server["Server Infrastructure"]
        MN[Mnemonic Service]
        subgraph Data["Data Layer"]
            PG[(PostgreSQL)]
            PGV[(PGVector)]
            NEO[(Neo4j)]
        end
    end

    CLI -->|"1. REST: Route request"| MN
    MN <--> PG
    MN <--> PGV
    MN <--> NEO
    MN -->|"2. Agent + patterns"| CLI
    CLI -->|"3. Execute with context"| CC
    CC -->|"4. Results"| CLI

    style CLI fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
    style CC fill:#f1f5f9,stroke:#64748b,stroke-width:2px
    style MN fill:#ccfbf1,stroke:#0d9488,stroke-width:2px
    style PG fill:#fef3c7,stroke:#f59e0b,stroke-width:1px
    style PGV fill:#fef3c7,stroke:#f59e0b,stroke-width:1px
    style NEO fill:#fef3c7,stroke:#f59e0b,stroke-width:1px

The flow:

1. You submit a prompt to Mnemonic
2. CLI sends it to Mnemonic for routing
3. Mnemonic's routing engine determines which agent handles the request (code-based decision)
4. Mnemonic returns the agent definition + relevant patterns
5. CLI sends the enriched prompt to Claude Code
6. Claude Code executes with the predetermined agent context

Mnemonic: The Brain

Mnemonic is a purpose-built service (not adapted from something else) that handles:

Routing Engine

Code-based rules evaluated in priority order:

Match Type	How It Works
Keyword	Prompt contains specific keywords ("bats", "shell script")
Regex	Prompt matches a pattern (\b(go\|golang)\b.*function)
Semantic	Prompt embedding is similar to stored pattern embeddings

Rules have priorities. Higher priority rules are evaluated first. First match wins.

Agent Storage

Agent definitions live in Mnemonic's PostgreSQL database at runtime:

• System prompts
• Allowed tools
• Model preferences (sonnet, opus, haiku)
• Routing keywords

Agent Definitions

The markdown agent definitions in Git remain the source of truth. They get loaded into Mnemonic's database, which serves as the runtime store. This means you can version control your agents, review changes in PRs, and deploy updates by syncing to the database.

Pattern Retrieval

Patterns are reusable context documents - code examples, guidelines, best practices. When an agent is selected, Mnemonic can also return relevant patterns to enrich the prompt.

RAG with Deterministic Orchestration

This is where the RAG comes in. PGVector does semantic similarity search on pattern embeddings to find relevant context. But unlike pure RAG systems, Mnemonic also handles the routing decision - which agent gets the request. Think of it as RAG with deterministic orchestration.

Data Architecture

Mnemonic uses a polyglot persistence strategy:

Database	Purpose
PostgreSQL	Relational data - agents, routing rules, patterns, associations
PGVector	Vector embeddings for semantic similarity search
Neo4j	Knowledge graph for relationships between patterns, agents, and concepts

This isn't over-engineering. Each database does what it's good at:

• Postgres gives ACID transactions and relational queries
• PGVector enables semantic search without a separate service
• Neo4j lets us traverse relationships (which patterns relate to which agents, which concepts connect which patterns)

The Phased Approach

Mnemonic is being built incrementally:

Phase 1: Claude Code Integration (Current)

sequenceDiagram
    participant User
    participant CLI as Mnemonic CLI
    participant MN as Mnemonic
    participant CC as Claude Code

    User->>CLI: Submit prompt
    CLI->>MN: POST /v1/api/route
    MN-->>CLI: Agent + patterns
    CLI->>CC: Invoke with enriched prompt
    CC-->>CLI: Results
    CLI-->>User: Display output

• Claude Code does the actual LLM work
• Mnemonic handles routing and pattern retrieval
• You still need Claude Code installed

Phase 2: Direct API Integration (Future)

• Mnemonic CLI calls Anthropic API directly
• No Claude Code dependency
• More control over context and execution

Phase 3: Authentication & Authorization (Enterprise)

• Team-level access control via Envoy + OPA
• Pattern governance
• Audit logging

Why This Matters

When you ask Mnemonic to "write BATS tests," the routing engine matches that to the bats-test-agent because a rule says so. Not because Claude decided to. Not because it interpreted your intent correctly. Because the code said so.

That's deterministic coordination.

---

Want the Full Technical Details?

This page gives you the concepts. For complete technical specifications, see the Mnemonic Architecture Documentation.