# Cortex > Darwinian memory for AI agents on Arkiv Braga — cited memories extend, unused decay free. Wallet-owned, RaBitQ-compressed, client-side sealed. Live console + MCP. Arkiv × ETHNS Builder Challenge (AI + Privacy). - **Type:** MCP server - **Install:** `agentstack add mcp-lingsiewwin-cortex` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [LingSiewWin](https://agentstack.voostack.com/s/lingsiewwin) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [LingSiewWin](https://github.com/LingSiewWin) - **Source:** https://github.com/LingSiewWin/Cortex - **Website:** https://cortex-arkiv.vercel.app ## Install ```sh agentstack add mcp-lingsiewwin-cortex ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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 wallet-derived > key (client-side in the plugin). _(AI + Privacy · Arkiv × ETHNS Builder Challenge)_ | | Link | |---|------| | **Deploy (Vercel)** | https://cortex-arkiv.vercel.app | | **Console** | https://cortex-arkiv.vercel.app/console | | **Video walkthrough** | https://www.loom.com/share/68178caad4034e8282ac412a440e0738 | | **Source** | https://github.com/LingSiewWin/Cortex | | **Chain** | [Arkiv Braga testnet](https://explorer.braga.hoodi.arkiv.network/) · chainId `60138453102` | 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` (additive on Braga: +24 h baseline, scaled up to 2.5× by the memory's proven utility), 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. ### Where it runs **Cortex has no backend you depend on.** The product is the Claude Code plugin: it runs **locally** in your agent — the MCP server speaks over stdio via `bun`, the SQLite mirror lives on your disk, and writes are signed by **your own funded session key**. Nothing requires the maintainer's infrastructure. The website is a **landing + install + video** surface, not a live autonomous demo. The `/console` loop, mirror, and SSE stream are for **local development** (`bun run dev`) — they are stateful and long-running, which serverless cannot host, so the public deployment does not run them. For the autonomous loop in action, see the [video walkthrough](https://www.loom.com/share/68178caad4034e8282ac412a440e0738); for real on-chain evidence, see [`docs/proof/`](./docs/proof/). --- ## Claude Code plugin **Marketplace (Claude Code):** ```text /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](https://braga.hoodi.arkiv.network/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`): ```bash 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`](./cortex-plugin/README.md). --- ## Quick start ```bash git clone https://github.com/LingSiewWin/Cortex.git cd Cortex bun install cp .env.example .env ``` Fill `.env` (see [Environment](#environment)). Then: ```bash 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](./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](https://braga.hoodi.arkiv.network/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`) | ### Production (Vercel) Set these in the [Vercel project](https://cortex-arkiv.vercel.app) → **Settings → Environment Variables** (Production + Preview as needed): - `OPENROUTER_API_KEY` or `COHERE_API_KEY` - `SESSION_KEY_PRIVATE_KEY` (fund on [Braga faucet](https://braga.hoodi.arkiv.network/faucet/)) - `USER_PRIMARY_ADDRESS` - `CORTEX_USER_SIGNATURE` (from `bun run cortex-auth` or `bun run derive-user-signature`) - Redeploy after env changes Fund session key via Braga faucet before demo. --- ## Architecture End-to-end on Arkiv Braga (renders on GitHub or [mermaid.live](https://mermaid.live)). ```mermaid sequenceDiagram autonumber participant UI as Browser console participant Wallet as Owner wallet participant API as Cortex API participant OR as Embeddings API participant Engine as RaBitQ recall seal participant Mirror as SQLite mirror participant Agent as Session key creator participant Chain as Arkiv Braga participant SSE as SSE stream Note over UI,Chain: Write path wallet signs 1h lease UI->>API: store-file prepare API->>OR: embedText descriptor OR-->>API: 1536-d embedding API-->>UI: RaBitQ and attributes UI->>Wallet: sign key derivation UI->>UI: AES-GCM seal payload Wallet->>Chain: mutateEntities Chain-->>Mirror: ingest events Mirror-->>SSE: graph and RPC ticker Note over Agent,Chain: Reinforce cite in act or decay Agent->>Engine: recall query k Engine->>Mirror: hybrid rank Engine->>Chain: query attributes Engine-->>Agent: memory IDs Agent->>Engine: act with citations Engine->>Chain: extendEntity additive plus reinforcement Engine->>Chain: anchor MMR root Engine-->>SSE: memory.cited and arkiv.rpc Note over Agent,Chain: act() is optimistic — enqueues; the worker anchors the extend async (no synchronous extend tx) Note over Chain: Uncited memories evict via L1Block ``` **Ownership:** `$creator` = session key (attribution); `$owner` = your wallet (extend/update/delete). Reads filter by creator + `project=cortex-ethns-2026`. **Tiers:** working (1h) → episodic (≥2 cites, +7d) → semantic (≥5 cites · 3 sessions, 1y rule). **Extend math:** deployed Braga `extend` is **additive** — `expiresAt += expiresIn` (verified on-chain 2026-05-25). Each citation adds exactly its reinforcement (+24 h working, +7 d episodic), so useful memories accumulate lease while uncited ones decay. (The `remaining + reinforcement` REPLACE formula belongs to the future `EntityRegistry.sol`, not the live precompile — see `src/darwinian/extend.ts`.) --- ## Stack - **Web:** Next.js 15 (App Router), React 19, Reown AppKit, wagmi, viem - **Runtime:** Bun (tests, scripts, plugin); Node on Vercel (API + `better-sqlite3`) - **Chain:** Arkiv Braga — chainId `60138453102`, SDK `@arkiv-network/sdk` ^0.6.8 - **Compression:** RaBitQ @ 1536-d - **Identity:** EIP-712 session auth, SIWE, ERC-5267 domain, browser-signed Braga writes --- ## Repo map ``` |__ |___ app/ Next.js — `/`, `/console`, `/api/[[...path]]`, `/sse` |___ lib/web/ AppKit, connect gate, browser upload hook |___ ui/ Landing, console, MemoryGraph, upload UI |___ src/ | |___ lib/ Arkiv client, crypto, sealing, Braga preflight | |___ compression/ RaBitQ, embeddings, document payloads | |___ darwinian/ extend, recall, citation, distill | |___ mirror/ SQLite schema, replay, MMR, anchor, evict watcher | |___ topology/ Graph builder for `/api/topology` | |___ api/ HTTP handlers (auth, store-file, seed, …) | |___ agent/ Autonomous loop, anchor worker | |___ mcp/ MCP server for agent tooling | |___ obsidian/ Vault → mirror sync |___ cortex-plugin/ Claude Code plugin (hooks, MCP, skills) |___ scripts/ seed, cite-flow, sovereignty-proof, plugin build |___ tests/ Offline + smoke/canary against Braga |___ contracts/ CortexRegistry.sol (+ SynapticMarket.sol deferred on Braga) ``` --- ## Sovereignty proof `bun scripts/sovereignty-proof.ts` · [Braga round-trip](https://explorer.braga.hoodi.arkiv.network/tx/0x6c391af1fa9f9faa952b793980e2b657b33d724298b15a4b7e5fc174543828a2) See [`docs/proof/`](./docs/proof/) for script-generated explorer links. --- ## Reference | | Link | |---|------| | **Explorer** | https://explorer.braga.hoodi.arkiv.network/ | | **Faucet** | https://braga.hoodi.arkiv.network/faucet/ | | **RPC** | `https://braga.hoodi.arkiv.network/rpc` | ### RaBitQ (embedding compression) Cortex stores **1-bit RaBitQ** codes (1536-d → ~198 B) for recall distance estimates. Implementation is in `src/compression/rabitq.ts` + `fht.ts` (TypeScript; not the NTU C++ library). **Citation (SIGMOD 2024):** Gao et al., *RaBitQ: Quantizing High-Dimensional Vectors with a Theoretical Error Bound*, [arXiv:2405.12497](https://arxiv.org/abs/2405.12497) · [RaBitQ-Library](https://github.com/VectorDB-NTU/RaBitQ-Library) (Apache-2.0). Deeper notes: [`docs/RabitQ.md`](./docs/RabitQ.md). --- ## License MIT — see [`LICENSE`](./LICENSE). ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [LingSiewWin](https://github.com/LingSiewWin) - **Source:** [LingSiewWin/Cortex](https://github.com/LingSiewWin/Cortex) - **License:** MIT - **Homepage:** https://cortex-arkiv.vercel.app Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-lingsiewwin-cortex - Seller: https://agentstack.voostack.com/s/lingsiewwin - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.