hieromem 1.0.0a1

Hierarchical Episodic Memory System for AI agents with graph-based semantic storage

HIEROMEM 🧠

Hierarchical Episodic Memory System - A memory framework for AI agents with graph-based semantic storage and multi-tenant support.

🚀 Features

Core Memory System

• Hierarchical Episodes: Organize memories in parent-child relationships with automatic summarization
• Graph-Based Storage: Neo4j-powered semantic graph for complex relationship queries
• Vector Search: FAISS-accelerated similarity search with sentence transformers
• Multi-Tenant: Isolated namespaces with per-tenant rate limiting and quotas

Production-Ready Infrastructure

• 🔒 Security: TLS/HTTPS via Nginx, API key management with expiration/revocation
• 💾 Data Persistence: Automated daily backups (SQLite, Neo4j, FAISS) with disaster recovery
• 📊 Observability: Prometheus metrics, Loki logging, Grafana dashboards
• ⚡ Scalability: Redis-backed distributed rate limiting, resource limits, health checks
• 🐳 Containerized: Full Docker Compose stack with health checks and graceful shutdown

🚀 HIEROMEM Engine v1.0 (Stabilization)

[!IMPORTANT] Active Development: The v1.0 engine is in stabilization phase. Test suite and documentation are being aligned with implementation.

This version contains:

• ✅ Episode Management – Hierarchical memory organization with parent-child relationships
• ✅ Dual Retrieval – Hybrid vector + symbolic graph search for comprehensive recall
• ✅ Trust Decay + Forgetting – Automatic memory aging and pruning based on access patterns
• ✅ Graph Merge + Relation Extraction – Semantic relationship discovery and consolidation
• ✅ Encoder Selection – Support for HuggingFace, Sentence Transformers, CLIP, Wav2Vec2
• ✅ Governance Safety Region – Configurable λ (trust threshold), τ (decay rate), θ (similarity), forbidden relations
• ✅ Narrative Summarization – Automatic episode summarization for hierarchical compression
• ✅ Event Log + Metrics – Prometheus instrumentation and structured logging
• ✅ Multi-Tenant Namespaces – Isolated memory spaces with per-tenant quotas and governance
• ✅ OAuth2/OIDC Authentication – Enterprise SSO support (Auth0, Okta, Google)
• ✅ Role-Based Access Control – Fine-grained permissions for memory operations
• ✅ Cross-Realm Isolation – Secure memory boundaries between agent realms with validation
• ✅ AWS Neptune Backend – Production-scale graph storage with Gremlin query support
• ✅ LLM Client Abstraction – Unified interface for OpenAI and local HuggingFace models
• ✅ Benchmark CI Integration – Automated retrieval quality, temporal QA, and latency benchmarks

This is the stable API surface for Cloud deployment. Additional features will be added in v1.1+ after Cloud launch.

📋 Table of Contents

• Quick Start
• Developer Guide - Complete integration guide
• Architecture
• API Documentation
• Configuration
• Deployment
• Monitoring
• Development
• Contributing
• SDK Quickstarts
• Compliance

🎯 Quick Start

Option A: Zero-Config (No Docker)

Get started in 3 commands - no Docker, Neo4j, or Redis required:

pip install hieromem
cd examples
python quickstart.py

from hieromem_core.memory import Memory
from hieromem_core.encoder import Encoder, EncoderConfig

# Initialize
encoder = Encoder(EncoderConfig())
memory = Memory(Nmax=100, encoder=encoder)

# Store
vector = encoder.encode_single("Alice works at Acme Corp")
memory.insert(vector=vector, meta={"text": "Alice works at Acme Corp"})

# Retrieve (vector + graph)
results = memory.dual_retrieve(query_text="Who works at Acme?", k=3)
print(results.results[0].text)  # "Alice works at Acme Corp"

See examples/quickstart.py for a complete working example.

Option B: Full Stack (Docker)

For production deployments with Neo4j, Redis, and monitoring:

Prerequisites

• Docker & Docker Compose
• Python 3.11+ (for local development)
• 8GB RAM minimum

1. Clone the Repository

git clone https://github.com/Rishikiran98/HIEROMEM.git
cd HIEROMEM

2. Configure Environment

cp .env.example .env
# Edit .env with your configuration

