Cortex
Darwinian memory for AI agents — observations that earn longer expiration when
cited; useless ones decay for free on Arkiv. Encrypted at rest with a key derived
from your wallet. (AI + Privacy · Arkiv × ETHNS Builder Challenge)
One repo — not a monorepo. app/ + src/ + cortex-plugin/ ship together.
What it does
| Layer | Behavior |
|---|
| Write | RaBitQ-compress embeddings (1536-d → ~198 B), seal payload with wallet-derived AES-256-GCM, createEntity on Braga with 1 h starting expiration |
| Recall | Hybrid search: Arkiv attributes + local mirror + RaBitQ distance — no vector DB |
| Reinforce | Every act(..., citations=[...]) fires accumulative extend (remaining lease + 24 h), so useful memories grow; stale ones evict via L1Block |
| Prove | Merkle Mountain Range over decisions; roots anchored on Arkiv |
Agent surface: recall(query, k) and act(action, citations[]) only.
Live console (/console)
An autonomous loop (server session key) recalls and cites on a timer; each step emits typed events on /sse. The UI shows Braga tx links, topology graph, and manual query/cite. File upload uses your browser wallet on Braga (prepare on server → sign tx in MetaMask).
Claude Code plugin
Marketplace (Claude Code):
/plugin marketplace add LingSiewWin/Cortex
/plugin install cortex-memory
cortex auth
Verified flow: marketplace add → cortex-memory install → cortex auth writes ~/.cortex/config.json (owner wallet + session key). Fund the printed session key on Braga faucet before Arkiv writes.
cortex auth opens a local page — keep the terminal open until you sign. Requires bun on your PATH.
From a clone (after bun run build:plugin):
claude plugin install --plugin-dir ./cortex-plugin
- Hooks: capture before compaction, recall at session start
- MCP:
cortex_recall, cortex_act, cortex_store_document on stdio (bun run mcp from repo root)
- Skill:
cortex-memory usage patterns
Config templates: cortex-plugin/.mcp.json, hooks/hooks.json. See cortex-plugin/README.md.
Quick start
git clone https://github.com/LingSiewWin/Cortex.git
cd Cortex
bun install
cp .env.example .env
Fill .env (see Environment). Then:
bun run faucet-check # session key has GLM on Braga
bun run seed # seed memories (run once, before the loop)
bun run dev # http://localhost:3000 → /console
| Script | Purpose |
|---|
bun run dev | Next.js dev server (landing + console + /api/*) |
bun run build / start | Production Next.js |
bun test | Full test suite (353+ tests) |
bun run smoke | Single real Braga create + read |
bun run mirror | Standalone mirror replay daemon |
bun run mcp | Cortex MCP server (stdio) |
bun run build:plugin | Bundle Claude Code plugin to cortex-plugin/dist/ |
See scripts/README.md for the full script list (Braga scripts & eval are optional).
Run seed before starting the loop — seed and the autonomous agent share one session-key EOA; parallel writes collide on nonce.
Environment
| Variable | Required | Role |
|---|
SESSION_KEY_PRIVATE_KEY | Writes / loop | $creator session-key EOA (fund via faucet) |
USER_PRIMARY_ADDRESS | Ownership | $owner primary EOA |
CORTEX_USER_SIGNATURE or CORTEX_USER_PRIVATE_KEY | Sealed recall | Wallet-derived payload key (see bun scripts/derive-user-signature.ts) |
OPENROUTER_API_KEY or COHERE_API_KEY | Embeddings | 1536-d vectors for RaBitQ (upload + recall) |
ANTHROPIC_API_KEY | Optional | Semantic distillation |
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID | Optional | Reown AppKit modal; omit → injected MetaMask only |
NEXT_PUBLIC_BRAGA_RPC | Optional | Default: Braga HTTP RPC from src/constants.ts |
CORTEX_MIRROR_PATH | Optional | SQLite mirror path (default ./cortex-mirror.sqlite) |
Architecture
thedotmack
Lucklyric
xrf9268-hue
anthropics
JuliusBrussee
wshobson