aioniq-trace 0.1.1

TRACE — local-first binary vector search SDK (wraps the trace_core engine)

aioniq-trace

Local-first binary vector search. TRACE compresses dense embeddings into compact binary signatures (~32× smaller) and searches them with vectorized XOR + popcount Hamming distance on the CPU — linear, streaming-append, no GPU, no network. Your data never leaves the machine.

Install as aioniq-trace, import as vector_trace.

Install

pip install aioniq-trace                 # core
pip install "aioniq-trace[text]"         # + sentence-transformers text embeddings
pip install "aioniq-trace[visual]"       # + CLIP image / text embeddings
pip install "aioniq-trace[mcp]"          # + Model Context Protocol server for agents

Quickstart

import time, vector_trace

with vector_trace.TraceIndex("~/my_index", families=["text_dated"]) as idx:
    idx.ingest("Met Dana at the harbor.", family="text_dated", timestamp=time.time())
    for r in idx.search("foggy day by the water", family="text_dated"):
        print(r.rank, round(r.confidence, 3), r.preview)

From the CLI:

trace index create -d ~/.trace/idx -f text_dated
trace index ingest "the harbor was foggy" -F text_dated -d ~/.trace/idx
trace index search "misty docks"          -F text_dated -d ~/.trace/idx
trace mcp        # run the MCP server (stdio) for AI agents

Features

• Compact & fast — sign-bit quantization (~32× smaller) + vectorized Hamming search on CPU.
• Local-first — on-disk indexes; no cloud, no telemetry.
• Multiple families — text, visual (CLIP), and persona embeddings, plus bring-your-own vectors.
• Cross-modal timeline — one time axis across families; recall_at_time() for "what was happening around then".
• Agent-ready — Python API, a trace CLI, and an MCP server exposing 7 tools.

Documentation

Guides — getting started, concepts, Python API, CLI, MCP, configuration — are in the repository: https://github.com/CalBearKen/TRACE

License

Apache-2.0 — see LICENSE. A separately-licensed commercial edition adds a hardware-accelerated engine.

Copyright © 2026 Aioniq.