LogosDB is the SQLite for AI Agents.
LogosDB is a fast semantic vector database written in C/C++ that provides approximate nearest-neighbor search over embedding vectors with associated text metadata.
Authors: Jose (@jose-compu)
Contributing: See CONTRIBUTING.md for build instructions, style guide, and PR workflow.
Features
- Vectors and metadata are stored as flat binary files, memory-mapped for zero-copy reads.
- Approximate nearest-neighbor search via HNSW (hnswlib), O(log n) query time.
- Each vector row carries optional text and ISO 8601 timestamp metadata (JSONL sidecar).
- The basic operations are
Put(embedding, text, timestamp), Get(id), and Search(query, top_k).
- Timestamp range filtering: search within a time window (e.g., "last 24 hours").
- Multiple distance metrics: inner product, cosine similarity (auto-normalized), or L2 Euclidean.
- Bulk vector access for direct tensor construction (e.g. loading into GPU memory).
- Thread-safe API on a single open handle: an internal mutex serializes operations that touch the index and metadata (including search).
- Crash recovery: HNSW index is automatically backfilled from the append-only vector store on open.
- Scales to millions of vectors.
- Framework integrations: LangChain and LlamaIndex VectorStore adapters.
- MCP server: first-class Claude Code integration via
logosdb-mcp-server.
Documentation
The public interface is in include/logosdb/logosdb.h. Callers should not include or rely on the details of any other header files in this package. Those internal APIs may be changed without warning.
Planning a deployment? See docs/sizing.md for disk/RAM estimates based on N×dim, or run python -m logosdb.sizing --rows 1_000_000 --dim 768.
Guide to header files:
- include/logosdb/logosdb.h: Main interface to the DB. Start here. Contains:
- C API with opaque handles and
errptr convention (RocksDB/LevelDB style)
- C++ convenience wrapper (
logosdb::DB) with RAII and exceptions
logosdb::Options for HNSW tuning and distance metric selectionlogosdb::SearchHit result structlogosdb_search_ts_range() for timestamp-filtered search
Limitations
- This is not a general-purpose vector database. It is purpose-built for embedding-based memory retrieval in LLM inference (funes.cpp).
- Only a single process (possibly multi-threaded) can access a particular database at a time.
- There is no client-server support built into the library. An application that needs such support will have to wrap their own server around the library.
- For inner-product distance (
LOGOSDB_DIST_IP, the default), vectors must be L2-normalized before insertion. Use LOGOSDB_DIST_COSINE for automatic normalization.
- Embedding generation is external — the caller provides pre-computed float vectors.
Roadmap
Work is tracked in open issues. 1.0.0 shipped on 2026-05-17; the public C API and supported language bindings follow Semantic Versioning on the 1.x line:
| Bump | When |
|---|
Patch (1.0.Z) | Bug fixes, security fixes, documentation, CI/build-only changes, and internal tooling that does not alter the supported contract of the public C API in include/logosdb/logosdb.h or the stable surface of language bindings. |
Minor (1.Y.z) | Backward-compatible additions: new functions or options, new storage or index behaviors behind explicit settings, new integrations, new platforms, and additive file-format upgrades with automatic or guided migration. |
Major (2.0.0) | Breaking changes to the public C API, on-disk format without a migration path, or binding contracts that cannot remain compatible. |
Target versions and issue assignment match GitHub milestones (each open roadmap issue has exactly one milestone).
Milestones → issues
Past releases are summarized in the CHANGELOG and the closed milestones.
SHIPPED 0.9.0 — minor — throughput and scale
- #87 — Streaming NDJSON import/export (
logosdb_export_ndjson / logosdb_import_ndjson in C / C++ / Python) with chunk_size, byte-offset --checkpoint, and --resume. Parquet output is a follow-up.
- #80 — Batch ingest v2:
logosdb_put_batch is now chunked and WAL-aware (LOGOSDB_BATCH_CHUNK_SIZE, default 1024). Durability matches per-row logosdb_put; speed-up vs single put is workload-dependent (≈1.4× at dim=64 on the bench; HNSW per-row cost dominates at larger dims).
This is the beginning of the README. Read the rest at the original. Read the full README ↗
