HippocampAI — Enterprise Memory Engine for Intelligent AI Systems

HippocampAI is a production-ready, enterprise-grade memory engine that transforms how AI systems remember, reason, and learn from interactions. It provides persistent, intelligent memory capabilities that enable AI agents to maintain context across sessions, understand user preferences, detect behavioral patterns, and deliver truly personalized experiences.

The name "HippocampAI" draws inspiration from the hippocampus - the brain region responsible for memory formation and retrieval - reflecting our mission to give AI systems human-like memory capabilities.

Current Release: v0.5.1 — Bug-fix and API expansion release: batch endpoints, deduplication endpoint, single-memory GET, Prometheus scrape in main app, remote backend URL fixes, QueryRouter stem matching, Groq retry tuning, and SQL packaging fix.

HippocampAI is organized into two main components for flexibility:

# Core library only (lightweight)
from hippocampai.core import MemoryClient, Memory, Config

# SaaS platform features
from hippocampai.platform import run_api_server, AutomationController

# Or use the main package (includes everything, backward compatible)
from hippocampai import MemoryClient

git clone https://github.com/rexdivakar/HippocampAI.git
cd HippocampAI

# Copy and edit environment file
cp .env.example .env
# Required: set GROQ_API_KEY (or switch LLM_PROVIDER=ollama and point LLM_BASE_URL to your instance)
# Required for production: set USER_AUTH_ENABLED=true and JWT_SECRET

docker compose up -d

Services started:

Verify the API is up:

curl http://localhost:8000/healthz
# {"status":"ok"}

# Core library (lightweight - 10 dependencies)
pip install hippocampai

# With SaaS features (API, auth, background tasks)
pip install "hippocampai[saas]"

# With specific LLM providers
pip install "hippocampai[openai]"     # OpenAI support
pip install "hippocampai[anthropic]"  # Anthropic Claude
pip install "hippocampai[groq]"       # Groq support

# Everything (development, all features)
pip install "hippocampai[all,dev]"

from hippocampai import MemoryClient

# Initialize client
client = MemoryClient()

# Store a memory
memory = client.remember(
    "I prefer oat milk in my coffee and work remotely on Tuesdays",
    user_id="alice",
    type="preference"
)

# Recall memories
results = client.recall("work preferences", user_id="alice")
print(f"Found: {results[0].memory.text}")

That's it! You now have intelligent memory for your AI application.

• Built-in Intelligence: Pattern detection, insights, behavioral analysis
• Memory Types: Facts, preferences, goals, habits, events (not just vectors)
• Temporal Reasoning: Native time-based queries and narratives

• 5-100x Faster: Redis caching, optimized retrieval
• Deployment Flexibility: Local, self-hosted, or SaaS
• Full Control: Complete source access and customization

• Ready in Minutes: pip install hippocampai
• 102+ Methods: Complete API covering all use cases
• Production-Tested: Battle-tested in real applications

See detailed comparison →

Complete documentation is available in the docs/ directory.

Complete Documentation Index - Browse all 26 documentation files organized by topic

Core Documentation:

• API Reference - All 102+ methods with examples
• Features Overview - Comprehensive feature documentation
• Architecture - System design and components
• Configuration - All configuration options

Advanced Topics:

• New Features - Plugins, namespaces, export/import, offline mode, tiered storage
• Multi-Agent Features - Agent coordination
• Intelligence Features - Fact extraction, entity recognition
• Temporal Analytics - Time-based queries
• Session Management - Conversation tracking

Production & Operations:

• User Guide - Production deployment
• Security - Security best practices
• Monitoring - Observability and metrics
• Backup & Recovery - Data protection

All variables are read from .env (or shell environment). Complete list is in .env.example.

Infrastructure

LLM

Retrieval and scoring

Feature flags

Half-lives (days)

