<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