aeon-memory

C++23 memory kernel for Node.js. Provides two primitives:

• Atlas — Memory-mapped vector index with SIMD-accelerated cosine similarity search (beam search, CSLS hubness correction, INT8 quantization).
• Trace — Append-only episodic event log with WAL, sidecar blob arena, and session-scoped retrieval.

Built as a native addon via node-addon-api. All hot paths are synchronous and operate on mmap'd files with zero-copy FFI.

Requirements

• macOS 14.0+ (Apple Silicon)
• Node.js ≥ 18
• Xcode Command Line Tools (for node-gyp)

Install

npm install
npm run build

npm run build compiles the C++ kernel (node-gyp rebuild) and the TypeScript wrapper (tsc).

Usage

import { AeonMemory } from "aeon-memory";

const mem = AeonMemory.getInstance();

// Check if native kernel loaded
if (!mem.isAvailable()) {
  console.error("Native addon not available");
}

// -- Trace: session event log --
mem.saveTurn("session-abc", { role: "user", content: "hello" });
mem.saveTurn("session-abc", { role: "assistant", content: "hi" });

const transcript = mem.getTranscript("session-abc");
// → [{ role: "user", content: "hello" }, { role: "assistant", content: "hi" }]

// -- Atlas: vector similarity search --
const vec = new Float32Array(1024); // your embedding
const id = mem.atlasInsert(0n, vec, "concept-name");

const results = mem.atlasNavigate(vec, 10);
// → [{ id: bigint, score: number }, ...]

// Cleanup
mem.close();

API

AeonMemory.getInstance(): AeonMemory

Lazy singleton. Initializes the native kernel on first call. If the addon is missing, all methods no-op gracefully.

Trace

| Method | Signature | Description | |---|---|---| | saveTurn | (sessionId: string, turn: unknown) → void | Append a JSON-serialized event to the WAL. Synchronous. | | getTranscript | (sessionId: string, limit?: number) → unknown[] | Retrieve session events, oldest-first. Default limit 1000. | | traceSize | () → number | Total event count. |

Atlas

| Method | Signature | Description | |---|---|---| | atlasInsert | (parentId: bigint, vector: Float32Array, metadata?: string, sessionId?: string) → bigint \| null | Insert a vector node. Returns node ID. | | atlasNavigate | (query: Float32Array, topK?: number) → Array<{ id: bigint, score: number }> | Beam search for nearest vectors. Default top-K 10, max 50. | | atlasSize | () → number | Total node count. |

Embedding

| Method | Signature | Description | |---|---|---| | getEmbedding | (text: string) → Promise<Float32Array \| null> | Fetch 1024-dim embedding from local Ollama (bge-m3). Falls back to deterministic mock if Ollama is unavailable. | | filterToolsSemantic | (prompt: string, tools: any[], topK?: number) → Promise<any[]> | One-shot tool indexing + semantic filtering via Atlas. |

Lifecycle

| Method | Signature | Description | |---|---|---| | isAvailable | () → boolean | Whether the native kernel loaded successfully. | | close | () → void | Release all C++ resources. Idempotent. |

Configuration

| Env Var | Default | Description | |---|---|---| | AEON_MEMORY_HOME | ~/.aeon-memory | Directory for Atlas and Trace data files. |

Default initialization creates two files in this directory:

• aeon_atlas.bin — Atlas vector index (1024-dim, INT8 quantization)
• aeon_trace.wal — Trace event log + sidecar blob file

Build Details

The package compiles all C++ sources from source (monolithic build). No external shared libraries required.

Sources

src/
├── aeon_node.cpp       # N-API bridge (node-addon-api)
├── core.cpp            # Build info / version
├── atlas.cpp           # SLB vector index, beam search, mmap
├── trace.cpp           # WAL, blob arena, session chains
├── simd_impl.cpp       # NEON / AVX2 / AVX-512 similarity + INT8 dot product
├── aeon_c_api.cpp      # C API (extern "C" boundary)
└── include/aeon/       # 17 headers

Compiler Flags

• C++23 (-std=c++23)
• -O3 -mcpu=apple-m4 -ffast-math -flto
• Native ARM NEON intrinsics (SIMDe bypassed on ARM64)

Output

build/Release/aeon.node   # Native addon (~307 KB)
dist/index.js             # ESM wrapper
dist/index.d.ts           # TypeScript declarations

Scripts

| Script | Command | |---|---| | npm run build | Full build (C++ + TypeScript) | | npm run build:native | C++ only (node-gyp rebuild) | | npm run build:ts | TypeScript only (tsc) | | npm run clean | Remove build artifacts |

Architecture

┌─────────────────────────────────────────────┐
│  TypeScript (AeonMemory)                    │
│  - Singleton, JSON round-trip, role mapping │
├─────────────────────────────────────────────┤
│  N-API Bridge (aeon_node.cpp)               │
│  - Zero-copy Float32Array → float*          │
│  - Synchronous method calls                 │
│  - BigInt ↔ uint64_t marshaling             │
├─────────────────────────────────────────────┤
│  C API (aeon_c_api.h)                       │
│  - extern "C", caller-allocated buffers     │
│  - No exceptions cross FFI boundary         │
├─────────────────────────────────────────────┤
│  C++23 Kernel                               │
│  - Atlas: mmap'd SLB vector index           │
│  - Trace: WAL + sidecar blob arena          │
│  - SIMD: NEON (ARM64) / AVX-512 (x86)      │
└─────────────────────────────────────────────┘

Linking

To use in another local project:

# In aeon-memory/
npm link

# In consuming project/
npm link aeon-memory

License

MIT