Memory API

Semantic memory, knowledge graphs, and key-value storage

Overview

OpenFang provides a unified memory substrate with three layers:

1. Key-Value Store - Structured data storage per agent
2. Semantic Memory - Vector-based recall with embeddings
3. Knowledge Graph - Entity-relation graph for structured knowledge

Key-Value Store

Simple key-value storage scoped to individual agents.

Get All Keys

GET /api/memory/agents/{id}/kv

curl http://127.0.0.1:4200/api/memory/agents/550e8400-e29b-41d4-a716-446655440000/kv

200 OK

{
  "user_preferences": {"theme": "dark", "language": "en"},
  "last_checkpoint": "2025-03-06T12:00:00Z",
  "task_count": 42
}

Get Value by Key

GET /api/memory/agents/{id}/kv/{key}

curl http://127.0.0.1:4200/api/memory/agents/550e8400-e29b-41d4-a716-446655440000/kv/user_preferences

200 OK

{
  "theme": "dark",
  "language": "en"
}

Set Value

PUT /api/memory/agents/{id}/kv/{key}

curl -X PUT http://127.0.0.1:4200/api/memory/agents/550e8400-e29b-41d4-a716-446655440000/kv/user_preferences \
  -H "Content-Type: application/json" \
  -d '{"theme": "dark", "language": "en"}'

200 OK

{
  "status": "ok"
}

Delete Key

DELETE /api/memory/agents/{id}/kv/{key}

curl -X DELETE http://127.0.0.1:4200/api/memory/agents/550e8400-e29b-41d4-a716-446655440000/kv/user_preferences

200 OK

{
  "status": "deleted"
}

Semantic Memory

Vector-based memory storage with automatic embedding and semantic recall.

Memory Fragment Structure

id · string

Unique memory ID (UUID)

agent_id · string

Owner agent ID

content · string

Textual content of the memory

embedding · array

Vector embedding (generated automatically)

metadata · object

Arbitrary key-value metadata

source · enum

Memory source type:

• conversation
• document
• observation
• inference
• user_provided
• system

confidence · number

Confidence score (0.0 - 1.0)

scope · string

Memory scope/collection (e.g., “episodic”, “semantic”)

created_at · string

ISO 8601 timestamp

accessed_at · string

Last access timestamp

access_count · integer

Number of times accessed

Store Memory

Memories are stored via the kernel’s memory trait implementation. To add a memory programmatically:

let memory_id = kernel.memory.remember(
    agent_id,
    "The user prefers dark mode",
    MemorySource::UserProvided,
    "preferences",
    metadata,
).await?;

Recall Memories

Perform semantic search over stored memories:

let memories = kernel.memory.recall(
    "What are the user's preferences?",
    5, // limit
    Some(MemoryFilter::agent(agent_id)),
).await?;

Memory Filters

Filter memories by various criteria:

agent_id · string

Filter by agent

source · enum

Filter by source type

scope · string

Filter by scope/collection

min_confidence · number

Minimum confidence threshold

after · string

Only memories created after this timestamp

before · string

Only memories created before this timestamp

metadata · object

Metadata key-value filters

Knowledge Graph

Structured entity-relation graph for representing complex knowledge.

Entity Types

• person - A person
• organization - An organization
• project - A project
• concept - A concept or idea
• event - An event
• location - A location
• document - A document
• tool - A tool
• custom(string) - Custom type

Relation Types

• works_at - Entity works at organization
• knows_about - Entity knows about concept
• related_to - Entities are related
• depends_on - Entity depends on another
• owned_by - Entity is owned by another
• created_by - Entity was created by another
• located_in - Entity is located in another
• part_of - Entity is part of another
• uses - Entity uses another
• produces - Entity produces another
• custom(string) - Custom relation

Add Entity

let entity = Entity {
    id: "john_doe".to_string(),
    entity_type: EntityType::Person,
    name: "John Doe".to_string(),
    properties: HashMap::from([
        ("email".to_string(), json!("[e-mail]")),
        ("role".to_string(), json!("developer")),
    ]),
    created_at: Utc::now(),
    updated_at: Utc::now(),
};

kernel.memory.add_entity(entity).await?;

Add Relation

let relation = Relation {
    source: "john_doe".to_string(),
    relation: RelationType::WorksAt,
    target: "acme_corp".to_string(),
    properties: HashMap::new(),
    confidence: 0.95,
    created_at: Utc::now(),
};

kernel.memory.add_relation(relation).await?;

Query Graph

let pattern = GraphPattern {
    source: Some("john_doe".to_string()),
    relation: Some(RelationType::WorksAt),
    target: None,
    max_depth: 2,
};

let matches = kernel.memory.query_graph(pattern).await?;

vec![
    GraphMatch {
        source: Entity { id: "john_doe", ... },
        relation: Relation { relation: WorksAt, ... },
        target: Entity { id: "acme_corp", ... },
    }
]

Memory Consolidation

Optimize and clean up memory storage:

let report = kernel.memory.consolidate().await?;

memories_merged · integer

Number of duplicate memories merged

memories_decayed · integer

Number of memories whose confidence decayed

duration_ms · integer

Consolidation duration in milliseconds

Export & Import

Export all memory data for backup or migration:

let data = kernel.memory.export(ExportFormat::Json).await?;
std::fs::write("memory_backup.json", data)?;

Import from backup:

let data = std::fs::read("memory_backup.json")?;
let report = kernel.memory.import(&data, ExportFormat::Json).await?;

entities_imported · integer

Number of entities imported

relations_imported · integer

Number of relations imported

memories_imported · integer

Number of memory fragments imported

errors · array

Import errors encountered

Memory Scopes

Organize memories into scopes for different use cases:

• episodic - Conversation-specific memories
• semantic - General knowledge and facts
• procedural - How-to knowledge and procedures
• preferences - User preferences and settings
• observations - Tool outputs and observations

Best Practices

Use Scopes

Organize memories into logical scopes for easier filtering

Set Confidence

Assign confidence scores to help prioritize recall results

Metadata

Enrich memories with metadata for advanced filtering

Consolidate

Periodically consolidate to merge duplicates and decay old memories

Next Steps

Agents API

Learn how agents interact with memory

Workflows API

Use memory in multi-agent workflows