Metadata-Version: 2.4
Name: arriadne
Version: 0.1.3
Summary: 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.
Project-URL: Homepage, https://github.com/kyssta-exe/Ariadne
Project-URL: Repository, https://github.com/kyssta-exe/Ariadne
Project-URL: Changelog, https://github.com/kyssta-exe/Ariadne/blob/main/CHANGELOG.md
Author-email: Kyssta <kyssta@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agent-memory,ai-agent,deduplication,embedding,faiss,fts5,hybrid-search,knowledge-graph,llm,memory,rag,retrieval,semantic-search,vector-search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: datasketch>=1.5.0
Requires-Dist: faiss-cpu>=1.7.4
Requires-Dist: numpy>=1.24.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# Ariadne

Memory for AI agents. Sub-millisecond search. Zero infrastructure.

[![PyPI](https://img.shields.io/pypi/v/arriadne.svg)](https://pypi.org/project/arriadne/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Tests](https://img.shields.io/badge/tests-143%20passed-brightgreen)](https://github.com/kyssta-exe/Ariadne/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

---

## Quick Start

```python
from arriadne import AriadneMemory

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

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

results = mem.recall("server specs", k=5)
```

```bash
pip install arriadne
```

---

## Why

| | Ariadne | Mnemosyne | Mem0 | ChromaDB |
|---|:---:|:---:|:---:|:---:|
| Vector search | **0.89ms** | 153ms | 12ms | 8ms |
| Hybrid search | ✅ RRF | ❌ | ❌ | ⚠️ basic |
| Knowledge graph | ✅ BFS | ⚠️ basic | ❌ | ❌ |
| Auto-dedup | ✅ MinHash | ❌ | ❌ | ❌ |
| Runs locally | ✅ | ✅ | ❌ | ✅ |
| No daemon | ✅ | ✅ | ❌ | ❌ |

---

## Features

### 0.89ms Vector Search

FAISS-powered. 12× faster than sqlite-vec. Auto-upgrades from exact to approximate search as your data grows.

| Engine | 10K vectors |
|--------|:-----------:|
| FAISS (Ariadne) | **0.89ms** |
| sqlite-vec | 10.5ms |

### Hybrid Retrieval

Vector similarity + BM25 keywords + graph traversal, fused with Reciprocal Rank Fusion. 90%+ recall@10 (with semantic embeddings).

```python
results = mem.recall("how to deploy to production", k=5)
# Searches both "deploy" (keyword) and semantic similarity in parallel
```

### Knowledge Graph

Typed entities and relationships with multi-hop traversal via SQLite recursive CTEs:

```python
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 with stability growth on each access. Priority-weighted scoring from importance, recency, and access count. Memories strengthen with use, fade without it.

### Auto-Deduplication

MinHash LSH catches near-duplicates at 1.25ms before they enter the system.

---

## Performance

Benchmarked on a 4-core 8GB VPS, 10K memories, 384-dim embeddings:

| Operation | Latency |
|-----------|---------|
| Vector search (FAISS) | **0.89ms** |
| Keyword search (FTS5) | **1.74ms** |
| Hybrid search (RRF) | **2.46ms** |
| Dedup check (MinHash) | **1.25ms** |
|| Memory insert | **0.85ms** |
| Graph traversal (3 hops) | **0.06ms** |

---

## Hermes Agent Integration

Ariadne works as a drop-in memory provider for [Hermes Agent](https://hermes-agent.nousresearch.com/).

```bash
# 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](https://ariadne.mantes.net/guide/hermes)

---

## Configuration

```python
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](https://ariadne.mantes.net)**

- [Quick Start](https://ariadne.mantes.net/guide/quick-start)
- [Installation](https://ariadne.mantes.net/guide/installation)
- [Hermes Setup](https://ariadne.mantes.net/guide/hermes)
- [Search & Retrieval](https://ariadne.mantes.net/guide/search)
- [Knowledge Graph](https://ariadne.mantes.net/guide/graph)
- [API Reference](https://ariadne.mantes.net/api/)
- [Benchmarks](https://ariadne.mantes.net/benchmarks)

---

## License

MIT — see [LICENSE](LICENSE).

---

<p align="center">
  <sub>Powered by <a href="https://mantes.net">Mantes</a></sub>
</p>
