arriadne 0.9.1

AI agent memory system — sub-millisecond hybrid search (FAISS vector + FTS5 keyword + RRF fusion), knowledge graph traversal, cognitive retention modeling, and auto-deduplication. Zero infrastructure.

Ariadne

Memory for AI agents. Local-first hybrid search + knowledge graph. Zero infrastructure.

---

Quick Start

pip install "arriadne[embeddings]"

from arriadne import AriadneMemory
from arriadne.embeddings import SentenceTransformerEmbedder

# An embedder turns text into vectors so semantic recall works automatically.
embedder = SentenceTransformerEmbedder("all-MiniLM-L6-v2")  # 384-dim

mem = AriadneMemory(db_path="memory.db", embedding_dim=embedder.dim, embedder=embedder)

mem.remember("VPS has 4 cores, 8GB RAM", importance=0.8)

# Semantic match — "server specs" finds the memory despite sharing no keywords.
results = mem.recall("server specs", k=5)

Without the [embeddings] extra (or without an embedder), Ariadne still works as a fast keyword store — pass your own vectors to remember/recall for semantic search, or omit them for FTS-only matching:

from arriadne import AriadneMemory

mem = AriadneMemory(db_path="memory.db")          # no embedder
mem.remember("deploy script lives in infra/deploy.sh")
mem.recall("deploy script", k=5)                  # keyword match

---

Why

Most "agent memory" options make you choose: a bare vector store (Chroma, sqlite-vec), or a hosted service (Mem0). Ariadne bundles vector + keyword + graph retrieval, deduplication, and a retention model into one local SQLite file — no daemon, no server, no API keys.

Capability	Ariadne	Chroma	sqlite-vec	Mem0
Vector search	✅ FAISS (auto Flat→IVF)	✅	✅	✅
Keyword search (BM25/FTS5)	✅	❌	❌	⚠️
Hybrid fusion (RRF)	✅	⚠️ basic	❌	⚠️
Knowledge graph (multi-hop)	✅	❌	❌	⚠️
Near-duplicate dedup (MinHash)	✅	❌	❌	⚠️
Retention / forgetting curve	✅	❌	❌	⚠️
Runs fully local, no daemon	✅	✅	✅	❌
Single file, zero infra	✅	⚠️	✅	❌

Capability comparison, not a benchmark — for latency, measure on your own hardware (see Performance). ✅ built-in · ⚠️ partial/varies · ❌ not available.

---

Features

Vector search (FAISS)

In-process FAISS index. Starts as exact IndexFlatIP and auto-upgrades to IndexIVFFlat once the dataset grows past ivf_threshold. Vectors are keyed by the memory's own id (IndexIDMap2) and rebuilt from the database on open, so the index can never drift out of sync after deletes or restarts.

Hybrid retrieval

Vector similarity + BM25 keywords (SQLite FTS5), fused with Reciprocal Rank Fusion. Keyword matching tries AND first (precise) and falls back to OR (recall).

results = mem.recall("how to deploy to production", k=5)
# Runs keyword + vector search and fuses the rankings

Knowledge graph

Typed entities and relationships with multi-hop traversal via SQLite recursive CTEs. Edges are walked in both directions:

mem.add_edge("WebApp", "API", edge_type="depends_on")
mem.add_edge("API", "Database", edge_type="depends_on")
mem.graph("WebApp", hops=2)   # → API, Database

Cognitive retention

Ebbinghaus forgetting curve R = e^(-t/S). Stability S grows each time a memory is recalled (retention_growth_factor, capped) — memories strengthen with use and fade without it. Priority-weighted scoring from importance, recency, access count, and retention drives eviction.

Auto-deduplication

MinHash LSH catches near-duplicates before they enter the store; the index is rebuilt from the database on open so it survives restarts. Exact duplicates are caught by a SHA-256 content hash.

Built for agents

Thread-safe (a single AriadneMemory can be shared across threads), reads are side-effect-free, and housekeeping (evict / consolidate / prune_access_log / purge_deleted, or maintenance() for all four) keeps the store bounded.

---

Performance

Latency depends on your hardware, embedding dimension, and dataset size, so Ariadne ships no canned numbers — measure on your own box:

pip install "arriadne[embeddings]"

import time, numpy as np
from arriadne import AriadneMemory, AriadneConfig

mem = AriadneMemory(config=AriadneConfig(db_path="bench.db", embedding_dim=384))
vecs = np.random.randn(10_000, 384).astype("float32")
for i, v in enumerate(vecs):
    mem.remember(f"memory {i}", embedding=v)

q = np.random.randn(384).astype("float32")
t = time.perf_counter()
for _ in range(1000):
    mem.recall("query", embedding=q, k=10)
print(f"recall avg: {(time.perf_counter() - t):.3f} ms/query")
mem.close()

Architecturally: FAISS does similarity as a single BLAS matrix multiply (and switches to an inverted-file index at scale), keyword search rides SQLite's FTS5 BM25 index, and graph traversal is a recursive CTE — all in-process, no network hops. See the benchmarks guide for a fuller harness.

---

Hermes Agent Integration

Ariadne works as a drop-in memory provider for Hermes Agent.

# Copy plugin
git clone https://github.com/kyssta-exe/Ariadne.git /tmp/ariadne-repo
cp -r /tmp/ariadne-repo/plugin ~/.hermes/plugins/ariadne

# Switch provider
hermes config set memory.provider ariadne
hermes restart

Full guide: ariadne.mantes.net/guide/hermes

---

Configuration

from arriadne import AriadneConfig, AriadneMemory

config = AriadneConfig(
    db_path="memory.db",
    embedding_dim=384,
    faiss_type="auto",          # auto | flat_ip | ivf_flat
    dedup_threshold=0.8,
    retention_half_life=86400,  # 1 day
)

mem = AriadneMemory(config=config)

---

Documentation

ariadne.mantes.net

• Quick Start
• Installation
• Hermes Setup
• Search & Retrieval
• Knowledge Graph
• API Reference
• Benchmarks

---

License

MIT — see LICENSE.

---

_{Powered by Mantes}