Cordelia Proxy

<p><img src="docs/logo.svg" alt="Cordelia" width="48" height="48"></p>

Cordelia Proxy


TypeScript MCP server, dashboard, and REST API for Cordelia.

Looking to install Cordelia? Go to cordelia-agent-sdk -- that's the front door.

What This Is

This repo contains the MCP proxy server that Claude Code talks to. It handles memory storage (SQLite), encryption (AES-256-GCM), search, groups, and the web dashboard.

What This Is NOT

This is not where you install Cordelia from. Install, hooks, skills, and setup have moved to cordelia-agent-sdk.

Architecture

Claude Code --> cordelia-agent-sdk (hooks) --> cordelia-proxy (MCP/HTTP) --> cordelia-node (Rust, QUIC)

Memory Layers:
  L0: Session Buffer    (ephemeral, current conversation)
  L1: Hot Context       (loaded at session start, ~50KB)
  L2: Warm Index        (searchable, pulled on demand, ~5MB)
  L3: Cold Archive      (compressed, rarely accessed)

L2 items can be private (entity-only), group-scoped (membership-gated), or public. Sharing uses copy-on-write -- originals are never modified, preserving entity sovereignty.

Security

L2 items are encrypted using AES-256-GCM with per-group Pre-Shared Keys (PSKs). Keys are distributed via ECIES envelope encryption (X25519 + HKDF-SHA256) during device enrollment. Legacy scrypt encryption was removed in E5. Embeddings are stripped from the persisted index and regenerated on-demand to prevent semantic fingerprint leakage.

Installation

For end users: Use the SDK installer:

curl -fsSL https://seeddrill.ai/install.sh | bash -s -- <your-username>

See cordelia-agent-sdk for full instructions.

Configuration

Claude Code MCP Settings

The installer automatically configures ~/.claude.json (global MCP config):

{
  "mcpServers": {
    "cordelia": {
      "command": "node",
      "args": ["/path/to/cordelia-proxy/dist/server.js"],
      "env": {
        "CORDELIA_STORAGE": "node",
        "CORDELIA_MEMORY_ROOT": "~/.cordelia/memory"
      }
    }
  }
}

The encryption key is not stored in MCP config or shell profiles. It is retrieved at runtime from the platform keychain (macOS Keychain / Linux GNOME Keyring) or ~/.cordelia/key. See docs/KEY-MANAGEMENT.md for details.

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | CORDELIA_ENCRYPTION_KEY | Passphrase for L2 encryption | (none - encryption disabled) | | CORDELIA_ENCRYPTION_ENABLED | Explicit enable/disable | true if key provided | | CORDELIA_EMBEDDING_PROVIDER | Embedding provider: ollama, openai, none | ollama | | CORDELIA_EMBEDDING_URL | Embedding API URL | http://localhost:11434 | | CORDELIA_EMBEDDING_MODEL | Embedding model name | nomic-embed-text | | CORDELIA_STORAGE | Storage backend: sqlite, json (legacy) | sqlite | | CORDELIA_TTL_SWEEP_INTERVAL_MS | Interval for TTL expiry sweep (ms) | 3600000 |

Available MCP Tools

L1 Hot Context

| Tool | Description | |------|-------------| | memory_read_hot | Read L1 hot context for a user | | memory_write_hot | Write/patch L1 hot context with optimistic concurrency | | memory_status | Get memory system status and encryption state |

L2 Warm Index

| Tool | Description | |------|-------------| | memory_search | Search L2 by keyword, type, tags | | memory_read_warm | Read a specific L2 item by ID | | memory_write_warm | Create/update entities, sessions, or learnings | | memory_delete_warm | Delete a specific L2 item by ID |

Groups

| Tool | Description | |------|-------------| | memory_share | Share a private memory to a group (COW copy) | | memory_group_create | Create a new group (creator becomes owner) | | memory_group_list | List groups | | memory_group_read | Read group details | | memory_group_add_member | Add entity to group | | memory_group_remove_member | Remove entity from group |

Analysis + Operations

| Tool | Description | |------|-------------| | memory_analyze_novelty | Detect novelty signals for persistence decisions | | memory_backup | Export memory to backup directory | | memory_restore | Restore from backup with integrity verification |

Session Hooks

Session hooks have moved to cordelia-agent-sdk. The SDK hooks resolve this proxy via getProxyDir() in hooks/lib.mjs.

Development

npm run dev      # Run with ts-node
npm run build    # Compile TypeScript
npm start        # Run compiled server
npm test         # Run all tests
npm run lint     # ESLint
npm run typecheck # tsc --noEmit
npm run ci       # Full pipeline: lint + typecheck + test + audit + build

Related Repos

• cordelia-agent-sdk -- Start here. Install, hooks, skills, agent spec
• cordelia-core -- Rust P2P node, protocol, replication, governor
• cordelia -- Archived monorepo (full git history)

License

AGPL-3.0 -- Copyright (c) 2026 Seed Drill

See LICENSE for full text.

Community

• Slack: https://join.slack.com/t/seeddrill/shared_invite/zt-3op96zqna-Y3OqZfUHsjQpHz~F8a~DPA