Hippocortex Architecture Overview
This document describes the high-level architecture of Hippocortex. It covers components, data flow, infrastructure, deployment models, and security boundaries.
High-Level Architecture
+---------------------------------------------------------------+
| Client Applications |
| (AI Agents, Orchestrators, Custom Integrations) |
+---------------------------------------------------------------+
| ^
| HTTPS (REST API) | JSON Responses
v |
+---------------------------------------------------------------+
| API Gateway (Hono) |
| Authentication | Rate Limiting | RBAC | Secret Interception |
+---------------------------------------------------------------+
| | | |
v v v v
+----------+ +----------+ +----------+ +----------+
| Capture | | Synthesize| | Learn | | Vault |
| Routes | | Routes | | Routes | | Routes |
+----------+ +----------+ +----------+ +----------+
| | | |
v | v v
+----------+ | +----------+ +----------+
| Event | | | Job | | Vault |
| Queue | | | Queue | | Crypto |
| (BullMQ) | | | (BullMQ) | | Engine |
+----------+ | +----------+ +----------+
| | | |
v v v v
+---------------------------------------------------------------+
| Processing Layer |
| Event Processor | Retrieval Engine | Memory Compiler |
| Salience Scorer | Ranking Engine | Artifact Generator |
| Secret Detector | Budget Allocator | Adaptive Compiler |
| Policy Engine | Provenance | Predictive Engine |
+---------------------------------------------------------------+
| |
v v
+---------------------------------------------------------------+
| Storage Layer |
| |
| PostgreSQL Redis |
| +---------------------------+ +------------------------+ |
| | events | | Job queues (BullMQ) | |
| | semantic_memories | | Prefetch cache | |
| | compiled_artifacts | | Rate limit counters | |
| | entity_nodes | | Session state | |
| | relation_edges | +------------------------+ |
| | vault_items | |
| | vault_audit_log | |
| | organizations | |
| | org_members | |
| | teams | |
| | agent_identities | |
| | memory_namespaces | |
| | namespace_policies | |
| | audit_log | |
| | memory_access_log | |
| | lifecycle_policies | |
| | memory_lineage | |
| +---------------------------+ |
+---------------------------------------------------------------+
Component Overview
SDK Layer
The SDK layer provides the client interface for interacting with Hippocortex.
| Component | Language | Purpose |
|---|---|---|
@hippocortex/sdk | TypeScript | Official TypeScript/JavaScript SDK |
hippocortex | Python | Official Python SDK |
| Framework Adapters | Both | OpenAI, LangGraph, CrewAI, AutoGen, OpenClaw |
SDKs expose three core operations: capture(), learn(), synthesize(). All communication is over HTTPS with JSON payloads.
API Layer (Hono)
The REST API is built with Hono, a lightweight TypeScript web framework. It handles:
| Responsibility | Implementation |
|---|---|
| Authentication | API key (hx_live_*) and JWT (Clerk) |
| Rate limiting | Per-plan limits (60 to unlimited req/min) |
| RBAC enforcement | Middleware checks permissions per route |
| Request validation | Schema validation for all endpoints |
| Secret interception | Scans payloads for secrets before storage |
| Tenant isolation | All queries scoped to authenticated tenant |
| Audit logging | Records mutations and access events |
Processing Layer
Event Processing
- Events arrive via the capture API
- Queued in BullMQ for async processing
- Scored for salience
- Scanned for secrets
- Stored as episodic memories
Memory Compilation
- Triggered via the learn API or scheduled jobs
- Processes episodic memories into semantic memories
- Extracts patterns and generates knowledge artifacts
- Runs contradiction detection
- Updates confidence scores
Retrieval Engine
- Receives synthesis queries
- Evaluates access policies
- Retrieves candidate memories and artifacts
- Applies 8-signal composite ranking
- Allocates token budget across sections
- Filters by provenance integrity
- Assembles context packs
Adaptive Compiler
- Monitors telemetry from retrieval and outcomes
- Adjusts 19 compilation and ranking parameters
- Maintains safety bounds on all parameters
- Produces audit trail for every adjustment
Predictive Engine
- Detects query sequence patterns
- Identifies artifact co-occurrence clusters
- Pre-assembles context packs for predicted queries
- Manages prefetch cache with TTL
Storage Layer
PostgreSQL
Primary data store for all persistent data. Uses parameterized SQL queries (no ORM). Key table groups:
| Table Group | Tables | Purpose |
|---|---|---|
| Core Memory | events, semantic_memories, compiled_artifacts | Event and knowledge storage |
| Knowledge Graph | entity_nodes, relation_edges | Entity relationship graph |
| Vault | vaults, vault_items, vault_audit_log | Encrypted secrets |
| Enterprise | organizations, org_members, teams, agent_identities | Multi-tenant model |
| Access Control | memory_namespaces, namespace_policies | Scoped access control |
| Audit | audit_log, memory_access_log | Compliance logging |
| Lifecycle | lifecycle_policies, memory_lineage | Data lifecycle management |
| Users | users, api_keys | Authentication |
Redis
Used for transient and performance-critical data:
| Use Case | Description |
|---|---|
| Job queues | BullMQ queues for capture and learn processing |
| Prefetch cache | Pre-warmed context packs from predictive engine |
| Rate limiting | Request counters per tenant/plan |
| Session state | Temporary processing state |
Data Flow
Capture Flow
Client SDK
|
| POST /v1/capture
v
API Gateway
|
| Authenticate + Rate Limit
v
Secret Interceptor
|
| Scan payload for secrets
| Redirect detected secrets to Vault
v
Event Queue (BullMQ)
|
| Async processing
v
Event Processor
|
| Salience scoring
| Deduplication check
| Namespace assignment
v
PostgreSQL (events table)
|
v
Response to client (eventId, status, salienceScore)
Compilation Flow
POST /v1/learn
|
v
Compilation Job Queue (BullMQ)
|
v
Event Retrieval
|
| Fetch unprocessed events
v
Pattern Extraction
|
| Frequency analysis
| Co-occurrence detection
| Sequence extraction
v
Artifact Generation
|
| Task schemas
| Failure playbooks
| Decision policies
| Causal patterns
| Strategy templates
v
Confidence Scoring
|
| Method strength * evidence count * recency
v
Contradiction Detection
|
| Supersede outdated artifacts
v
Adaptive Parameter Update (if enabled)
|
| Adjust compilation thresholds from telemetry
v
PostgreSQL (compiled_artifacts, semantic_memories)
Retrieval Flow
POST /v1/synthesize
|
v
API Gateway (auth + RBAC)
|
v
Policy Engine
|
| Evaluate namespace access policies
| Determine accessible namespaces
v
Predictive Cache Lookup
|
| Check if pre-warmed pack exists
| If hit: return cached pack
| If miss: continue to retrieval
v
Memory Retrieval
|
| Fetch candidate memories from accessible namespaces
v
Composite Ranking (8 signals)
|
| Score and rank all candidates
v
Provenance Filter
|
| Remove items with broken provenance
v
Budget Allocation
|
| Distribute token budget across sections
| Dynamic reallocation of unused budget
v
Context Assembly
|
| Build final context pack
| Include provenance references
v
Response (SynthesizeResult)
Vault Flow
Secret Detection (during capture)
|
| Regex pattern matching
| Confidence scoring
v
High Confidence?
|
+-- Yes --> Vault Auto-Capture
| |
| v
| Generate DEK (AES-256-GCM)
| |
| v
| Encrypt value with DEK
| |
| v
| Encrypt DEK with KEK (envelope)
| |
| v
| Store encrypted blob + wrapped DEK
| |
| v
| Replace value with vault:// reference
|
+-- No (uncertain) --> Queue for human review
|
+-- No (not a secret) --> Pass through to memory
Infrastructure
Production Stack
| Component | Technology | Purpose |
|---|---|---|
| API Server | Hono (TypeScript) | REST API |
| Job Queue | BullMQ (Redis-backed) | Async processing |
| Primary DB | PostgreSQL 16 | Persistent storage |
| Connection Pool | PGBouncer | Database connection pooling |
| Cache/Queue | Redis 7 | Queues, cache, rate limiting |
| Reverse Proxy | Traefik | SSL termination, routing |
| SSL | Let's Encrypt | Automated TLS certificates |
| Monitoring | Prometheus + Grafana | Metrics and dashboards |
| Container | Docker Compose | Orchestration |
Production Container Layout (13 containers)
traefik -- reverse proxy, SSL termination
cloud-api -- main API server
cloud-api-worker -- BullMQ job processor
postgres -- primary database
pgbouncer -- connection pooler
redis -- queue backend + cache
prometheus -- metrics collection
grafana -- dashboards
loki -- log aggregation (optional)
dashboard -- Next.js dashboard app
docs -- documentation site
backup-agent -- automated PostgreSQL backups
certbot -- SSL certificate renewal
Deployment Models
Cloud (Hosted)
- Managed deployment at
api.hippocortex.dev - Dashboard at
dashboard.hippocortex.dev - No infrastructure management required
- Automatic scaling and updates
- SLA available on Enterprise plan
Self-Hosted
- Docker Compose deployment on any Linux server
- Tested on Hetzner dedicated servers
- Full control over data residency
- Requires PostgreSQL and Redis
- Manual scaling and updates
Security Boundaries
Authentication Boundary
Internet
|
| TLS 1.3
v
Traefik (SSL termination)
|
| Plain HTTP (internal network only)
v
API Gateway
|
| API Key or JWT validation
| Rate limiting
v
Authenticated request context
Tenant Isolation
- Every database query is scoped to the authenticated tenant ID
- No cross-tenant data access is possible
- Tenant ID is extracted from the authentication token, never from request parameters
- Enterprise organizations add an additional isolation layer
Data Classification
| Data Type | Storage | Encryption | Access Control |
|---|---|---|---|
| Events | PostgreSQL | At rest (disk encryption) | Tenant-scoped |
| Memories | PostgreSQL | At rest | Tenant + namespace |
| Artifacts | PostgreSQL | At rest | Tenant + namespace |
| Vault Secrets | PostgreSQL | AES-256-GCM (app layer) | Permission-gated |
| API Keys | PostgreSQL | SHA-256 hashed | Owner only |
| Audit Logs | PostgreSQL | At rest | Admin + audit roles |
Network Security
- All external traffic encrypted with TLS 1.3
- Internal services communicate over private Docker network
- PostgreSQL and Redis not exposed to public internet
- PGBouncer limits connection count and enforces authentication
- Traefik handles rate limiting at the edge