Skip to main content

Context Graph API

The Context Graph extends ZeroMemory with a knowledge graph layer. Entities, edges, and multi-hop traversal power contextual reasoning beyond vector similarity.

Base URL: https://api.ainative.studio/api/v1/public/memory/v2/graph

All endpoints require Authorization: Bearer <token>.

Core Graph​

POST /entity​

Create or update an entity. If the entity exists, aliases are merged and memory_count is incremented.

curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/graph/entity \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "canonical_name": "Alice Johnson",
    "entity_type": "person",
    "aliases": ["alice", "AJ"],
    "properties": {"title": "CTO", "company": "AINative"}
  }'

Response:

{
  "id": "c002751b-...",
  "canonical_name": "Alice Johnson",
  "entity_type": "person",
  "aliases": ["alice", "AJ"],
  "properties": {"title": "CTO", "company": "AINative"},
  "memory_count": 1,
  "status": "created"
}

POST /edge​

Create a directed edge between two entities. If an active edge with the same source + predicate exists but different target, the old edge is auto-superseded (contradiction detection).

curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/graph/edge \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_name": "Alice Johnson",
    "target_name": "AINative Studio",
    "predicate": "works_at",
    "confidence": 0.95
  }'

POST /traverse​

Multi-hop graph traversal via recursive CTE. Returns all reachable nodes and edges up to max_hops depth.

curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/graph/traverse \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "Alice Johnson",
    "max_hops": 3,
    "predicates": ["works_at", "knows"],
    "min_confidence": 0.5
  }'

Response:

{
  "nodes": [
    {"id": "...", "label": "Alice Johnson", "type": "person", "properties": {}},
    {"id": "...", "label": "AINative Studio", "type": "org", "properties": {}}
  ],
  "edges": [
    {"id": "...", "source": "...", "target": "...", "predicate": "works_at", "confidence": 0.95, "depth": 1}
  ],
  "paths": []
}

Optional as_of parameter for historical graph state (edge versioning).

GET /neighbors/{entity_name}​

Direct connections for an entity (1-hop).

GET /stats​

Graph analytics: node count, edge count, density, top entities.

GET /entities​

List entities with optional type filter and pagination.

GET /entities?entity_type=person&limit=50&offset=0

POST /entity/merge​

Merge duplicate entities. Re-points all edges and consolidates aliases.

curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/graph/entity/merge \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "canonical": "Alice Johnson",
    "merge": ["alice", "Alice", "AJ"]
  }'

GraphRAG​

POST /graphrag​

Hybrid search blending vector similarity with graph proximity.

curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/graph/graphrag \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "pricing strategy",
    "limit": 10,
    "graph_weight": 0.3,
    "max_hops": 2
  }'
ParameterDefaultDescription
graph_weight0.30 = pure vector, 1 = pure graph, 0.3 = 70% vector + 30% graph
max_hops2How far to traverse from matched entities

Response: Same shape as /recall with added vector_score, graph_boost, and blended score fields.

Ontology​

GET /ontology​

Get the project's ontology definition.

GET /ontology?project_id=<uuid>

POST /ontology​

Define or update a project ontology. Version auto-increments on update.

curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/graph/ontology \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "<uuid>",
    "entity_types": ["customer", "order", "product"],
    "predicates": {
      "customer": {"places": "order", "prefers": "product"},
      "order": {"contains": "product"}
    }
  }'

POST /ontology/infer​

Auto-infer an ontology from existing entity/edge patterns.

POST /ontology/infer?min_entity_count=5&min_predicate_count=3

POST /ontology/apply​

Apply an inferred ontology and retroactively classify entities.

Edge Versioning​

GET /contradictions​

List edges that were superseded by newer conflicting edges.

POST /contradictions/{edge_id}/resolve​

Resolve a contradiction. Actions: accept_new, keep_both, reject_new.

Templates​

GET /templates​

List 5 pre-built semantic data product templates.

[
  {"name": "customer-support", "description": "Ontology for customer support workflows", "entity_types": ["customer", "ticket", "product", "agent", "knowledge_article"]},
  {"name": "research", "description": "Ontology for academic/research workflows", ...},
  {"name": "code-review", "description": "Ontology for software development", ...},
  {"name": "sales", "description": "Ontology for sales and CRM", ...},
  {"name": "knowledge-base", "description": "Ontology for documentation and Q&A", ...}
]

POST /templates/{name}/apply​

Apply a template to a project: creates ontology + seeds entities.

POST /templates/customer-support/apply?project_id=<uuid>