# .env file
QDRANT_URL=http://localhost:6333      # local Qdrant; use http://qdrant:6333 inside Docker
LLM_PROVIDER=ollama
LLM_MODEL=qwen2.5:7b-instruct

# Library usage — no running server required
from hippocampai import MemoryClient

client = MemoryClient()  # reads .env automatically

memory = client.remember("I prefer dark mode", user_id="alice", type="preference")
results = client.recall("UI settings", user_id="alice", k=3)

from hippocampai.backends.remote import RemoteBackend
from hippocampai import MemoryClient

client = MemoryClient(backend=RemoteBackend(
    api_url="http://localhost:8000",
    api_key="your-api-key",   # omit if USER_AUTH_ENABLED=false
    timeout=90,
))

memory = client.remember("Alice joined in January", user_id="alice")
results = client.recall("when did Alice join", user_id="alice", k=5)

from hippocampai import MemoryClient
from hippocampai.adapters import GroqLLM

client = MemoryClient(
    llm_provider=GroqLLM(api_key="your-key"),
    qdrant_url="https://your-qdrant-cluster.com",
    redis_url="redis://your-redis:6379"
)

See all configuration options →

All endpoints are served by the FastAPI application on port 8000. Interactive docs available at http://localhost:8000/docs.

docker run -d -p 6333:6333 qdrant/qdrant
pip install hippocampai

git clone https://github.com/rexdivakar/HippocampAI.git
cd HippocampAI
cp .env.example .env
# Edit .env: set GROQ_API_KEY, optionally set USER_AUTH_ENABLED=true
docker compose up -d

Includes:

• FastAPI server (port 8000)
• React Dashboard (port 81)
• Celery workers with Beat scheduler
• Flower monitoring (port 5555)
• Prometheus metrics (port 9090)
• Grafana dashboards (port 3002)

cd frontend
npm install
npm run dev  # Development server on port 5173

Production deployment guide →

