Ariadne

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

Quick Start

pip install "ariadne-memory[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 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). Stored confidence from memory provenance/feedback is applied after retrieval, so approved facts outrank rejected ones without hiding their history. Results include score_parts explaining the RRF/FTS and confidence contribution.

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

context = mem.context_pack("how to deploy to production", token_budget=800)
# Compact, deterministic memory block ready for an agent prompt

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 capacity-based eviction.

Your memories are never destroyed implicitly. Eviction only runs when the store exceeds an explicit max_memories capacity (default: off) — without one, evict() is a no-op and bounding the store is your call (curator.decay(), maintenance()).

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.

Smarter recall

Two optional knobs on recall() / context_pack() improve result quality:

# MMR diversifies the top-k so you get distinct facets, not k near-duplicates.
mem.recall("deploy", k=5, mmr=0.3)

# Recency weighting floats fresh facts (recorded in score_parts — still explainable).
mem.context_pack("what did we decide?", token_budget=800, recency_boost=0.5)

Superseded facts (e.g. an API key that was rotated) are hidden by checking the whole store for an active replacement — not just the current result window — and every ranking adjustment is visible in score_parts.

Config without code

export ARIADNE_DB_PATH=~/.ariadne/memory.db
export ARIADNE_MAX_MEMORIES=100000        # optional capacity bound
# or a TOML file: AriadneConfig.from_toml("ariadne.toml")

Health checks

ariadne doctor   # index sync, FTS coverage, orphans, dangling pointers — exit 1 on failure
ariadne feedback 42 --action reject   # confidence-weighted feedback loop

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 tidy.

Drop into Claude Code (and other MCP hosts)

One command prints ready-to-merge registration JSON for Claude Code, Claude Desktop, Cursor, VS Code, and Zed:

ariadne mcp --host claude-code

For Claude Code you can also wire memory hooks — every user prompt injects a packed block of relevant memories as context, and every finished turn is recorded (optionally distilled into facts/relations by an LLM):

// ~/.claude/settings.json — snippet printed by `ariadne mcp --host claude-code`
{
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": "ariadne hook claude-code --db-path /abs/path.db" }] }
    ],
    "Stop": [
      { "hooks": [{ "type": "command", "command": "ariadne hook claude-code --db-path /abs/path.db" }] }
    ]
  }
}

Hooks are fail-open: if the memory store is unavailable, your session is not.

Dashboard auth + metrics

ariadne dashboard --token "$(openssl rand -hex 32)"   # or ARIADNE_DASHBOARD_TOKEN
curl -H "Authorization: Bearer $TOKEN" localhost:8765/api/stats
curl localhost:8765/metrics        # Prometheus text format, zero dependencies

Performance

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

pip install "ariadne-memory[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, giving your agent durable hybrid search memory with zero infrastructure.

Plugin Setup

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

Then configure Hermes to use Ariadne:

hermes config set memory.provider ariadne
hermes restart

Alternatively, set the provider in ~/.hermes/config.yaml:

memory:
  provider: ariadne

The plugin automatically creates its database at ~/.hermes/ariadne/memory.db (plus a shared surface at ~/.hermes/ariadne/shared/memory.db for cross-agent memory).

Available Tools

The plugin exposes these ariadne_* tools to Hermes:

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

Backup & Restore

Ariadne supports full database backup and restore through the CLI, the web dashboard, and the Python API. Backups are consistent SQLite snapshots (WAL checkpoint + file copy) — no daemon restart required.

CLI Commands

# Create a timestamped backup (default: arriadne-backup-YYYYMMDDTHHMMSS.db)
ariadne backup

# Backup to a specific file
ariadne backup -o /backups/my-memory.db

# Restore from a backup (creates a safety backup of the current DB first)
ariadne restore /backups/my-memory.db

# Restore without safety backup
ariadne restore /backups/my-memory.db --no-safety-backup

# Export all memories as JSON (to stdout or a file)
ariadne export
ariadne export -o memories.json

# Import memories from a JSON file
ariadne import memories.json

Dashboard UI

Launch the dashboard and use the backup/restore controls:

ariadne dashboard

The dashboard exposes two endpoints:

Python API

from arriadne import AriadneMemory, AriadneConfig

mem = AriadneMemory(config=AriadneConfig(db_path="memory.db"))

# Export all memories to a dict
data = mem.export_json()
# data contains {"memories": [...], "stats": {...}}

# Import from a previously exported dict
imported_count = mem.import_json(data)
print(f"Imported {imported_count} memories")

mem.close()

Addons

Ariadne supports domain-specific addons that extend the core memory system with specialized extractors, entity types, CLI commands, and API endpoints. Addons are separate pip packages discovered automatically via Python entry points.

Available Addons

Installing an Addon

# Install the finance addon (Excel + CSV only)
pip install ariadne-finance

# With PDF support
pip install "ariadne-finance[pdf]"

# Full (PDF + yfinance for market data)
pip install "ariadne-finance[full]"

Once installed, the addon is auto-discovered — no configuration needed:

from arriadne.addons import AddonRegistry

registry = AddonRegistry()
registry.discover()  # finds all installed addons
print(registry.addon_names)  # ['ariadne-finance']

# Use addon extractors
extractor = registry.get_extractor_for_file("report.pdf")
result = extractor.extract("report.pdf")

registry.shutdown()

Creating Your Own Addon

See docs/addons/index.md for the full addon authoring guide. Quick start:

from arriadne.addons import BaseAddon, ExtractorBase, EntityType

class MyAddon(BaseAddon):
    name = "my-addon"
    version = "0.1.0"
    description = "My custom addon"

    def get_extractors(self):
        return [MyExtractor()]

    def get_entity_types(self):
        return [EntityType(name="custom", display_name="Custom Entity")]

Register in your pyproject.toml:

[project.entry-points."ariadne.addons"]
my-addon = "my_addon:MyAddon"

License

MIT — see LICENSE.

_{Powered by Mantes}