3. Start the Stack

docker compose up -d

4. Access Services

• API: http://localhost:8000
• Visualizer: http://localhost:5173
• Grafana: http://localhost:3000 (admin/admin)
• Prometheus: http://localhost:9090
• Neo4j Browser: http://localhost:7474

5. Create an API Key

docker compose exec hieromem-api python -m hieromem_api.key_management create my-tenant --days 90

6. Test the API

curl -X POST http://localhost:8000/memory/remember \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "default",
    "event_type": "user_action",
    "content": "User completed onboarding tutorial",
    "metadata": {"user_id": "123", "duration_seconds": 45}
  }'

📦 SDK Quickstarts

Python

pip install sdks/python

from hieromem_client import HieromemClient

client = HieromemClient(base_url="http://localhost:8000", api_key="YOUR_KEY")
client.remember("hello world", namespace="demo")
print(client.recall("hello"))

JavaScript

npm install ./sdks/javascript

import { HieromemClient } from "@hieromem/sdk";

const client = new HieromemClient({ baseUrl: "http://localhost:8000", apiKey: "YOUR_KEY" });
await client.remember("hello world", { namespace: "demo" });
console.log(await client.recall("hello"));

Go

go get github.com/Rishikiran98/hieromem/sdks/go

import (
        "context"
        "fmt"

        hieromem "github.com/Rishikiran98/hieromem/sdks/go"
)

client := hieromem.NewClient("http://localhost:8000", "YOUR_KEY")
resp, _ := client.Recall(context.Background(), hieromem.RecallRequest{Query: "hello"})
fmt.Println(resp)

🤖 Agent SDK

The HIEROMEM Agent SDK provides high-level abstractions for building memory-aware AI agents.

Installation

pip install -e ./packages/hieromem_agent

LLM Client

The LLMClient supports both OpenAI API and local HuggingFace models:

from hieromem_agent import LLMClient, LLMConfig

# OpenAI (default)
client = LLMClient(LLMConfig(model="gpt-4o-mini"))
response = client.complete("What is 2+2?")

# Local HuggingFace model
import os
os.environ["HIEROMEM_LLM_PROVIDER"] = "local_huggingface"
client = LLMClient(LLMConfig(model="Qwen/Qwen2.5-1.5B-Instruct"))
response = client.complete("What is 2+2?")

Memory Agent

from hieromem_agent import MemoryAgent
from hieromem_core.memory import Memory

memory = Memory(Nmax=100, encoder=encoder)
agent = MemoryAgent(memory=memory, llm_client=client)

# Agent with persistent memory
response = agent.chat("Remember that my favorite color is blue")
response = agent.chat("What is my favorite color?")  # Uses memory retrieval

🔐 Cross-Realm Isolation (Multi-Agent)

HIEROMEM supports secure memory isolation between agents with cross-realm access controls:

from hieromem_core.realms import (
    MemoryRealm,
    check_permission,
    validate_cross_realm_access,
    get_accessible_realms,
    CrossRealmAccessError
)

# Create isolated realms
private_realm = MemoryRealm(name="agent-private", type="private")
shared_realm = MemoryRealm(name="team-shared", type="shared")

# Check permissions before access
accessible = get_accessible_realms(realms, agent_id="agent-1", required="read")

# Validate cross-realm references
if validate_cross_realm_access(source_realm, target_realm, agent_id):
    # Safe to create cross-realm reference
    pass

📊 Benchmarks

HIEROMEM includes automated benchmarks for measuring system performance:

Benchmark	Description	Metrics
Retrieval Quality	Measures recall@k, precision, MRR	benchmarks/retrieval_quality.py
Temporal QA	Tests temporal reasoning with memory conflicts	benchmarks/temporal_qa.py
Latency	Measures insert/retrieve latency at scale	benchmarks/latency_benchmark.py

Running Benchmarks

cd benchmarks
python retrieval_quality.py --output results/retrieval.json
python temporal_qa.py --output results/temporal.json
python latency_benchmark.py --output results/latency.json

Benchmarks run automatically on push to main via GitHub Actions.

🏢 Enterprise Features

Enterprise features are disabled by default. Enable them with:

export HIEROMEM_ENTERPRISE=1

