Uteke

Give your AI a memory that never leaves your machine.

Offline-first semantic memory engine — single binary, zero config, 30ms recall.

🇬🇧 English · 🇮🇩 Bahasa Indonesia

Quick Start

# Install (macOS, Linux, Windows)
curl -sSL codecora.dev/install | sh

# Store a memory with metadata
uteke remember "Deploy v2.1 to staging" --tags deploy,staging \
  --entity staging-server --category infrastructure

# Hybrid search (vector + FTS5, ranked by RRF)
uteke recall "when do we deploy?"

# Stats
uteke stats

That's it. No API keys. No Docker. No Python. First run downloads the embedding model (~188MB) and you're good to go.

📖 Install options · Pre-built binaries · Docker · Full docs

Docker

Listens on localhost only by default. See Docker docs for auth setup.

# One-liner (model downloads on first run, cached in volume)
docker run -d --name uteke -p 127.0.0.1:8767:8767 -v uteke-data:/data \
  ghcr.io/codecoradev/uteke:latest

# Or from Docker Hub
docker run -d --name uteke -p 127.0.0.1:8767:8767 -v uteke-data:/data \
  codecoradev/uteke:latest

# Or docker compose
docker compose up -d

📖 Docker docs · Compose file

Why Uteke?

AI agents forget everything between sessions. Uteke gives them persistent, searchable memory — entirely offline, in one binary.

Key Features

• 🧠 Hybrid Search — Vector similarity + FTS5 full-text search, merged by Reciprocal Rank Fusion (RRF)
• 🏠 Rooms — Group memories by context (meetings, projects) with author attribution
• ⏳ Time-travel queries — Recall memories as they existed at any point in time
• 🔌 Pluggable embeddings — Swap ONNX/OpenAI/Ollama backends via config
• 🏷️ Metadata Enrichment — Tag, entity, category, and key:value metadata on every memory
• 🔗 Relationship graph — Link memories with typed edges (supersedes, contradicts, references)
• 📉 Smart decay — Composite importance scoring, pin critical memories
• ⚡ Recall cache — LRU cache eliminates redundant embedding for repeated queries
• 📊 Benchmarks — Built-in uteke bench for perf testing + LongMemEval retrieval harness
• 👥 Multi-Agent Namespaces — Fully isolated memory per agent, zero overhead
• 🖥️ Server Mode — Persistent daemon with ~42ms warm recall (75x faster than CLI)
• 🔥 Tiered Memory — Hot/Warm/Cold tracking with auto-cleanup of stale memories
• 🔒 Fully Offline — Local ONNX embeddings (768d), no telemetry, no cloud, no API calls
• 🔄 Embed Fallback — Gracefully falls back to cloud API if local embedder fails; MockEmbedder for testing
• 📂 Batch Import — Import entire directories (--batch-dir) with auto-strategy routing (document vs. memory extraction)
• 📦 Single Binary — Zero dependencies. No Docker, no database server, no Python, no API keys
• 📥 Import/Export — JSONL-based backup and restore
• 🧩 Memory Types — Typed categories (fact, procedure, decision, etc.) with auto-inference
• 🔗 Backlinks — Bidirectional memory edges — references are automatically reciprocal
• 📜 Timeline Events — Chronological audit log per memory (created, updated, superseded)
• 📈 Salience + Recency — Dual-axis recall boost by memory type and age
• 🌙 Dream Cycle — One-command maintenance pipeline (lint → backlinks → dedup → orphans)
• 🔍 Orphan Detection — Find disconnected, low-importance memories for cleanup
• 📎 Citations — Source attribution on every memory (URL, file, user, import)
• 🔌 MCP Server — JSON-RPC over stdio + Streamable HTTP transport

• 📝 Document Engine — Wiki/knowledge base with uteke doc create/get/list and auto-chunking

• 🤖 Cosine Auto-Linking — Automatically creates similar_to edges between related memories

• 🌐 Graph API — GET /graph returns nodes + edges JSON; POST /graph/edge and DELETE /graph/edge for mutation
• 🔑 View-Only API Keys — Read-only tokens for safe GET-only access to the server
• 📄 Markdown Chunker — Splits documents by headings, respects code blocks and token limits

🔌 MCP Server — configure with Claude Code, Cursor, Hermes

// .mcp.json (Claude Code, Cursor)
{ "mcpServers": { "uteke": { "command": "uteke-mcp" } } }

See MCP docs for Claude Desktop, Hermes, and HTTP transport.

📖 Full documentation · CLI reference · Configuration

Architecture

Hybrid search pipeline:

• HNSW (usearch) — vector similarity, finds by meaning
• FTS5 (SQLite) — full-text keyword search, finds by exact terms
• Reciprocal Rank Fusion (k=60) — merges both ranked lists → best of both worlds
• Local ONNX (EmbeddingGemma Q4, 768d) — embeddings computed on-device, no API calls

Everything runs in-process. No network. No cloud. No server required (unless you want server mode).

Development

cargo build --workspace        # Build
cargo test --workspace         # Test (327 unit tests)
cargo clippy -- -D warnings    # Lint
cargo fmt                      # Format

See CONTRIBUTING.md for the full contribution guide.

License

Apache License 2.0 — use it, fork it, ship it.

Star History