Home/Documentation

Ontology

The Ontology resource manages domain-specific schemas. Define concepts, relationships, and hierarchies to structure how facts are extracted and organized in your knowledge graph.

POSTclient.ontology.load()
HTTP:POST /v1/ontology

Load or update an ontology domain with concepts and relationships.

Parameters

domainstrRequired

Unique identifier for the ontology domain (e.g., "software_engineering").

namestrRequired

Human-readable name for the ontology.

conceptslist[OntologyConceptRequest | dict]Required

List of concepts to define in the ontology.

descriptionstrOptional

Description of the ontology domain.

relationshipslist[OntologyRelationshipRequest | dict]Optional

Relationships between concepts.

Concept Structure

Concept Fields

concept_idstrRequired

Unique identifier for the concept.

namestrRequired

Human-readable name.

descriptionstrOptional

Description of the concept.

aliaseslist[str]Optional

Alternative names for the concept.

Relationship Structure

Relationship Fields

source_concept_idstrRequired

ID of the source concept.

target_concept_idstrRequired

ID of the target concept.

relationship_typestrRequired

Type of relationship (e.g., "built_with", "is_a", "has_a").

Example

load_ontology.py
PYTHON
from memoair import MemoAir
 
client = MemoAir()
 
# Define a software engineering ontology
client.ontology.load(
    domain="software_engineering",
    name="Software Engineering Concepts",
    description="Common concepts in software development",
    concepts=[
        {
            "concept_id": "python",
            "name": "Python",
            "description": "A high-level programming language",
            "aliases": ["py", "python3"],
        },
        {
            "concept_id": "fastapi",
            "name": "FastAPI",
            "description": "Modern Python web framework",
        },
        {
            "concept_id": "pytorch",
            "name": "PyTorch",
            "description": "Machine learning framework",
        },
        {
            "concept_id": "web_framework",
            "name": "Web Framework",
            "description": "Framework for building web applications",
        },
        {
            "concept_id": "ml_framework",
            "name": "ML Framework",
            "description": "Framework for machine learning",
        },
    ],
    relationships=[
        {
            "source_concept_id": "fastapi",
            "target_concept_id": "python",
            "relationship_type": "built_with",
        },
        {
            "source_concept_id": "pytorch",
            "target_concept_id": "python",
            "relationship_type": "built_with",
        },
        {
            "source_concept_id": "fastapi",
            "target_concept_id": "web_framework",
            "relationship_type": "is_a",
        },
        {
            "source_concept_id": "pytorch",
            "target_concept_id": "ml_framework",
            "relationship_type": "is_a",
        },
    ],
)
GETclient.ontology.get()
HTTP:GET /v1/ontology/{domain}

Retrieve a loaded ontology by domain.

PYTHON
# Get ontology details
ontology = client.ontology.get(domain="software_engineering")
 
print(f"Name: {ontology.name}")
print(f"Concepts: {len(ontology.concepts)}")
print(f"Relationships: {len(ontology.relationships)}")
GETclient.ontology.list()
HTTP:GET /v1/ontology

List all loaded ontology domains.

PYTHON
# List all ontologies
ontologies = client.ontology.list()
 
for ont in ontologies:
    print(f"- {ont.domain}: {ont.name} ({ont.concept_count} concepts)")
GETclient.ontology.stats()
HTTP:GET /v1/ontology/{domain}/stats

Get statistics for a specific ontology.

PYTHON
stats = client.ontology.stats(domain="software_engineering")
 
print(f"Domain: {stats.domain}")
print(f"Concepts: {stats.concept_count}")
print(f"Relationships: {stats.relationship_count}")
DELETEclient.ontology.delete()
HTTP:DELETE /v1/ontology/{domain}

Delete an ontology domain and all its concepts.

PYTHON
# Delete an ontology
client.ontology.delete(domain="software_engineering")

Using Ontologies with Memory

Once an ontology is loaded, you can map extracted facts to ontology concepts during memory ingestion:

ontology_mapping.py
PYTHON
from memoair import MemoAir, Message
 
client = MemoAir()
 
# Add memory with ontology mapping
client.memories.add(
    group_id="user:john",
    messages=[
        Message(
            content="I've been learning FastAPI for building APIs",
            role_type="user"
        ),
    ],
    map_to_ontology=True,
    ontology_domain="software_engineering",
    ontology_confidence_threshold=0.7,
)
 
# The extracted fact "John uses FastAPI" will be linked to:
# - The "fastapi" concept in the ontology
# - Which is related to "python" and "web_framework"

Ontology in Tripartite Search

When you enable search_ontology=True in tripartite search, MemoAir includes ontology concepts in the results:

PYTHON
results = client.search.tripartite(
    query="What Python frameworks does John know?",
    user_id="user:john",
    search_ontology=True,  # Include ontology in search
)
 
# Results might include:
# [user] John uses FastAPI
# [ontology] FastAPI is a web framework built with Python
# [ontology] Python is a high-level programming language

Tip: Ontologies help your AI understand domain-specific terminology and relationships, improving search relevance and enabling more accurate fact extraction.