Local memory. Ready for your agent.
One self-contained binary. No Node.js or Rust required on macOS Apple Silicon/Intel, Linux x64/ARM64, or Windows x64. Local memory works without an account or API key.
1. Install
macOS / Linux / WSL
curl -fsSL https://raw.githubusercontent.com/amar3012005/ICARUS/main/install.sh | bashNative Windows PowerShell
irm https://raw.githubusercontent.com/amar3012005/ICARUS/main/install.ps1 | iexChoose Agent Memory for the default local experience. Knowledge Space is a preview; Harness is an explicit opt-in. On Windows, run icarus setup after installation for guided setup.
Open a new terminal after installation. To use the current macOS/Linux terminal:
export PATH="$HOME/.icarus/bin:$PATH"
icarus --version2. Save and recall
icarus save "The release checklist lives in docs/release.md" --org first-memory
icarus recall "release checklist" --org first-memory3. Connect your coding agent — optional
From the repository root, choose codex, claude, or cursor. This registers memory tools and creates the repository memory shard. Restart the coding agent after registration.
icarus mcp install codex
# Add --harness only when this repository should use task governance.4. Developer sign-in — optional
icarus connectChoose email or Google on the ICARUS developer account page. For email, enter the six-digit code from your ICARUS email and choose Verify and continue. The browser returns to the waiting terminal, which confirms sign-in.
Keep the terminal open; it waits up to fifteen minutes. If it expires after the browser verified you, run icarus connect again to finish using that session. No purchase or company workspace is required. Developer identity grants no hosted customer API access and does not upload local memory.
Skip sign-in to keep working offline. Use icarus connect --logout to remove the local developer credential. Upgrade later with icarus update.
Read the quickstartDownloads and checksumsDeveloper sign-in details
Agent Bus is experimental with no public installer; the proposed bridge is not shipped. Computer Use is a separate experimental module. Installing Memory enables neither.
v1 made a claim; v2 ships the system. Since June, ICARUS went from a frozen format RFC to a production Rust engine behind HIVEMIND: seven machine-verified gates, a live cutover serving real tenants, and — new in v2 — every memory it builds is post-quantum signed by default. This revision documents what was actually built, with the numbers each gate had to pass.
From thesis to production — seven gates
Nothing advanced on judgment. Each phase ended in a gate: a scripted, reproducible pass/fail check on real data — real bge-m3 embeddings of real production memories, never synthetic vectors. A phase that failed its gate could not advance.
napi addon + MnemeVectorStore — a drop-in for the Qdrant client. Eval gate: recall@5 parity 1.00 vs the live stack on real data. Soak testing surfaced and fixed a real concurrent-reserve segfault (RwLock write-guard).
The engine that emerged: a Rust core (.mseg slots + usearch HNSW overlay + PQ codebooks), write-path isolated from indexing, exposed to Node through a napi binding whose store class is a drop-in for the vector-DB client it replaces. Soak testing under concurrent load surfaced a real segfault in incremental indexing — found, root-caused to an unguarded reserve, fixed with a write-guard, and regression-tested. That is what the gates are for.
The .amr slot — unchanged, and that’s the point
The 202-byte slot frozen in the v1 RFC survived production contact without a single field change. The format is the contract:
1024-dim embedding → 128 bytes via Product Quantization. 32× compression. The vector IS in the slot, not a foreign key.
How it runs live — anchor + engine
In production, ICARUS does not replace the relational layer — memory is a relational hub (provenance, projects, embeddings all reference it). The deployed topology keeps a thin relational anchor per memory and moves the hot path — semantic + entity + temporal + graph recall — onto the .amr engine. One file per tenant, opened in-process by the memory engine, with the recall backend live-verified against the previous stack before cutover (recall-parity gate: 1.00).
| Layer | Role in the live system |
|---|---|
| Relational anchor | One row per memory — identity, provenance, project links. The FK hub stays. |
| .amr shard (per tenant) | The recall engine: PQ vectors, entity bitmaps, bi-temporal anchors, adjacency — one mmap. |
| HNSW overlay | Async-built index; writes never wait for indexing (p99 54.75 µs under rebuild). |
| Engine binding | napi addon; store interface is a drop-in for the previous vector-DB client. |
New in v2 — every memory is post-quantum signed, by default
An agent-memory system asks for long-horizon trust: memories written today must still be provably authentic in ten years — against attackers who can rewrite a database, and eventually against quantum adversaries. So the write path signs every memory at creation with ML-DSA-65 (NIST FIPS 204), on by default across managed and self-host deployments:
Signed with ML-DSA-65 — a NIST-standard post-quantum signature. Secret key lives ONLY in server env, never in the database: an attacker with full DB access cannot forge a valid signature.
Three properties matter. Default-on: not a tier or a toggle — the engine signs every write (30,000+ live signatures on managed hosting at publication). Key separation: signing keys live only in server env, never the database — DB compromise ≠ forgery ability. Independent verification: public keys and verify endpoints are exposed; an auditor needs zero trust in us. Around the memory layer, the same posture: hybrid X25519 + ML-KEM-768 (FIPS 203) key exchange on the edge — defeating harvest-now/decrypt-later — and an SLH-DSA (FIPS 205) hash-chained, append-only audit trail with a signed checkpoint.
| Surface | Post-quantum mechanism |
|---|---|
| Memory writes | ML-DSA-65 signature per memory (FIPS 204) — on by default |
| Transport | Hybrid X25519 + ML-KEM-768 key exchange (FIPS 203) |
| Audit trail | SLH-DSA-SHA2-128s hash-chained signatures (FIPS 205), tamper-evident |
| Verification | Public endpoints: /api/security/pqc · /verify-memory · /audit-verify |
Honest edges: signing is currently fail-open (a write proceeds unsigned if keys are absent) — an enforce mode for high-assurance tenants is planned; and on self-host BYOD topologies the signature attaches at the engine anchor, with agent-side signing on the roadmap alongside customer-held keys (BYOK): you hold the key, and even we cannot forge your memory.
v2 numbers
| Metric | Result |
|---|---|
| proof gate — mmap scan vs vector DB over REST (10k, real embeddings) | 13.3× faster (0.155 ms vs 2.057 ms p50) |
| recall@10 p50 @ 1M vectors (HNSW) | 1.33 ms · 99.25% vs exact |
| bi-temporal + 2-hop graph recall @ 1M | 1.93 ms p50 |
| write p99 under concurrent index rebuild | 54.75 µs — writes never block |
| vector compression (PQ, ADC + rescore) | 32× at 100% recall@10 overlap |
| production shadow eval (8,682 live vectors) | 99.80% top-10 overlap · 98% top-1 |
| cutover recall-parity gate (drop-in binding) | 1.00 vs previous stack |
| memory integrity | ML-DSA-65 signature per write — default-on |
What’s next
The remaining arc is operational depth, not format change: long-soak burn-in under production write rates; signature enforcement mode (reject unsigned writes) for regulated tenants; agent-side signing on self-host so the signature is born on the customer’s box; and customer-held signing keys. The format stays frozen — the RFC published before the code is still the contract, and v2’s strongest result is that production never forced it to break.