Feature	Description	Requires
Billing	Stripe integration for usage-based billing	pip install hieromem[saas]
Dashboard	Tenant management and analytics UI	HIEROMEM_ENTERPRISE=1
OAuth2/OIDC	Enterprise SSO (Auth0, Okta, Google)	OIDC_ENABLED=true
Advanced Multi-Tenancy	Per-tenant quotas and rate limits	HIEROMEM_ENTERPRISE=1

See docs/ARCHITECTURE.md for the full feature classification.

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                    Nginx (TLS/HTTPS)                    │
│                    :80, :443                            │
└────────────────┬────────────────────────────────────────┘
                 │
        ┌────────┴────────┐
        │                 │
┌───────▼────────┐  ┌────▼──────────┐
│  API :8000     │  │  Visualizer   │
│  (FastAPI)     │  │  (React)      │
└───────┬────────┘  └───────────────┘
        │
        ├──────────┬──────────┬──────────┬──────────┐
        │          │          │          │          │
┌───────▼──────┐ ┌─▼──────┐ ┌─▼──────┐ ┌─▼──────┐ ┌─▼──────────┐
│ Neo4j :7687  │ │ Redis  │ │ SQLite │ │ FAISS  │ │ Prometheus │
│ (Graph DB)   │ │ (Cache)│ │ (Meta) │ │(Vector)│ │ (Metrics)  │
└──────────────┘ └────────┘ └────────┘ └────────┘ └─────┬──────┘
                                                          │
                                                    ┌─────▼─────┐
                                                    │  Grafana  │
                                                    └───────────┘

Components

Component	Purpose	Technology
API	REST API for memory operations	FastAPI, Python 3.11
Visualizer	Web UI for exploring memories	React, TypeScript, Vite
Neo4j	Graph database for semantic relationships	Neo4j 5.15
Redis	Distributed rate limiting & caching	Redis 7.2
SQLite	Metadata and episode storage	SQLite (WAL mode)
FAISS	Vector similarity search	Facebook AI Similarity Search
Prometheus	Metrics collection and alerting	Prometheus + Alertmanager
Loki	Centralized log aggregation	Grafana Loki
Grafana	Visualization dashboards	Grafana

🔗 Graph Capabilities

HIEROMEM supports graph-based semantic storage with multiple backend options for development, testing, and production environments.

Graph Backends

Backend	Use Case	Dependencies
in_memory_graph	Development, Testing, CI	None (NetworkX)
neo4j	Production	Neo4j 5.15+
neptune	AWS Production	AWS Neptune, Gremlin

Configuration

In-Memory Graph (Development/Testing)

# configs/default.yaml
stores:
  symbolic: in_memory_graph

memory:
  Nmax: 20
  embedding_dim: 768

Or via environment variable:

export HIEROMEM_MEMORY_BACKEND=in_memory_graph

Neo4j (Production)

# configs/default.yaml
stores:
  symbolic: neo4j

neo4j:
  uri: ${NEO4J_URI}
  user: ${NEO4J_USER}
  password: ${NEO4J_PASSWORD}
  enable_multi_tenancy: true

Set credentials via environment variables:

export NEO4J_URI=bolt://localhost:7687
export NEO4J_USER=neo4j
export NEO4J_PASSWORD=<your-password>

Graph-Enhanced Features

• Multi-hop Reasoning: Traverse relationships to discover connected episodes
• Dual Retrieval: Combines vector similarity with graph structure
• Entity Indexing: Fast lookup of episodes containing specific entities
• Graph Statistics: Monitor node/edge counts via health endpoints

Graph Search API

POST /memory/graph-search
X-API-Key: your-api-key

{
  "episode_id": "abc123",
  "depth": 2,
  "limit": 50,
  "namespace": "default"
}

Response:

{
  "results": [
    {"source": "Alice", "target": "Bob", "relations": ["knows"], "trust": 0.9},
    {"source": "Bob", "target": "Charlie", "relations": ["knows"], "trust": 0.8}
  ]
}

Checking Graph Status

# Via health endpoint
curl http://localhost:8000/health/detailed | jq '.memory.graph_store'

# Expected output when enabled:
{
  "backend": "networkx",
  "type": "InMemoryGraphStore",
  "node_count": 42,
  "edge_count": 78
}

