Hippocortex/Docs
GitHubDashboard

Core Concepts

This page explains the mental model behind Hippocortex. Understanding these concepts makes the SDK, API, and enterprise features much easier to use.

Events, Artifacts, and Context Packs

Hippocortex processes information in three stages, mirroring how human memory works.

Events are raw observations. Every time your agent does something significant (sends a message, calls a tool, receives an error), you record it as an event. Events are structured, timestamped, and immutable. They are the raw material of memory.

Artifacts are compiled knowledge. The Memory Compiler analyzes patterns across events and produces structured knowledge objects: step-by-step procedures, failure playbooks, causal patterns, and decision policies. Artifacts are what your agent has "learned."

Context Packs are retrieved summaries. When your agent needs to make a decision, the Synthesize engine searches artifacts and recent events, ranks them by relevance, and compresses them into a token-budget-aware context pack that gets injected into the prompt.

Events (raw)  -->  Compiler  -->  Artifacts (knowledge)
                                        |
Query  -------------------------------->|
                                        v
                                  Context Pack (injected into prompt)

The Three Operations

Capture

Capture records an interaction as an event. You call it after your agent does something worth remembering.

Supported event types include: message, tool_call, tool_result, outcome, observation, file_change, and test_run. Each event has a session ID that groups related events together and a payload with the event-specific data.

Events are scored for salience automatically. High-salience events (failures, key decisions, novel situations) receive more weight during compilation.

Learn

Learn triggers the Memory Compiler. It analyzes events and extracts patterns into four artifact types:

Artifact TypeWhat It Captures
Task SchemaStep-by-step procedures from successful task completions
Failure PlaybookFailure modes with symptoms, root causes, and recovery steps
Causal PatternCause-and-effect relationships observed across events
Decision PolicyConditional rules extracted from decision patterns

The compiler is deterministic and uses zero LLM calls. Every artifact traces back to its source events, creating a full provenance chain.

Synthesize

Synthesize retrieves relevant context for a query. It searches across all memory layers (recent events, compiled artifacts, entity knowledge) and ranks results using an 8-signal scoring system that considers semantic similarity, recency, frequency, provenance quality, and more.

The output is a context pack divided into sections (procedures, failures, decisions, facts, causal patterns) that fits within your specified token budget.

Sessions

A session groups related events together. Think of it like a conversation thread or a task execution. All events within a session share a sessionId.

Sessions help the compiler understand which events are related. A deployment session, for example, might include tool calls, test results, and a final outcome. The compiler can then extract a deployment procedure from that sequence.

Namespaces

Namespaces partition memory into isolated collections. In enterprise deployments, different teams or agent classes can have their own namespaces with independent access controls.

For example, a "customer-support" namespace might be readable by support agents but not by research agents. A "shared-knowledge" namespace might be readable by everyone but writable only by operators.

The HMX Protocol

HMX (Hippocortex Memory Exchange) is the structured format for events and artifacts. It defines event types, artifact schemas, fingerprinting for deduplication, context windows for retrieval, and versioning for backward compatibility.

You do not need to interact with HMX directly. The SDKs handle serialization and deserialization. But understanding that there is a formal protocol behind the data model helps when debugging or building custom integrations.

Next Steps