ariadne

name	ariadne
description	Ariadne memory system for Hermes — FAISS + FTS5 + knowledge graph + cognitive retention. Local-first, zero daemon.
version	1.0.0
author	hermes
license	MIT
platforms	["linux","macos"]
metadata	{"hermes":{"tags":["memory","ai-agent","FAISS","knowledge-graph","search","hermes-plugin"],"homepage":"https://ariadne-memory.readthedocs.io"}}

Ariadne — Memory System for Hermes

Ariadne is a local-first memory system for AI agents. It replaces Mnemosyne as the Hermes memory provider with a hybrid search engine: FAISS vector search + SQLite FTS5 keyword search + Reciprocal Rank Fusion, plus a knowledge graph with typed edges and multi-hop traversal, MinHash LSH near-duplicate deduplication, and an Ebbinghaus forgetting curve for cognitive retention. No cloud, no daemon, no API keys.

Features at a Glance

Capability	Details
Vector search	FAISS (auto Flat→IVF at scale)
Keyword search	SQLite FTS5 BM25
Hybrid fusion	Reciprocal Rank Fusion (RRF)
Knowledge graph	Typed edges, multi-hop traversal via recursive CTEs
Deduplication	MinHash LSH + SHA-256 content hash
Retention	Ebbinghaus forgetting curve (stability grows with use)
Shared memory	Cross-agent surface via separate DB
Storage	Single SQLite file (~/.hermes/ariadne/memory.db)

Setup

1. Install the Python package

pip install ariadne-memory

With embeddings support (recommended):

pip install "ariadne-memory[embeddings]"

2. Install the Hermes plugin

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

Or manually create ~/.hermes/plugins/ariadne/ with __init__.py and plugin.yaml from the repo.

3. Switch the provider

hermes config set memory.provider ariadne

Or edit ~/.hermes/config.yaml:

memory:
  provider: ariadne

4. Migrate from Mnemosyne (optional)

If you have existing Mnemosyne memories:

ariadne migrate ~/.hermes/mnemosyne/data/mnemosyne.db \
  --db-path ~/.hermes/ariadne/memory.db

Or export to JSON first and import:

ariadne export -o /tmp/mnemosyne-export.json \
  --db-path ~/.hermes/mnemosyne/data/mnemosyne.db
ariadne import /tmp/mnemosyne-export.json \
  --db-path ~/.hermes/ariadne/memory.db

5. Restart and verify

hermes restart

Then ask Hermes: "Check memory status" — you should see "engine": "Ariadne" in the output.

File Layout

~/.hermes/
├── plugins/
│   └── ariadne/
│       ├── __init__.py     # MemoryProvider implementation
│       └── plugin.yaml     # Plugin metadata + tool schemas
└── ariadne/
    ├── memory.db           # SQLite: memories, graph, embeddings, metadata
    └── shared/
        └── memory.db       # Cross-agent shared memory surface

Plugin Tools

Ariadne exposes these tools through the Hermes MemoryProvider interface with the ariadne_ prefix.

Core Memory Tools

Tool	Purpose	Key Params
ariadne_remember	Store a new memory	content, importance (0-1), memory_type, entities, metadata
ariadne_recall	Search memories (hybrid vector+keyword)	query, limit, type_filter, importance_min
ariadne_forget	Delete a memory by ID	memory_id
ariadne_update	Update memory content or metadata	memory_id, content, importance, metadata
ariadne_invalidate	Soft-delete / mark memory inactive	memory_id
ariadne_stats	Database statistics	(none)

Knowledge Graph Tools

Tool	Purpose	Key Params
ariadne_graph_link	Create a typed edge between entities	source, target, relationship, weight
ariadne_graph_query	Traverse the graph from an entity	entity, hops (default 2)

Export / Import

Tool	Purpose	Key Params
ariadne_export	Export all memories as JSON	output_path
ariadne_import	Import memories from JSON	input_path

Scratchpad (ephemeral notes)

Tool	Purpose	Key Params
ariadne_scratchpad_write	Write a scratchpad note	content
ariadne_scratchpad_read	Read all scratchpad notes	(none)
ariadne_scratchpad_clear	Clear scratchpad	(none)

Shared Memory (cross-agent)

Tool	Purpose	Key Params
ariadne_shared_remember	Store in shared surface	content, importance, memory_type
ariadne_shared_recall	Search shared surface	query, limit
ariadne_shared_forget	Delete from shared surface	memory_id
ariadne_shared_stats	Shared surface statistics	(none)

Diagnostics & Maintenance

Tool	Purpose	Key Params
ariadne_diagnose	Health check + version info	(none)
ariadne_sleep	Run full maintenance cycle (consolidate + lifecycle)	dry_run

CLI Commands

The ariadne CLI provides direct database access outside of Hermes:

# Initialize a new database
ariadne init --db-path ~/.hermes/ariadne/memory.db --dim 384

# Add a memory
ariadne add "Deploy script lives in infra/deploy.sh" \
  --type semantic --importance 0.8 --db-path ~/.hermes/ariadne/memory.db

# Search memories
ariadne search "deploy script" -k 5 --db-path ~/.hermes/ariadne/memory.db

# Show stats
ariadne stats --db-path ~/.hermes/ariadne/memory.db

