Semantic Memory

Purpose

Semantic Memory stores general world knowledge and facts that are not tied to a specific timestamp or session. It represents the "textbook knowledge" of the agent.

Key Features

• Confidence Scoring: Every fact has a confidence score (0.0-1.0). Conflicting facts can coexist, but retrieval favors higher confidence.
• Dynamic Linking: Facts automatically link to related concepts via :RELATED_TO edges.
• Extraction: Uses LLMs to parse unstructured text into atomic Subject-Predicate-Object triples.

Functional Deep Dive

Fact Extraction

The system uses LLMs to parse incoming unstructured text (from documents or high-utility episodes) into atomic facts. For example, "Python is a programming language" becomes (Python)-[:IS_A]->(Programming Language).

Recursive Retrieval

Retrieval isn't just keyword matching. When retrieving a concept (e.g., "Python"), the system also fetches connected nodes (e.g., "Programming Language", "Snake") depending on the context relationships [:RELATED_TO].

Ingestion Workflow

Codebase Interaction

• Invocation: UnifiedIngestionService.ingest_content or during MainOrchestrator retrieval hooks.
• Key API: /api/memory/v1/facts

API Reference

Semantic Memory provides RESTful endpoints for managing knowledge facts.

SDK Reference

The Functor SDK provides a Python interface for semantic memory operations.

Adding Facts

from functor_sdk import FunctorClient

client = FunctorClient(api_key="your-api-key")

# Add a semantic fact
fact = client.memory.semantic.add_fact(
    content="Python is a high-level programming language",
    kg_name="tech_knowledge",
    source="documentation",
    metadata={"category": "programming"},
    ttl_days=365
)

print(f"Created fact: {fact['id']}")

Searching Facts

# Semantic search
results = client.memory.semantic.search(
    query="programming languages",
    kg_name="tech_knowledge",
    limit=10
)

for fact in results['facts']:
    print(f"{fact['content']} (confidence: {fact['confidence']})")

Managing Facts

# List facts
facts = client.memory.semantic.list(
    kg_name="tech_knowledge",
    limit=50
)

# Get facts by knowledge graph
kg_facts = client.memory.semantic.get_by_kg(
    kg_name="tech_knowledge",
    limit=100
)

# Update fact
updated = client.memory.semantic.update(
    fact_id="fact_123",
    content="Updated content",
    confidence=0.95
)

# Delete fact
client.memory.semantic.delete(fact_id="fact_123")