Hippocortex/Docs
GitHubDashboard

Architecture Overview

This document describes the high-level architecture of Hippocortex: its components, data flow, infrastructure, and security boundaries. It is intended for developers who want to understand what happens behind the API.

System Overview

Hippocortex is a cloud-hosted service with four main layers: the API gateway, the processing layer, the storage layer, and the client SDKs. All communication between clients and the API happens over HTTPS. Internal services communicate within a private Docker network.

+---------------------------------------------------------------+
|                     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           v
+---------------------------------------------------------------+
|                     Processing Layer                           |
|  Event Processor | Retrieval Engine | Memory Compiler          |
|  Salience Scorer | Ranking Engine   | Artifact Generator       |
|  Secret Detector | Budget Allocator | Adaptive Compiler        |
+---------------------------------------------------------------+
        |                                           |
        v                                           v
+---------------------------------------------------------------+
|                     Storage Layer                              |
|  PostgreSQL (events, memories, artifacts, orgs, vault)         |
|  Redis (job queues, cache, rate limits, session state)         |
+---------------------------------------------------------------+

API Gateway

The API gateway is built on Hono and runs as a Node.js service. Every request passes through a middleware chain before reaching a route handler:

  1. Authentication. API keys (hx_live_*, hx_test_*) for programmatic access. JWT tokens (via Clerk) for dashboard and user flows.
  2. Rate limiting. Per-key rate limits tracked in Redis. Configurable per plan tier.
  3. RBAC. Enterprise routes check organization membership and role hierarchy before granting access.
  4. Secret interception. The gateway scans incoming payloads for credentials and API keys. Detected secrets are automatically redacted and stored in the encrypted Vault.

Processing Layer

Event Processor

When an event arrives via the Capture endpoint, it is validated, assigned a salience score, and written to PostgreSQL. Events are also enqueued in BullMQ for asynchronous processing (entity extraction, deduplication, relation mapping).

Memory Compiler

The compiler runs when Learn is called. It operates in two modes:

  • Incremental processes only events since the last compilation. This is fast and is the default.
  • Full reprocesses all events from scratch. Use this periodically for consistency.

The compiler uses frequency analysis, co-occurrence detection, and sequence extraction to identify patterns. It produces four artifact types: task schemas, failure playbooks, causal patterns, and decision policies. No LLM calls are made during compilation, making outputs deterministic and auditable.

Retrieval Engine

When Synthesize is called, the retrieval engine searches across all memory layers. It ranks results using 8 signals: semantic similarity, temporal recency, frequency, salience, provenance quality, entity overlap, session relevance, and confidence. Results are then packed into sections (procedures, failures, decisions, facts) within the caller's token budget.

Storage Layer

PostgreSQL stores all persistent data: events, semantic memories, compiled artifacts, entity graphs, vault items, organizations, teams, audit logs, and more. Tenant isolation is enforced at the query layer with row-level filtering.

Redis handles ephemeral workloads: BullMQ job queues for async processing, prefetch caches for hot artifacts, rate limit counters, and session state.

Security Boundaries

All external traffic enters through HTTPS. Internal services communicate on a private Docker bridge network with no public exposure. Database credentials, the vault master key, and other secrets are stored as environment variables, never in code or configuration files.

The Vault uses AES-256-GCM envelope encryption. Each secret has its own Data Encryption Key (DEK), which is wrapped with a Key Encryption Key (KEK). Raw secret values are never stored in plaintext.

For a detailed security model including threat analysis and compliance direction, see Enterprise Security.

Deployment Model

Hippocortex runs as a set of Docker containers behind Traefik (reverse proxy with automatic TLS). The current deployment target is Hetzner Cloud, with PostgreSQL and Redis running as managed or containerized services.

Internet -> Traefik (TLS) -> API Container -> PostgreSQL
                          -> Worker Container -> Redis (BullMQ)
                          -> Dashboard Container
                          -> Docs Container (Docsify)

Next Steps