Memory model

MemHQ stores memory as a hybrid graph: a structured knowledge graph of entities and edges, layered on top of an episodic log of raw inputs. Everything you can read or write through the API flows through three primary objects.

Projects

A project is the top-level isolation boundary. Each project has its own API key, its own user and group namespace, and its own usage and billing counters. You can think of a project as a tenant.

Users and groups

Inside a project, memory is stored in two complementary kinds of graphs:

• Per-user graphs — keyed by the user_id you pass on ingestion. This is the default home for anything personal to a single end-user: their preferences, history, ongoing threads. Two different user_ids cannot read each other's memory.
• Group graphs — keyed by group_id and explicitly shared between a set of users. The right place for team workspaces, customer accounts, product knowledge bases — any context where multiple people read from and contribute to the same memory.

Most queries (search, ask) accept either or both — you can ask for "facts about this user, plus the shared customer-account graph they're a member of" in one call. RBAC is enforced at the storage layer; see RBAC.

Episodes and memories

When you call /v1/memhq/add, the payload becomes an episode: an immutable, timestamped record of the raw input you sent (messages, documents, events). Episodes are the source of truth — we never overwrite them.

The ingestion pipeline then extracts memories from the episode: distilled, queryable claims like

Prefers dark roast coffee, no sugar.

Each memory is linked back to the episode(s) it was extracted from, so every answer can cite a source. Memories — not episodes — are what search and ask operate over.

Entities and relations

Memories are normalized into an underlying graph of entities (people, companies, products, places, concepts) and typed relations between them. The graph is what makes multi-hop questions possible: "who at Acme's data team is most likely to know about the pricing model?" can walk user → team → company → topic across episodes that were ingested weeks apart.

You can extend the entity and relation vocabulary with a custom ontology per project; see API → Memory for the ontology endpoints.

Putting it together

A typical agent loop looks like:

1. On each user turn, call /v1/memhq/add with the message and a user_id. Returns immediately with an episode_id.
2. Before generating the next assistant turn, call /v1/memhq/search (or /v1/memhq/ask) with the same user_id and the question or context the agent needs. The pipeline has by then surfaced the latest memories.
3. Inject the returned memories into your prompt.

The ingestion side is asynchronous and durable; the read side is synchronous and fast. See Ingestion pipeline for what runs between steps 1 and 2.