# CueMap

> A deterministic, high-performance memory engine built in Rust that gives AI agents fast, accurate, and explainable context recall without external model calls.

CueMap is a high-performance temporal-associative memory store built in Rust, designed to give AI agents durable, inspectable context recall. It turns natural-language queries into deterministic cues, intersects the strongest evidence, and returns source-backed memories—without relying on external model calls or opaque vector search by default. The project is developed by cuemap-dev and is currently at v0.7.2, released in August 2026.

## What It Is

CueMap is a memory layer for AI agents and long-running assistants that need to recall information across sessions without hallucinating or losing provenance. Unlike pure vector databases, CueMap's default recall path is deterministic and ontology-free: it extracts normalized lexical cues, structural facets (dates, numbers, entities, source metadata), and recency/salience signals at write time, then resolves queries through the same deterministic normalization at read time. An optional bundled local MiniLM-L3-v2 encoder adds semantic reranking in hybrid mode without opening external network calls.

## Architecture and Core Algorithm

CueMap implements what it calls a **Continuous Gradient Algorithm** with five stages:

- **Intersection (Context Filter)**: triangulates relevant memories by overlapping cues
- **Structural Extraction**: emits deterministic cues for observable evidence such as dates, numbers, lists, and surface entities
- **Recency & Salience**: balances fresh data with high-signal events via an adaptive impact scoring module
- **Reinforcement**: frequently accessed memories gain signal strength, remaining accessible as they age
- **Sparse Recall**: uses normalized lexical cues, structural facets, recency, salience, and bounded deterministic reranking

The engine is built on Axum for async HTTP, DashMap + aHash for lock-free concurrent access, and Zstd + ChaCha20-Poly1305 for compressed, encrypted-at-rest persistence. Snapshots are stored as zstd-compressed JSON `.bin` files and restored automatically on startup.

## Performance at Scale

The v0.7.2 release benchmarks, run on a MacBook Pro M-series with 64GB RAM against 1M Wikipedia-derived memories, show:

- **Lexical recall**: 2.63 ms average, 3.72 ms P95
- **Hybrid recall** (with bundled local encoder): 8.36 ms average, 10.67 ms P95
- **Lexical write**: 3.33 ms average
- **Hybrid write**: 11.28 ms average
- Zero external model calls on the hot path

On retrieval benchmarks, the project reports 96.2% Hit@20 on LongMemEval (470 non-abstention questions, hybrid recall), 96.1% Hit@20 on LoCoMo, and 80.3% Hit@20 on BEAM at 1M scale. These are raw retrieval scores before an answer model interprets results.

## Integration and Deployment Paths

CueMap offers four access paths that all talk to the same local Rust process:

- **CLI**: `cuemap add` and `cuemap recall` from any terminal
- **Python SDK**: `pip install cuemap`
- **TypeScript SDK**: `npm install cuemap`
- **MCP Server**: `npx -y cuemap-mcp@0.7.2` — connects coding agents (Claude Code, Cursor, VS Code, OpenAI Codex, Google Antigravity, OpenCode) to the local engine
- **HTTP API**: OpenAPI 3.1 contract at `/openapi.yml`
- **Docker**: `cuemap/engine` image with bind-mounted data directory

Configuration uses a layered TOML system (CLI args > env vars > `server_config.toml` > defaults). Cloud backup is supported for AWS S3, Google Cloud Storage, and Azure Blob Storage. Authentication uses API key headers; encryption-at-rest uses ChaCha20-Poly1305 with PBKDF2 key derivation.

## Licensing and Source Availability

CueMap is released under the **Business Source License 1.1 (BSL-1.1)**, licensed by CueMap/Kaan Demirel. The BSL allows full use for development, testing, and self-hosting, but prohibits offering the engine as a competing managed database service. The Change Date is 2030-03-02, after which the license converts to Apache 2.0. Commercial licensing for closed-source SaaS or managed-service use is available by contacting the team directly.

## Features
- Deterministic cue-based recall without external model calls
- Hybrid recall with bundled local MiniLM-L3-v2 semantic reranking
- Lexical recall averaging 2.63 ms at 1M memories
- Project-isolated multi-tenant memory spaces
- MCP server for coding agent integration (Claude Code, Cursor, VS Code, Codex)
- Python and TypeScript SDKs
- HTTP API with OpenAPI 3.1 schema
- Self-learning ingestion agent with filesystem watcher
- Tree-sitter powered code chunking (Rust, Python, TypeScript, Go, Java, PHP)
- Document parsing: PDF, DOCX, XLSX, CSV, JSON, YAML, XML
- Zstd-compressed, ChaCha20-Poly1305 encrypted-at-rest snapshots
- Cloud backup: AWS S3, Google Cloud Storage, Azure Blob Storage
- Periodic and graceful-shutdown snapshot persistence
- API key authentication with multi-key support
- Configurable via TOML with layered CLI/env/config override
- Adaptive salience bias and reinforcement-based access learning
- Manual lexicon wiring and alias management
- Docker support with unprivileged container user
- Bounded reconstruction passes for long-form content
- Match integrity scoring on recall results

## Integrations
Claude Code, Cursor, VS Code, OpenAI Codex, Google Antigravity, OpenCode, AWS S3, Google Cloud Storage, Azure Blob Storage, MinIO, DigitalOcean Spaces, Docker, npm, PyPI, MCP (Model Context Protocol)

## Platforms
LINUX, API, VSC_EXTENSION, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
v0.7.2

## Links
- Website: https://cuemap.dev
- Documentation: https://cuemap.dev/docs
- Repository: https://github.com/cuemap-dev/cuemap
- EveryDev.ai: https://www.everydev.ai/tools/cuemap