# Export/import JSON
ariadne export -o backup.json --db-path ~/.hermes/ariadne/memory.db
ariadne import backup.json --db-path ~/.hermes/ariadne/memory.db

# Run maintenance (consolidate + evict + prune)
ariadne maintain --db-path ~/.hermes/ariadne/memory.db

Backup & Restore

# Create a consistent backup (WAL checkpoint + copy)
ariadne backup --db-path ~/.hermes/ariadne/memory.db \
  -o ~/.hermes/ariadne/backup-$(date +%Y%m%dT%H%M%S).db

# Restore from backup (creates safety backup first)
ariadne restore ~/.hermes/ariadne/backup-20260101T120000.db \
  --db-path ~/.hermes/ariadne/memory.db

# Restore without safety backup
ariadne restore ~/.hermes/ariadne/backup-20260101T120000.db \
  --db-path ~/.hermes/ariadne/memory.db --no-safety-backup

Quick backup shortcut (copies all files):

cp -r ~/.hermes/ariadne ~/backup/ariadne-$(date +%Y%m%d)

Dashboard

Ariadne includes a web dashboard for visualizing memory stats, the knowledge graph, and search results.

# Install dashboard dependency
pip install "ariadne[dashboard]"

# Launch dashboard
ariadne dashboard --host 0.0.0.0 --port 8765

# Without auto-opening browser
ariadne dashboard --host 0.0.0.0 --port 8765 --no-browser

Open http://localhost:8765 in a browser. The dashboard provides:

• Memory count and type breakdown
• Knowledge graph visualization (interactive)
• Search interface
• Lifecycle tier distribution (hot/warm/cold)
• FAISS index stats

Best Practices

Memory Quality

• Set importance thoughtfully (0.0–1.0): facts the agent needs long-term should be 0.7+; ephemeral context can be 0.3–0.5.
• Use memory_type to categorize: semantic (facts/preferences), procedural (how-to), episodic (events/conversations).
• Add entities when storing memories — this feeds the knowledge graph and improves graph traversal queries.

Maintenance

• Run ariadne_sleep periodically (e.g., on cron or at session end) to consolidate duplicates and age out stale memories.
• Use dry_run: true on consolidate/prune first to see what would be affected before committing.
• Back up before maintenance: ariadne backup before large consolidation or pruning runs.

Graph Usage

• Link related entities with ariadne_graph_link as the agent discovers relationships.
• Query with hops=2 or 3 for most use cases; higher hops are slower and usually unnecessary.

Shared Memory

• Use ariadne_shared_* tools for knowledge that should persist across agent sessions or be shared between multiple Hermes agents.
• The shared surface lives at ~/.hermes/ariadne/shared/memory.db — back it up separately if needed.

Performance

• FAISS auto-upgrades from FlatIP to IndexIVFFlat as the dataset grows — no manual tuning needed.
• The vector index is rebuilt from the database on every startup, so there's no separate index file to manage.
• For very large datasets (100K+ memories), the IVF index provides sub-millisecond recall.

Reverting to Mnemosyne

hermes config set memory.provider mnemosyne
hermes restart

Or disable the plugin without removing it:

mv ~/.hermes/plugins/ariadne ~/.hermes/plugins/ariadne.disabled
hermes restart

Addons

Ariadne supports domain-specific addons via Python entry_points. Addons are separate pip packages that register via the ariadne.addons entry_points group and are auto-discovered at runtime.

Available Addons

Addon	Description	Install
ariadne-finance	PDF/Excel extraction, ticker recognition, financial knowledge graph	pip install ariadne-finance

Finance Addon

# Core (Excel + CSV only)
pip install ariadne-finance

# With PDF support (marker-pdf + pdfplumber)
pip install "ariadne-finance[pdf]"

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

CLI usage:

ariadne finance ingest report.pdf --importance 0.8
ariadne finance search "NVDA revenue Q3"
ariadne finance tickers report.txt

Dashboard API: GET /api/finance/tickers?text=..., GET /api/finance/classify?text=..., POST /api/finance/ingest

Creating Custom Addons

from arriadne.addons import BaseAddon, ExtractorBase, EntityType

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

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

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

    def get_cli_commands(self):
        from arriadne.addons import CLICommand
        return [CLICommand(name="my-cmd", help_text="My command", handler=my_handler)]

Register in pyproject.toml:

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

Addons provide: extractors, entity types, CLI commands, API routes, search filters, graph relationships. See docs/addons/index.md for the full authoring guide.

Pitfalls

• Non-editable install required. Use pip install . not pip install -e .. Editable installs create .pth files that can shadow other packages in the same namespace (e.g., ariadne_finance shadowed by stale ariadne editable finder).
• Optional deps guard. PDF extraction requires marker-pdf and pdfplumber. Always wrap in try/except ImportError with helpful install message.
• Entity canonicalization. Add canonical entity names on ingress (lowercase, strip, deduplicate) to prevent fragmentation: "Mailcow" vs "mailcow" vs " mailcow ".

References

• Docs: https://ariadne-memory.readthedocs.io
• GitHub: https://github.com/kyssta-exe/Ariadne
• PyPI: https://pypi.org/project/ariadne-memory/
• Hermes Guide: https://ariadne-memory.readthedocs.io/guide/hermes
• Addon docs: docs/addons/index.md, docs/addons/finance.md
• Finance addon: addons/finance/