📚 API Documentation

Core Endpoints

Remember an Event

POST /memory/remember
Content-Type: application/json
X-API-Key: your-api-key

{
  "namespace": "default",
  "event_type": "user_action",
  "content": "Event description",
  "metadata": {"key": "value"},
  "scene_graph": {
    "nodes": [{"id": "user1", "type": "User", "properties": {}}],
    "edges": [{"source": "user1", "target": "action1", "relation": "performed"}]
  }
}

Recall Memories

POST /memory/recall
Content-Type: application/json
X-API-Key: your-api-key

{
  "namespace": "default",
  "query": "What did the user do?",
  "top_k": 5,
  "min_similarity": 0.7
}

Get Episode Tree

GET /memory/tree?namespace=default
X-API-Key: your-api-key

Health Check

GET /system/health

Full API Documentation

Interactive API docs available at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

⚙️ Configuration

Environment Variables

Variable	Description	Default
NEO4J_URI	Neo4j connection URI	bolt://neo4j:7687
NEO4J_PASSWORD	Neo4j password	password
REDIS_URL	Redis connection URL	redis://redis:6379/0
SQLITE_PATH	SQLite database path	/data/memory.db
HIEROMEM_API_KEY	Default API key	dev-key
GRAFANA_PASSWORD	Grafana admin password	admin

Resource Limits

Default limits per service (configurable in docker-compose.yml):

• API: 2 CPU, 4GB RAM
• Neo4j: 2 CPU, 2GB RAM
• Redis: 1 CPU, 512MB RAM

🚢 Deployment

Production Deployment Checklist

• Copy .env.example to .env and set production values
• Generate strong passwords for Neo4j and Grafana
• Replace self-signed SSL certificates with Let's Encrypt
• Configure offsite backup sync (S3, GCS, Azure Blob)
• Set up Alertmanager for Prometheus alerts
• Create production API keys with expiration
• Configure Grafana dashboards and data sources
• Adjust resource limits based on workload
• Set up DNS and domain routing
• Configure firewall rules

Backup & Recovery

Automated Backups: Daily at 02:00 UTC, 7-day retention

# Manual backup
docker compose exec backup /scripts/backup.sh

# Restore from backup
docker compose run --rm backup /scripts/restore.sh <TIMESTAMP>

See docs/disaster_recovery.md for full recovery procedures.

Database Migrations

# Create a new migration
cd packages/hieromem_core
alembic revision -m "description"

# Apply migrations
alembic upgrade head

# Rollback
alembic downgrade -1

📊 Monitoring

Prometheus Metrics

Available at http://localhost:9090

• Request rate and latency
• Memory usage and episode counts
• Rate limiting statistics
• Health check status

Grafana Dashboards

Access at http://localhost:3000 (default: admin/admin)

Pre-configured dashboards:

• System Overview
• API Performance
• Resource Usage
• Log Analysis (via Loki)

Alerts

Configured in infra/prometheus/alerts.yml:

• High memory usage (>90%)
• High CPU usage (>80%)
• Service down
• High error rate (>5%)
• Slow response time (p95 >2s)

🛠️ Development

Local Setup

# Install dependencies
pip install -r requirements.txt

# Install packages in editable mode
pip install -e packages/hieromem_core
pip install -e packages/hieromem_api

# Run tests
pytest

# Run API locally
cd packages/hieromem_api
uvicorn hieromem_api.main:app --reload

Running Tests

# All tests
pytest

# Specific test file
pytest tests/test_api_memory.py

# With coverage
pytest --cov=hieromem_core --cov=hieromem_api

Code Quality

# Format code
black packages/

# Lint
flake8 packages/

# Type checking
mypy packages/

🛡️ Compliance

• GDPR Readiness – data processing agreements, erasure, portability, consent.
• CCPA Controls – consumer rights, Do Not Sell handling, deletion pipeline.
• SOC 2 Preparation – security, availability, and confidentiality controls.

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Write tests for new features
• Follow PEP 8 style guide
• Update documentation
• Ensure CI/CD passes

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with FastAPI
• Graph storage powered by Neo4j
• Vector search using FAISS
• Embeddings from Sentence Transformers

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki

---

Built with ❤️ for AI agents that never forget