# HippocampAI — Autonomous Memory Engine for LLM Agents
[](https://pypi.org/project/hippocampai/)
[](https://pypi.org/project/hippocampai/)
[](https://pepy.tech/project/hippocampai)
[](https://sonar.craftedbrain.com/dashboard?id=rexdivakar_HippocampAI_6669aa8c-2e81-4016-9993-b29a3a78c475)
HippocampAI turns raw conversations into a curated long-term memory vault for your AI assistants. It extracts, scores, deduplicates, stores, and retrieves user memories so agents can stay personal, consistent, and context-aware across sessions.
- **Plug-and-play** `MemoryClient` API with built-in pipelines for extraction, dedupe, consolidation, and importance decay
- **Hybrid retrieval** that fuses dense vectors, BM25, reciprocal-rank fusion, reranking, recency, and importance signals
- **Self-hosted first** — works fully offline via Qdrant + Ollama or in the cloud via OpenAI with the same code paths
- **Production-ready** — automatic retry logic, structured JSON logging, request tracing, telemetry, typed models, and scheduled jobs
- **Fully customizable** — every component (extraction, retrieval, scoring) is extensible without vendor lock-in
**Current Release:** v1.0.0 — first major stable release of HippocampAI.
---
## ✨ Why HippocampAI
- **Persistent personalization** – store preferences, facts, goals, habits, and events per user with importance scoring and decay
- **Reliable retrieval** – hybrid ranking surfaces the right memories even when queries are vague or drift semantically
- **Automatic hygiene** – extractor, deduplicator, consolidator, and scorer keep the memory base uncluttered
- **Local-first** – run everything on your infra with open models, or flip a switch to activate OpenAI for higher quality
- **Built-in telemetry** – track all memory operations with detailed tracing and metrics (similar to Mem0 platform)
- **Extensible Python SDK** – customize every stage without being locked to a hosted API
---
## 🚀 Quick Start
### 1. Installation
**Install from PyPI (Recommended):**
```bash
# Install with core dependencies
pip install hippocampai
# Or install with additional providers
pip install "hippocampai[all]" # All providers + API + Web
pip install "hippocampai[openai]" # Just OpenAI
pip install "hippocampai[api]" # FastAPI server
pip install "hippocampai[web]" # Flask web interface
```
View on PyPI: [https://pypi.org/project/hippocampai/](https://pypi.org/project/hippocampai/)
**Or install from source:**
```bash
git clone https://github.com/rexdivakar/HippocampAI.git
cd HippocampAI
# Install with core dependencies
pip install -e .
# Or install with additional providers
pip install -e ".[all]" # All providers + API + Web
pip install -e ".[openai]" # Just OpenAI
pip install -e ".[api]" # FastAPI server
pip install -e ".[web]" # Flask web interface
```
### 2. Start Qdrant
```bash
docker run -p 6333:6333 qdrant/qdrant
```
### 3. Configure Environment
```bash
cp .env.example .env
```
Edit `.env` and set your configuration:
```bash
# Basic settings
QDRANT_URL=http://localhost:6333
LLM_PROVIDER=ollama
LLM_MODEL=qwen2.5:7b-instruct
# For cloud providers (optional)
# LLM_PROVIDER=openai
# OPENAI_API_KEY=sk-your-key-here
# ALLOW_CLOUD=true
```
### 4. Initialize Collections
```bash
python -c "from hippocampai import MemoryClient; MemoryClient()"
```
---
## 💡 Basic Usage
```python
from hippocampai import MemoryClient
# Initialize client
client = MemoryClient()
# Store a memory
memory = client.remember(
text="I prefer oat milk in my coffee",
user_id="alice",
type="preference",
importance=8.0,
tags=["beverages", "preferences"]
)
# Memory size is automatically tracked
print(f"Memory size: {memory.text_length} chars, {memory.token_count} tokens")
# Recall relevant memories
results = client.recall(
query="How does Alice like her coffee?",
user_id="alice",
k=3
)
for result in results:
print(f"{result.memory.text} (score: {result.score:.3f})")
# Get memory statistics
stats = client.get_memory_statistics(user_id="alice")
print(f"Total memories: {stats['total_memories']}")
print(f"Total size: {stats['total_characters']} chars, {stats['total_tokens']} tokens")
```
### Async Usage
```python
from hippocampai import AsyncMemoryClient
import asyncio
async def main():
client = AsyncMemoryClient()
# Store memories concurrently
tasks = [
client.remember_async(f"Memory {i}", user_id="alice")
for i in range(10)
]
memories = await asyncio.gather(*tasks)
# Async recall
results = await client.recall_async(
query="What do you know about me?",
user_id="alice",
k=5
)
asyncio.run(main())
```
---
## 🎯 Features
### Core Memory Operations
- **CRUD Operations** — remember, recall, update, delete with telemetry tracking
- **Automatic extraction** from conversations using heuristics or LLM
- **Deduplication** with semantic similarity and reranking
- **Importance scoring** with configurable decay
- **Multi-user isolation** — complete data separation per user
- **Memory size tracking** — automatic character and token counting
- **Async support** — async variants of all core operations for high-performance apps
### Hybrid Retrieval
HippocampAI combines multiple retrieval strategies:
1. **Vector search** — semantic similarity using embeddings
2. **BM25** — keyword matching for precision
3. **Reciprocal rank fusion** — merges both signals
4. **Cross-encoder reranking** — precision refinement
5. **Score fusion** — combines similarity, reranking, recency, and importance
```python
results = client.recall(query="coffee preferences", user_id="alice", k=5)
for result in results:
print(f"Score breakdown:")
print(f" Similarity: {result.breakdown['sim']:.3f}")
print(f" Rerank: {result.breakdown['rerank']:.3f}")
print(f" Recency: {result.breakdown['recency']:.3f}")
print(f" Importance: {result.breakdown['importance']:.3f}")
```
### Conversation Extraction
```python
conversation = """
User: I really enjoy drinking green tea in the morning.
Assistant: That's great! Green tea is healthy.
User: Yes, and I usually have it without sugar.
"""
memories = client.extract_from_conversation(
conversation=conversation,
user_id="bob",
session_id="session_001"
)
print(f"Extracted {len(memories)} memories")
```
### Advanced Features
```python
# Batch operations
memories_data = [
{"text": "I like Python", "tags": ["programming"]},
{"text": "I prefer dark mode", "type": "preference"},
]
created = client.add_memories(memories_data, user_id="alice")
# Graph relationships
client.add_relationship(
source_id=created[0].id,
target_id=created[1].id,
relation_type=RelationType.RELATED_TO
)
# Version control
history = client.get_memory_history(memory_id)
client.rollback_memory(memory_id, version_number=1)
# Context injection for LLMs
prompt = client.inject_context(
prompt="What are my preferences?",
query="user preferences",
user_id="alice",
k=5
)
# Memory statistics
stats = client.get_memory_statistics(user_id="alice")
print(f"Total: {stats['total_memories']} memories")
print(f"Size: {stats['total_characters']} chars, {stats['total_tokens']} tokens")
print(f"By type: {stats['by_type']}")
```
### Telemetry & Observability
```python
# Memory operations are automatically tracked
client.remember(text="I love Python", user_id="alice")
client.recall(query="What do I like?", user_id="alice")
# Access telemetry via client
metrics = client.get_telemetry_metrics()
print(f"Average recall time: {metrics['recall_duration']['avg']:.2f}ms")
print(f"Average memory size: {metrics['memory_size_chars']['avg']:.1f} chars")
# Get recent operations
operations = client.get_recent_operations(limit=10)
for op in operations:
print(f"{op.operation.value}: {op.duration_ms:.2f}ms ({op.status})")
```
---
## 📚 Examples
Explore working examples in the `examples/` directory:
```bash
# Basic usage
python examples/01_basic_usage.py
# Conversation extraction
python examples/02_conversation_extraction.py
# Hybrid retrieval
python examples/03_hybrid_retrieval.py
# Custom configuration
python examples/04_custom_configuration.py
# Multi-user management
python examples/05_multi_user.py
# Batch operations
python examples/06_batch_operations.py
# Advanced features (graph, version control, context injection, etc.)
python examples/07_advanced_features_demo.py
# Memory consolidation scheduler
python examples/08_scheduler_demo.py
# Graph persistence (JSON export/import)
python examples/09_graph_persistence_demo.py
# Production resilience (retry logic + structured logging)
python examples/example_resilience.py
# Run all examples
./run_examples.sh
```
---
## ⚙️ Configuration
### Environment Variables
See `.env.example` for all configuration options:
- **Qdrant** settings (URL, collections, HNSW tuning)
- **Embedding** model selection and parameters
- **LLM** provider (ollama, openai, anthropic, groq)
- **Retrieval** weights and parameters
- **Decay** half-lives per memory type
- **Jobs** scheduling (importance decay, consolidation)
### Custom Configuration
```python
from hippocampai import MemoryClient, Config
# Option 1: Override specific parameters
client = MemoryClient(
qdrant_url="http://localhost:6333",
weights={"sim": 0.6, "rerank": 0.2, "recency": 0.1, "importance": 0.1}
)
# Option 2: Create custom config object
config = Config(
embed_model="BAAI/bge-small-en-v1.5",
llm_provider="ollama",
llm_model="qwen2.5:7b-instruct",
top_k_final=10
)
client = MemoryClient(config=config)
```
---
## 📖 Documentation
### Getting Started
- **[Quick Start Guide](docs/QUICKSTART.md)** - Get up and running in 5 minutes
- **[Getting Started](docs/GETTING_STARTED.md)** - Detailed installation, setup, and first steps
- **[Usage Guide](docs/USAGE.md)** - Common usage patterns, chat clients, and integration examples
### Core Documentation
- **[API Reference](docs/API_REFERENCE.md)** - Complete API documentation for all methods and classes
- **[Features Guide](docs/FEATURES.md)** - Comprehensive feature documentation with examples and use cases
- **[Configuration Guide](docs/CONFIGURATION.md)** - All configuration options, presets, and environment variables
- **[Provider Setup](docs/PROVIDERS.md)** - Configure LLM providers (Ollama, OpenAI, Anthropic, Groq)
### Advanced Guides
- **[Resilience & Observability](docs/RESILIENCE.md)** - Automatic retry logic, error handling, and structured logging
- **[Telemetry Guide](docs/TELEMETRY.md)** - Observability, tracing, metrics, and performance monitoring
- **[Testing Guide](docs/TESTING_GUIDE.md)** - Complete testing guide with 117 tests and 100% pass rate
### Examples & Tutorials
- **[Examples Documentation](docs/examples.md)** - Guide to all working examples in the `examples/` directory
- See the [Examples section](#-examples) above for a complete list of runnable examples
### Developer Resources
- **[Package Summary](docs/PACKAGE_SUMMARY.md)** - Technical overview of the package architecture and structure
- **[Implementation Summary](docs/IMPLEMENTATION_SUMMARY.md)** - Implementation details of core features and components
- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute to HippocampAI
- **[Changelog](docs/CHANGELOG.md)** - Version history, updates, and breaking changes
---
**Need help?** Join our community: [Discord](https://discord.gg/pPSNW9J7gB)
---
## 🆚 HippocampAI vs Mem0
| Feature | HippocampAI | Mem0 |
|---------|-------------|------|
| **Deployment** | ✅ Self-hosted first, cloud optional | ❌ SaaS-first |
| **Customization** | ✅ Full pipeline control | ❌ Limited API surface |
| **Retrieval** | ✅ Hybrid (vector + BM25 + rerank + decay) | ⚠️ Vector-first |
| **Memory hygiene** | ✅ Built-in extraction, dedupe, consolidation | ⚠️ Manual or implicit |
| **Telemetry** | ✅ Built-in tracing & metrics | ✅ Platform dashboard |
| **Data residency** | ✅ Your infra, your data | ❌ Managed cloud |
| **Setup complexity** | ⚠️ Requires Qdrant | ✅ Zero infra |
| **Cost** | ✅ Free (self-hosted) | ⚠️ Usage-based pricing |
**Choose HippocampAI when:**
- You need full control and customization
- Data residency is critical
- You want to avoid vendor lock-in
- You're building production systems requiring observability
**Choose Mem0 when:**
- You want zero infrastructure management
- You're prototyping quickly
- You don't mind managed services
---
## 🗺️ Roadmap
**Completed (v1.0.0):**
- [x] Configuration presets (`.from_preset("local")`, `.from_preset("cloud")`)
- [x] Built-in telemetry and observability
- [x] Automatic retry logic for Qdrant and LLM operations
- [x] Structured JSON logging with request ID tracking
- [x] Batch operations (add_memories, delete_memories)
- [x] Graph indexing and relationships
- [x] Version control and rollback
- [x] Context injection for LLM prompts
- [x] Memory access tracking
- [x] Advanced filtering and sorting
- [x] Snapshots and audit trail
- [x] KV store for fast lookups
- [x] Memory size tracking (text_length, token_count)
- [x] Async variants for all core operations
- [x] Memory consolidation scheduler (background jobs)
- [x] Persistent graph storage (JSON export/import)
**Planned:**
- [ ] LangChain and LlamaIndex integrations
- [ ] Retrieval evaluators and A/B testing
- [ ] Multi-tenant RBAC and access policies
- [ ] Native TypeScript SDK
- [ ] Grafana/Prometheus metrics exporters
- [ ] WebSocket support for real-time updates
Contributions welcome! Open issues or PRs to shape HippocampAI's direction.
---
## 📄 License
Apache 2.0 — See [LICENSE](LICENSE) for details.
---
## 🤝 Contributing
We welcome contributions! Please see our [contributing guidelines](CONTRIBUTING.md) for details.
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests (`pytest`)
5. Commit your changes
6. Push to the branch
7. Open a Pull Request
---
## 🌟 Star History
If you find HippocampAI useful, please star the repo! It helps others discover the project.
---
## 📧 Contact
- **Issues**: [GitHub Issues](https://github.com/rexdivakar/HippocampAI/issues)
- **Discord**: [Join our community](https://discord.gg/pPSNW9J7gB)
Built with ❤️ by the HippocampAI team
Raw data
{
"_id": null,
"home_page": null,
"name": "hippocampai",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Rex Divakar <rexdivakar@hotmail.com>",
"keywords": "llm, memory, rag, retrieval, vector-database, qdrant, ai, embeddings, semantic-search",
"author": "HippocampAI Contributors",
"author_email": "Rex Divakar <rexdivakar@hotmail.com>",
"download_url": "https://files.pythonhosted.org/packages/9c/57/030fc22e42592ce9f6e744850bb9d186bb89b1d43c0e436867c90e13a445/hippocampai-1.0.0.tar.gz",
"platform": null,
"description": "# HippocampAI \u2014 Autonomous Memory Engine for LLM Agents\n\n[](https://pypi.org/project/hippocampai/)\n[](https://pypi.org/project/hippocampai/)\n[](https://pepy.tech/project/hippocampai)\n[](https://sonar.craftedbrain.com/dashboard?id=rexdivakar_HippocampAI_6669aa8c-2e81-4016-9993-b29a3a78c475)\n\nHippocampAI turns raw conversations into a curated long-term memory vault for your AI assistants. It extracts, scores, deduplicates, stores, and retrieves user memories so agents can stay personal, consistent, and context-aware across sessions.\n\n- **Plug-and-play** `MemoryClient` API with built-in pipelines for extraction, dedupe, consolidation, and importance decay\n- **Hybrid retrieval** that fuses dense vectors, BM25, reciprocal-rank fusion, reranking, recency, and importance signals\n- **Self-hosted first** \u2014 works fully offline via Qdrant + Ollama or in the cloud via OpenAI with the same code paths\n- **Production-ready** \u2014 automatic retry logic, structured JSON logging, request tracing, telemetry, typed models, and scheduled jobs\n- **Fully customizable** \u2014 every component (extraction, retrieval, scoring) is extensible without vendor lock-in\n\n**Current Release:** v1.0.0 \u2014 first major stable release of HippocampAI.\n\n---\n\n## \u2728 Why HippocampAI\n\n- **Persistent personalization** \u2013 store preferences, facts, goals, habits, and events per user with importance scoring and decay\n- **Reliable retrieval** \u2013 hybrid ranking surfaces the right memories even when queries are vague or drift semantically\n- **Automatic hygiene** \u2013 extractor, deduplicator, consolidator, and scorer keep the memory base uncluttered\n- **Local-first** \u2013 run everything on your infra with open models, or flip a switch to activate OpenAI for higher quality\n- **Built-in telemetry** \u2013 track all memory operations with detailed tracing and metrics (similar to Mem0 platform)\n- **Extensible Python SDK** \u2013 customize every stage without being locked to a hosted API\n\n---\n\n## \ud83d\ude80 Quick Start\n\n### 1. Installation\n\n**Install from PyPI (Recommended):**\n\n```bash\n# Install with core dependencies\npip install hippocampai\n\n# Or install with additional providers\npip install \"hippocampai[all]\" # All providers + API + Web\npip install \"hippocampai[openai]\" # Just OpenAI\npip install \"hippocampai[api]\" # FastAPI server\npip install \"hippocampai[web]\" # Flask web interface\n```\n\nView on PyPI: [https://pypi.org/project/hippocampai/](https://pypi.org/project/hippocampai/)\n\n**Or install from source:**\n\n```bash\ngit clone https://github.com/rexdivakar/HippocampAI.git\ncd HippocampAI\n\n# Install with core dependencies\npip install -e .\n\n# Or install with additional providers\npip install -e \".[all]\" # All providers + API + Web\npip install -e \".[openai]\" # Just OpenAI\npip install -e \".[api]\" # FastAPI server\npip install -e \".[web]\" # Flask web interface\n```\n\n### 2. Start Qdrant\n\n```bash\ndocker run -p 6333:6333 qdrant/qdrant\n```\n\n### 3. Configure Environment\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` and set your configuration:\n\n```bash\n# Basic settings\nQDRANT_URL=http://localhost:6333\nLLM_PROVIDER=ollama\nLLM_MODEL=qwen2.5:7b-instruct\n\n# For cloud providers (optional)\n# LLM_PROVIDER=openai\n# OPENAI_API_KEY=sk-your-key-here\n# ALLOW_CLOUD=true\n```\n\n### 4. Initialize Collections\n\n```bash\npython -c \"from hippocampai import MemoryClient; MemoryClient()\"\n```\n\n---\n\n## \ud83d\udca1 Basic Usage\n\n```python\nfrom hippocampai import MemoryClient\n\n# Initialize client\nclient = MemoryClient()\n\n# Store a memory\nmemory = client.remember(\n text=\"I prefer oat milk in my coffee\",\n user_id=\"alice\",\n type=\"preference\",\n importance=8.0,\n tags=[\"beverages\", \"preferences\"]\n)\n\n# Memory size is automatically tracked\nprint(f\"Memory size: {memory.text_length} chars, {memory.token_count} tokens\")\n\n# Recall relevant memories\nresults = client.recall(\n query=\"How does Alice like her coffee?\",\n user_id=\"alice\",\n k=3\n)\n\nfor result in results:\n print(f\"{result.memory.text} (score: {result.score:.3f})\")\n\n# Get memory statistics\nstats = client.get_memory_statistics(user_id=\"alice\")\nprint(f\"Total memories: {stats['total_memories']}\")\nprint(f\"Total size: {stats['total_characters']} chars, {stats['total_tokens']} tokens\")\n```\n\n### Async Usage\n\n```python\nfrom hippocampai import AsyncMemoryClient\nimport asyncio\n\nasync def main():\n client = AsyncMemoryClient()\n\n # Store memories concurrently\n tasks = [\n client.remember_async(f\"Memory {i}\", user_id=\"alice\")\n for i in range(10)\n ]\n memories = await asyncio.gather(*tasks)\n\n # Async recall\n results = await client.recall_async(\n query=\"What do you know about me?\",\n user_id=\"alice\",\n k=5\n )\n\nasyncio.run(main())\n```\n\n---\n\n## \ud83c\udfaf Features\n\n### Core Memory Operations\n\n- **CRUD Operations** \u2014 remember, recall, update, delete with telemetry tracking\n- **Automatic extraction** from conversations using heuristics or LLM\n- **Deduplication** with semantic similarity and reranking\n- **Importance scoring** with configurable decay\n- **Multi-user isolation** \u2014 complete data separation per user\n- **Memory size tracking** \u2014 automatic character and token counting\n- **Async support** \u2014 async variants of all core operations for high-performance apps\n\n### Hybrid Retrieval\n\nHippocampAI combines multiple retrieval strategies:\n\n1. **Vector search** \u2014 semantic similarity using embeddings\n2. **BM25** \u2014 keyword matching for precision\n3. **Reciprocal rank fusion** \u2014 merges both signals\n4. **Cross-encoder reranking** \u2014 precision refinement\n5. **Score fusion** \u2014 combines similarity, reranking, recency, and importance\n\n```python\nresults = client.recall(query=\"coffee preferences\", user_id=\"alice\", k=5)\n\nfor result in results:\n print(f\"Score breakdown:\")\n print(f\" Similarity: {result.breakdown['sim']:.3f}\")\n print(f\" Rerank: {result.breakdown['rerank']:.3f}\")\n print(f\" Recency: {result.breakdown['recency']:.3f}\")\n print(f\" Importance: {result.breakdown['importance']:.3f}\")\n```\n\n### Conversation Extraction\n\n```python\nconversation = \"\"\"\nUser: I really enjoy drinking green tea in the morning.\nAssistant: That's great! Green tea is healthy.\nUser: Yes, and I usually have it without sugar.\n\"\"\"\n\nmemories = client.extract_from_conversation(\n conversation=conversation,\n user_id=\"bob\",\n session_id=\"session_001\"\n)\n\nprint(f\"Extracted {len(memories)} memories\")\n```\n\n### Advanced Features\n\n```python\n# Batch operations\nmemories_data = [\n {\"text\": \"I like Python\", \"tags\": [\"programming\"]},\n {\"text\": \"I prefer dark mode\", \"type\": \"preference\"},\n]\ncreated = client.add_memories(memories_data, user_id=\"alice\")\n\n# Graph relationships\nclient.add_relationship(\n source_id=created[0].id,\n target_id=created[1].id,\n relation_type=RelationType.RELATED_TO\n)\n\n# Version control\nhistory = client.get_memory_history(memory_id)\nclient.rollback_memory(memory_id, version_number=1)\n\n# Context injection for LLMs\nprompt = client.inject_context(\n prompt=\"What are my preferences?\",\n query=\"user preferences\",\n user_id=\"alice\",\n k=5\n)\n\n# Memory statistics\nstats = client.get_memory_statistics(user_id=\"alice\")\nprint(f\"Total: {stats['total_memories']} memories\")\nprint(f\"Size: {stats['total_characters']} chars, {stats['total_tokens']} tokens\")\nprint(f\"By type: {stats['by_type']}\")\n```\n\n### Telemetry & Observability\n\n```python\n# Memory operations are automatically tracked\nclient.remember(text=\"I love Python\", user_id=\"alice\")\nclient.recall(query=\"What do I like?\", user_id=\"alice\")\n\n# Access telemetry via client\nmetrics = client.get_telemetry_metrics()\nprint(f\"Average recall time: {metrics['recall_duration']['avg']:.2f}ms\")\nprint(f\"Average memory size: {metrics['memory_size_chars']['avg']:.1f} chars\")\n\n# Get recent operations\noperations = client.get_recent_operations(limit=10)\nfor op in operations:\n print(f\"{op.operation.value}: {op.duration_ms:.2f}ms ({op.status})\")\n```\n\n---\n\n## \ud83d\udcda Examples\n\nExplore working examples in the `examples/` directory:\n\n```bash\n# Basic usage\npython examples/01_basic_usage.py\n\n# Conversation extraction\npython examples/02_conversation_extraction.py\n\n# Hybrid retrieval\npython examples/03_hybrid_retrieval.py\n\n# Custom configuration\npython examples/04_custom_configuration.py\n\n# Multi-user management\npython examples/05_multi_user.py\n\n# Batch operations\npython examples/06_batch_operations.py\n\n# Advanced features (graph, version control, context injection, etc.)\npython examples/07_advanced_features_demo.py\n\n# Memory consolidation scheduler\npython examples/08_scheduler_demo.py\n\n# Graph persistence (JSON export/import)\npython examples/09_graph_persistence_demo.py\n\n# Production resilience (retry logic + structured logging)\npython examples/example_resilience.py\n\n# Run all examples\n./run_examples.sh\n```\n\n---\n\n## \u2699\ufe0f Configuration\n\n### Environment Variables\n\nSee `.env.example` for all configuration options:\n\n- **Qdrant** settings (URL, collections, HNSW tuning)\n- **Embedding** model selection and parameters\n- **LLM** provider (ollama, openai, anthropic, groq)\n- **Retrieval** weights and parameters\n- **Decay** half-lives per memory type\n- **Jobs** scheduling (importance decay, consolidation)\n\n### Custom Configuration\n\n```python\nfrom hippocampai import MemoryClient, Config\n\n# Option 1: Override specific parameters\nclient = MemoryClient(\n qdrant_url=\"http://localhost:6333\",\n weights={\"sim\": 0.6, \"rerank\": 0.2, \"recency\": 0.1, \"importance\": 0.1}\n)\n\n# Option 2: Create custom config object\nconfig = Config(\n embed_model=\"BAAI/bge-small-en-v1.5\",\n llm_provider=\"ollama\",\n llm_model=\"qwen2.5:7b-instruct\",\n top_k_final=10\n)\n\nclient = MemoryClient(config=config)\n```\n\n---\n\n## \ud83d\udcd6 Documentation\n\n### Getting Started\n\n- **[Quick Start Guide](docs/QUICKSTART.md)** - Get up and running in 5 minutes\n- **[Getting Started](docs/GETTING_STARTED.md)** - Detailed installation, setup, and first steps\n- **[Usage Guide](docs/USAGE.md)** - Common usage patterns, chat clients, and integration examples\n\n### Core Documentation\n\n- **[API Reference](docs/API_REFERENCE.md)** - Complete API documentation for all methods and classes\n- **[Features Guide](docs/FEATURES.md)** - Comprehensive feature documentation with examples and use cases\n- **[Configuration Guide](docs/CONFIGURATION.md)** - All configuration options, presets, and environment variables\n- **[Provider Setup](docs/PROVIDERS.md)** - Configure LLM providers (Ollama, OpenAI, Anthropic, Groq)\n\n### Advanced Guides\n\n- **[Resilience & Observability](docs/RESILIENCE.md)** - Automatic retry logic, error handling, and structured logging\n- **[Telemetry Guide](docs/TELEMETRY.md)** - Observability, tracing, metrics, and performance monitoring\n- **[Testing Guide](docs/TESTING_GUIDE.md)** - Complete testing guide with 117 tests and 100% pass rate\n\n### Examples & Tutorials\n\n- **[Examples Documentation](docs/examples.md)** - Guide to all working examples in the `examples/` directory\n- See the [Examples section](#-examples) above for a complete list of runnable examples\n\n### Developer Resources\n\n- **[Package Summary](docs/PACKAGE_SUMMARY.md)** - Technical overview of the package architecture and structure\n- **[Implementation Summary](docs/IMPLEMENTATION_SUMMARY.md)** - Implementation details of core features and components\n- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute to HippocampAI\n- **[Changelog](docs/CHANGELOG.md)** - Version history, updates, and breaking changes\n\n---\n\n**Need help?** Join our community: [Discord](https://discord.gg/pPSNW9J7gB)\n\n---\n\n## \ud83c\udd9a HippocampAI vs Mem0\n\n| Feature | HippocampAI | Mem0 |\n|---------|-------------|------|\n| **Deployment** | \u2705 Self-hosted first, cloud optional | \u274c SaaS-first |\n| **Customization** | \u2705 Full pipeline control | \u274c Limited API surface |\n| **Retrieval** | \u2705 Hybrid (vector + BM25 + rerank + decay) | \u26a0\ufe0f Vector-first |\n| **Memory hygiene** | \u2705 Built-in extraction, dedupe, consolidation | \u26a0\ufe0f Manual or implicit |\n| **Telemetry** | \u2705 Built-in tracing & metrics | \u2705 Platform dashboard |\n| **Data residency** | \u2705 Your infra, your data | \u274c Managed cloud |\n| **Setup complexity** | \u26a0\ufe0f Requires Qdrant | \u2705 Zero infra |\n| **Cost** | \u2705 Free (self-hosted) | \u26a0\ufe0f Usage-based pricing |\n\n**Choose HippocampAI when:**\n\n- You need full control and customization\n- Data residency is critical\n- You want to avoid vendor lock-in\n- You're building production systems requiring observability\n\n**Choose Mem0 when:**\n\n- You want zero infrastructure management\n- You're prototyping quickly\n- You don't mind managed services\n\n---\n\n## \ud83d\uddfa\ufe0f Roadmap\n\n**Completed (v1.0.0):**\n\n- [x] Configuration presets (`.from_preset(\"local\")`, `.from_preset(\"cloud\")`)\n- [x] Built-in telemetry and observability\n- [x] Automatic retry logic for Qdrant and LLM operations\n- [x] Structured JSON logging with request ID tracking\n- [x] Batch operations (add_memories, delete_memories)\n- [x] Graph indexing and relationships\n- [x] Version control and rollback\n- [x] Context injection for LLM prompts\n- [x] Memory access tracking\n- [x] Advanced filtering and sorting\n- [x] Snapshots and audit trail\n- [x] KV store for fast lookups\n- [x] Memory size tracking (text_length, token_count)\n- [x] Async variants for all core operations\n- [x] Memory consolidation scheduler (background jobs)\n- [x] Persistent graph storage (JSON export/import)\n\n**Planned:**\n\n- [ ] LangChain and LlamaIndex integrations\n- [ ] Retrieval evaluators and A/B testing\n- [ ] Multi-tenant RBAC and access policies\n- [ ] Native TypeScript SDK\n- [ ] Grafana/Prometheus metrics exporters\n- [ ] WebSocket support for real-time updates\n\nContributions welcome! Open issues or PRs to shape HippocampAI's direction.\n\n---\n\n## \ud83d\udcc4 License\n\nApache 2.0 \u2014 See [LICENSE](LICENSE) for details.\n\n---\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see our [contributing guidelines](CONTRIBUTING.md) for details.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run tests (`pytest`)\n5. Commit your changes\n6. Push to the branch\n7. Open a Pull Request\n\n---\n\n## \ud83c\udf1f Star History\n\nIf you find HippocampAI useful, please star the repo! It helps others discover the project.\n\n---\n\n## \ud83d\udce7 Contact\n\n- **Issues**: [GitHub Issues](https://github.com/rexdivakar/HippocampAI/issues)\n- **Discord**: [Join our community](https://discord.gg/pPSNW9J7gB)\n\nBuilt with \u2764\ufe0f by the HippocampAI team\n",
"bugtrack_url": null,
"license": null,
"summary": "HippocampAI \u2014 autonomous long-term memory engine with hybrid retrieval and cross-encoder reranking",
"version": "1.0.0",
"project_urls": {
"Changelog": "https://github.com/rexdivakar/HippocampAI/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/rexdivakar/HippocampAI#readme",
"Homepage": "https://github.com/rexdivakar/HippocampAI",
"Issue Tracker": "https://github.com/rexdivakar/HippocampAI/issues",
"Repository": "https://github.com/rexdivakar/HippocampAI"
},
"split_keywords": [
"llm",
" memory",
" rag",
" retrieval",
" vector-database",
" qdrant",
" ai",
" embeddings",
" semantic-search"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f472c906dc5a134616c250c8f394da76c12a2b7f30b5af80dba9be2742abd06b",
"md5": "5e7120c237589ba594f3429bc05ef328",
"sha256": "3ef28daadcc1d6120f63847773af3f27ab25dfcc86fc0d895d250654644dafb6"
},
"downloads": -1,
"filename": "hippocampai-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5e7120c237589ba594f3429bc05ef328",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 80108,
"upload_time": "2025-10-21T17:28:38",
"upload_time_iso_8601": "2025-10-21T17:28:38.175525Z",
"url": "https://files.pythonhosted.org/packages/f4/72/c906dc5a134616c250c8f394da76c12a2b7f30b5af80dba9be2742abd06b/hippocampai-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9c57030fc22e42592ce9f6e744850bb9d186bb89b1d43c0e436867c90e13a445",
"md5": "ff2b68015138564a18b5780ace9328bb",
"sha256": "0fe609b1370cb5b0c0cbabf8396764e78b1b8bce91a16e54116c28eb96b5ab7a"
},
"downloads": -1,
"filename": "hippocampai-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "ff2b68015138564a18b5780ace9328bb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 69999,
"upload_time": "2025-10-21T17:28:39",
"upload_time_iso_8601": "2025-10-21T17:28:39.236433Z",
"url": "https://files.pythonhosted.org/packages/9c/57/030fc22e42592ce9f6e744850bb9d186bb89b1d43c0e436867c90e13a445/hippocampai-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-21 17:28:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rexdivakar",
"github_project": "HippocampAI",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "qdrant-client",
"specs": [
[
">=",
"1.7.0"
]
]
},
{
"name": "sentence-transformers",
"specs": [
[
">=",
"2.2.0"
]
]
},
{
"name": "anthropic",
"specs": [
[
">=",
"0.39.0"
]
]
},
{
"name": "openai",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "groq",
"specs": [
[
">=",
"0.4.0"
]
]
},
{
"name": "pyyaml",
"specs": [
[
">=",
"6.0"
]
]
},
{
"name": "python-json-logger",
"specs": [
[
">=",
"2.0.7"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "pydantic-settings",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
"==",
"2.12.3"
]
]
},
{
"name": "flask",
"specs": [
[
">=",
"3.0.0"
]
]
},
{
"name": "flask-cors",
"specs": [
[
">=",
"4.0.0"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.31.0"
]
]
}
],
"lcname": "hippocampai"
}
JSON
