Types

Memory


{
  "id": "uuid",
  "content": "string",
  "type": "string",
  "category": "string | null",
  "importance": 0.5,
  "source": "direct | derived",
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-01T00:00:00Z",
  "metadata": {}
}

DerivedMemory

Extends Memory with:


{
  "derived_from": ["memory-uuid-1", "memory-uuid-2"],
  "derivation_reason": "string"
}

Entity


{
  "id": "uuid",
  "content": "string",
  "type": "person | organization | location | preference | skill | other",
  "category": "string | null",
  "importance": 0.8,
  "community_id": "string | null",
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-01T00:00:00Z",
  "metadata": {}
}

EntityUpdate

Used when updating an entity. All fields optional, at least one required:


{
  "content": "string",
  "type": "string",
  "category": "string",
  "importance": 0.9
}

Relationship


{
  "id": "uuid",
  "source_id": "uuid",
  "target_id": "uuid",
  "relationship_type": "string",
  "weight": 1.0,
  "created_at": "2025-01-01T00:00:00Z",
  "metadata": {}
}

EntityRelationships


{
  "entity_id": "uuid",
  "incoming": [Relationship],
  "outgoing": [Relationship]
}

IngestResponse

Returned by ingestion and remember():


{
  "entities_created": 3,
  "relationships_created": 2,
  "episodes_created": 1,
  "processing_time_ms": 245,
  "status": "success"
}

QueryResult

A single result from a knowledge query:


{
  "id": "uuid",
  "content": "string",
  "type": "string",
  "category": "string | null",
  "importance": 0.5,
  "relevance_score": 0.95,
  "emotional_valence": 0.0,
  "emotional_intensity": 0.0,
  "community_id": "string | null",
  "metadata": {}
}

QueryResponse

Returned by recall() and knowledge.query():


{
  "results": [QueryResult],
  "context": "Combined context string for LLM prompts",
  "query_complexity": "simple | medium | complex",
  "cache_hit": false,
  "result_count": 5,
  "reasoning_chains": [ReasoningChain],
  "citations": [Citation],
  "retrieval_path": "cache | graph | vector | hybrid | unified",
  "timing": TimingBreakdown
}

TimingBreakdown

Per-stage latency information:


{
  "embedding_ms": 12,
  "cache_check_ms": 3,
  "complexity_routing_ms": 1,
  "hybrid_search_ms": 45,
  "reranking_ms": 20,
  "community_enrichment_ms": 0,
  "graph_reasoning_ms": 0,
  "context_assembly_ms": 5,
  "total_ms": 86
}

MemoryStats


{
  "total_memories": 150,
  "direct_memories": 120,
  "derived_memories": 30,
  "relationships": 85
}

Episode


{
  "id": "uuid",
  "start_time": "2025-01-01T00:00:00Z",
  "end_time": "2025-01-01T01:00:00Z",
  "entity_count": 5,
  "entity_ids": ["uuid-1", "uuid-2"],
  "summary": "string | null",
  "created_at": "2025-01-01T00:00:00Z"
}

ConsolidationReport


{
  "status": "completed",
  "dry_run": false,
  "entities_evaluated": 100,
  "entities_soft_deleted": 15,
  "entities_hard_deleted": 3,
  "memory_reduction_pct": 12.5
}

GraphVisualization


{
  "nodes": [GraphNode],
  "edges": [GraphEdge],
  "communities": [GraphCommunity],
  "stats": KnowledgeStats
}

GraphNode


{
  "id": "uuid",
  "label": "string",
  "type": "string",
  "importance": 0.5,
  "community_id": "string | null",
  "metadata": {}
}

GraphEdge


{
  "source": "uuid",
  "target": "uuid",
  "relationship": "string",
  "weight": 1.0
}

GraphCommunity


{
  "id": "uuid",
  "label": "string",
  "summary": "string | null",
  "entity_count": 8,
  "entity_ids": ["uuid-1", "uuid-2"]
}

DuplicatesResponse


{
  "groups": [DuplicateGroup],
  "total_groups": 3
}

DuplicateGroup


{
  "entity_ids": ["uuid-1", "uuid-2"],
  "similarity_score": 0.95,
  "suggested_merge_target": "uuid-1"
}

MergeResponse


{
  "merged_into": "uuid",
  "merged_count": 1,
  "relationships_redirected": 4,
  "status": "success"
}

Conversation


{
  "id": "uuid",
  "owner_id": "string",
  "external_id": "string | null",
  "title": "string | null",
  "metadata": {},
  "message_count": 42,
  "started_at": "2025-01-01T00:00:00Z",
  "last_message_at": "2025-01-01T00:30:00Z",
  "created_at": "2025-01-01T00:00:00Z"
}

Message


{
  "id": "uuid",
  "conversation_id": "uuid",
  "role": "user | assistant | system",
  "content": "string",
  "metadata": {},
  "created_at": "2025-01-01T00:00:00Z",
  "extracted_entity_ids": ["uuid-1"]
}

ConversationRecallResponse

Returned by conv.recall():


{
  "conversation_context": [ConversationContext],
  "results": [QueryResult],
  "context": "Combined context string for LLM prompts",
  "timing": TimingBreakdown
}

ConversationContext


{
  "id": "uuid",
  "conversation_id": "uuid",
  "role": "user | assistant | system",
  "content": "string",
  "metadata": {},
  "created_at": "2025-01-01T00:00:00Z",
  "extracted_entity_ids": ["uuid-1"]
}

Document

Used when ingesting content:


{
  "content": "string",
  "id": "string | null",
  "timestamp": "2025-01-01T00:00:00Z | null",
  "metadata": {}
}

HealthStatus


{
  "status": "ok",
  "version": "1.0.0",
  "environment": "production"
}