1. Authentication is disabled by default. USER_AUTH_ENABLED=false in docker-compose defaults. All /v1/* endpoints are open with no auth check. Set USER_AUTH_ENABLED=true and configure JWT_SECRET in .env.

2. Default credentials in .env.example — replace before deploying:

   • HIPPOCAMPAI_API_KEY=example_key_do_not_use
   • FLOWER_PASSWORD=changeme_in_production
   • GRAFANA_ADMIN_PASSWORD=changeme_in_production

3. GROQ_API_KEY in plain-text .env — for production, inject via Docker secrets, AWS Secrets Manager, or HashiCorp Vault. Never commit .env to git. (.env is in .gitignore.)

4. Single uvicorn worker — --workers 1 in the docker-compose command. Under concurrent LLM-backed requests the single worker threadpool will saturate. Run multiple workers (--workers 4) or place a process manager (gunicorn) in front.

5. No TLS — all services communicate over plain HTTP. Add nginx or Caddy as a TLS-terminating reverse proxy in front of port 8000.

6. Groq free-tier rate limits — 30 RPM. High-throughput writes to /v1/memories:remember and /v1/memories:extract (which call the LLM for type classification and extraction) will hit this limit and retry. Options: upgrade to Groq Dev Tier, switch to a self-hosted LLM (LLM_PROVIDER=ollama), or pass type explicitly in remember requests to skip LLM classification.

7. admin_ui/ directory is empty — the hippocampai-admin container (nginx on port 3001) serves 403 because the directory has no files. Either populate it or remove the service from docker-compose.

8. Frontend Docker healthcheck reports unhealthy — Vite dev server responds on / but the healthcheck hits a different path. Change the healthcheck to curl -f http://localhost:81/ or switch to the production build.

9. QDRANT_URL in .env — the default is http://localhost:6333 which works for local library use. When running inside Docker compose, the API container needs QDRANT_URL=http://qdrant:6333 (already set in docker-compose.yml via the service DNS name).

10. Celery worker healthcheck disabled — healthcheck: disable: true in docker-compose. Production should enable Flower-based or custom health monitoring for Celery workers.

11. AUTO_CONSOLIDATION_ENABLED=false — memory consolidation (sleep-phase replay) is off by default. Set to true to enable nightly automatic consolidation.

• ENABLE_PROCEDURAL_MEMORY=false — procedural memory and prompt self-optimization
• ENABLE_PROSPECTIVE_MEMORY=false — time- and event-triggered intent system
• HIPPOCAMPAI_ENABLE_TMS=false — truth maintenance system (retraction and contradiction detection)

AI Agents & Chatbots

• Personalized assistants with context across sessions
• Customer support with interaction history
• Educational tutoring that adapts to students

Enterprise Applications

• Knowledge management for teams
• CRM enhancement with interaction intelligence
• Compliance monitoring and audit trails

Research & Analytics

• Behavioral pattern analysis
• Long-term trend detection
• User experience personalization

More use cases →

See benchmarks →

• Documentation: Complete guides
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Discord: Join our community

Over 25 working examples in the examples/ directory:

# Basic operations
python examples/01_basic_usage.py

# Advanced features
python examples/11_intelligence_features_demo.py
python examples/13_temporal_reasoning_demo.py
python examples/14_cross_session_insights_demo.py

# New v0.4.0 features
python examples/20_collaboration_demo.py      # Multi-agent collaboration
python examples/21_predictive_analytics_demo.py  # Predictive analytics
python examples/22_auto_healing_demo.py       # Auto-healing pipeline
python examples/consolidation_demo.py         # Memory consolidation

View all examples →

We welcome contributions! See our Contributing Guide for details.

git clone https://github.com/rexdivakar/HippocampAI.git
cd HippocampAI
pip install -e ".[dev]"
pytest

Apache 2.0 - Use freely in commercial and open-source projects.

If you find HippocampAI useful, please star the repo! It helps others discover the project.

Built with by the HippocampAI team

from hippocampai import MemoryClient

client = MemoryClient()

# Core operations
memory = client.remember("text", user_id="alice")
results = client.recall("query", user_id="alice", k=5)
client.update_memory(memory_id, text="new text")
client.delete_memory(memory_id)

# Intelligence
facts = client.extract_facts("John works at Google")
entities = client.extract_entities("Elon Musk founded SpaceX")
patterns = client.detect_patterns(user_id="alice")

# Analytics
habits = client.detect_habits(user_id="alice")
changes = client.track_behavior_changes(user_id="alice")
stats = client.get_memory_statistics(user_id="alice")

# Sessions
session = client.create_session(user_id="alice", title="Planning")
client.complete_session(session.id, generate_summary=True)

# Bi-Temporal Facts (NEW)
from hippocampai.models.bitemporal import BiTemporalQuery
fact = client.store_bitemporal_fact(
    user_id="alice",
    subject="alice",
    predicate="works_at",
    object_value="Acme Corp",
    valid_from=datetime(2024, 1, 1),
)
facts = client.query_bitemporal_facts(BiTemporalQuery(
    user_id="alice",
    valid_at=datetime(2024, 6, 1),
))

# Context Assembly (NEW)
from hippocampai.context.models import ContextConstraints
context = client.assemble_context(
    user_id="alice",
    query="What are Alice's work preferences?",
    constraints=ContextConstraints(token_budget=4000),
)
print(context.final_context_text)

# Custom Schema Validation (NEW)
from hippocampai.schema import SchemaRegistry
registry = SchemaRegistry()
result = registry.validate_entity("person", {"name": "Alice"})

# Relevance Feedback (NEW v0.5.0)
client.rate_recall(
    memory_id=results[0].memory.id,
    user_id="alice",
    query="coffee preferences",
    feedback_type="relevant"
)

# See docs/LIBRARY_COMPLETE_REFERENCE.md for the full method reference

Full API Reference | REST API Reference