Memory Lineage

Memory lineage tracks the provenance of every piece of data in Hippocortex -- where it came from, who created it, and how it was transformed.

How It Works

Every time data enters or is processed by Hippocortex, a lineage record is created:

1. Event capture -- when POST /v1/capture stores a new event, a lineage record tracks the source actor and event type
2. Compilation -- when POST /v1/learn triggers compilation, lineage records link the compiled artifacts back to their source events
3. Derivation -- compiled artifacts reference their parent memories via parent_memory_ids

Lineage Record Fields

Field	Description
id	Unique lineage record ID
memory_id	The memory/artifact this record describes
memory_type	Type: event, compilation, semantic_memory, artifact
source_actor_type	Who created it: user, api_key, agent, system
source_actor_id	ID of the actor
source_event_ids	Original events this was derived from
parent_memory_ids	Parent memories in the derivation chain
compiler_job_id	BullMQ job ID (for compilations)
compilation_version	Version number of the compilation
metadata	Additional context
created_at	When the lineage record was created

Querying Lineage

Get lineage for a specific memory

curl https://api.hippocortex.dev/v1/organizations/org_abc123/lineage/mem_789 \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "X-Organization-ID: org_abc123"

Returns all lineage records for that memory ID.

Get the full lineage graph

curl https://api.hippocortex.dev/v1/organizations/org_abc123/lineage/graph/mem_789 \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "X-Organization-ID: org_abc123"

Returns a graph with nodes and edges, built by BFS traversal of parent relationships:

{
  "ok": true,
  "data": {
    "rootMemoryId": "mem_789",
    "nodes": [
      { "id": "mem_789", "isRoot": true },
      { "id": "evt_001", "isRoot": false },
      { "id": "evt_002", "isRoot": false }
    ],
    "edges": [
      { "from": "evt_001", "to": "mem_789", "type": "derived_from" },
      { "from": "evt_002", "to": "mem_789", "type": "derived_from" }
    ],
    "lineageRecords": [...]
  }
}

Lineage Graph

The graph structure shows the full derivation chain:

Event A ──┐
          ├──> Compiled Artifact X ──> Semantic Memory Y
Event B ──┘

You can traverse the graph in either direction:

• Forward: from events to compiled outputs (what was this event used for?)
• Backward: from a memory to its source events (where did this come from?)

Use Cases

• Compliance: prove where specific data originated
• Debugging: trace a bad memory back to the events that produced it
• Impact analysis: understand which artifacts would be affected if source events are deleted
• Audit: verify that compilation processes are producing expected outputs