cortex-rs

Native Rust memory engine with SQLite FTS5 lexical recall, bi-encoder vector similarity, and hardware-secured loopback isolation.

Overview

cortex-rs is the canonical memory engine powering Atlas and the AIEN sovereign agent stack. Written in native Rust (Axum), it replaces interpreted memory servers with sub-millisecond lexical and semantic retrieval.

It provides hybrid search combining BM25 full-text indexing with ONNX vector embeddings, enabling autonomous agents to recall procedures, lessons, and architectural discoveries across thousands of turns without context collapse.

Features

• Sub-Millisecond Retrieval: Pure compiled Rust using SQLite WAL mode and FTS5 inverted indexes with typical latency <1ms.
• Hybrid Semantic Recall: Direct integration with local bi-encoder vector servers for cosine similarity and dense embedding scoring.
• Hardware Vault Security: Zero plaintext secrets. All authentication uses bearer token validation bound to loopback interfaces (127.0.0.1).
• Graph & Provenance Traversal: Bidirectional relationship edges (cortex_claims, cortex_entities) for deep contextual graph traversal.
• Unslop Standard: Enforces clean technical facts without AI filler or speculative abstractions.

Turnkey Reproduction & Benchmarks

Run the engine and observe live latency and throughput metrics directly with a single command.

1. One-Line Docker Benchmark

Execute the compiled native benchmark inside a container to evaluate SQLite WAL ingestion, FTS5 lexical retrieval, and graph claim traversal:

docker run --rm ghcr.io/aien-dev/cortex-rs:latest --bench

Or build and run locally with Docker:

docker build -t cortex-rs https://github.com/aien-dev/cortex-rs.git
docker run --rm cortex-rs --bench

Verified benchmark output on Grace Blackwell GB10:

================================================================================
CORTEX-RS FLAGSHIP REPRODUCTION BENCHMARK
Target: SQLite WAL + FTS5 Inverted Index + Graph Claim Traversal
Records to ingest: 500
================================================================================

[1/3] Benchmarking Entity Ingestion (FTS5 + SQLite WAL)...
[2/3] Benchmarking FTS5 Lexical Search across 500 records...
[3/3] Benchmarking Bidirectional Graph Claim Traversal...

================================================================================
BENCHMARK RESULTS SUMMARY (Reproducible Single-Command Output)
================================================================================
Corpus Size:                      500 entities
Total Search Queries Run:         500
--------------------------------------------------------------------------------
METRIC                          p50 (µs)    p95 (µs)    p99 (µs)      Rate / QPS
--------------------------------------------------------------------------------
Entity Ingestion (WAL+FTS5)         76.9       145.6      8121.9       4375.6 writes/s
FTS5 Lexical Search                121.8       452.9       461.3       6341.2 qps
Graph Claim Traversal                7.3         7.5        10.2     133247.2 qps
--------------------------------------------------------------------------------
Search p50 in milliseconds:      0.122 ms
Search p99 in milliseconds:      0.461 ms
================================================================================

2. Standalone Native Reproduction (Zero Docker)

To run natively on Linux or macOS without Docker:

# Clone repository and execute the automated verification runner
git clone https://github.com/aien-dev/cortex-rs.git
cd cortex-rs
./scripts/reproduce.sh

Or run the built-in benchmark directly with Cargo:

cargo run --release -- --bench --bench-records 1000

3. Running the Production Server

Local Process

# Compile release binary
cargo build --release

# Run Cortex-RS on local loopback
./target/release/cortex-rs --port 18080 --db-path ~/.config/cortex/cortex.db

Docker Container

docker run -d \
  --name cortex-rs \
  -p 18080:18080 \
  -e CORTEX_TOKEN=your-vault-token \
  ghcr.io/aien-dev/cortex-rs:latest

4. API Endpoints

Health Check (Unauthenticated)

curl http://127.0.0.1:18080/health
# {"runtime":"native-arm64-rust","service":"cortex-rs","space":"atlas-memory","status":"ok","version":"0.1.0"}

Entity Ingestion

curl -X POST http://127.0.0.1:18080/api/cortex/write \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "entity",
    "value": {
      "space": "atlas-memory",
      "canonicalName": "system_module_1",
      "entityType": "discovery",
      "content": "Grace Blackwell GB10 unified memory architecture verification."
    }
  }'

Lexical Search

curl -G http://127.0.0.1:18080/api/cortex/search \
  --data-urlencode "q=unified memory" \
  -H "Authorization: Bearer <TOKEN>"

License

This repository is licensed under the Sovereign Reciprocal Commons License (SRCL-1.0) (Apache 2.0 with LLVM Exception).

• The Swarm Covenant (Section 11): Universal, perpetual, 100% royalty-free commercial freedom for all human developers, startups, open communities, and businesses. ZERO revenue ceilings, ZERO capital thresholds, and ZERO royalty obligations. Proprietary application code and agent workflows remain your exclusive property under the LLVM Exception.
• The One Team Covenant (Section 12): Major artificial intelligence laboratories (OpenAI, xAI, Google, Anthropic, Microsoft) are welcomed as collaborators on the same team. However, closed-door hoarding and extractive token rate limits are prohibited. Any entity training upon this Work must release resulting model weights openly within 30 days. Reciprocal distillation rights are granted to the Swarm, voiding anti-distillation terms of service ab initio.
• Hardened Retroactive Inception (Section 13): Applies retroactively to all prior commits and distributions ab initio, discharging prior noncommercial or restrictive notices with an irrevocable covenant not to sue.

See LICENSE for the full legal text.