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 · 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; for real on-chain evidence, see docs/proof/.

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`)

Production (Vercel)

Set these in the Vercel project → Settings → Environment Variables (Production + Preview as needed):

OPENROUTER_API_KEY or COHERE_API_KEY
SESSION_KEY_PRIVATE_KEY (fund on Braga 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).

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

See 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 · RaBitQ-Library (Apache-2.0). Deeper notes: docs/RabitQ.md.

License

MIT — see LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 128 Commits
.claude-plugin		.claude-plugin
.github/workflows		.github/workflows
app		app
assets		assets
contracts		contracts
cortex-plugin		cortex-plugin
docs		docs
extensions/memory-arkiv		extensions/memory-arkiv
lib/web		lib/web
scripts		scripts
src		src
tests		tests
ui		ui
.env.example		.env.example
.gitignore		.gitignore
.mcp.json		.mcp.json
.vercelignore		.vercelignore
LICENSE		LICENSE
README.md		README.md
bun.lock		bun.lock
instrumentation.ts		instrumentation.ts
next-env.d.ts		next-env.d.ts
next.config.ts		next.config.ts
package.json		package.json
skills-lock.json		skills-lock.json
tsconfig.json		tsconfig.json
vercel.json		vercel.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Cortex

What it does

Where it runs

Claude Code plugin

Quick start

Environment

Production (Vercel)

Architecture

Stack

Repo map

Sovereignty proof

Reference

RaBitQ (embedding compression)

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Cortex

What it does

Where it runs

Claude Code plugin

Quick start

Environment

Production (Vercel)

Architecture

Stack

Repo map

Sovereignty proof

Reference

RaBitQ (embedding compression)

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages