Memory API

Overview

OpenFang provides a unified memory substrate with three layers:

Key-Value Store - Structured data storage per agent
Semantic Memory - Vector-based recall with embeddings
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

{
  "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

{
  "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"}'

{
  "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

{
  "status": "deleted"
}

Semantic Memory

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

Memory Fragment Structure

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!("[email protected]")),
        ("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

REST API

CLI Reference

OpenAI Compatibility

Overview

Key-Value Store

Get All Keys

Get Value by Key

Set Value

Delete Key

Semantic Memory

Memory Fragment Structure

Store Memory

Recall Memories

Memory Filters

Knowledge Graph

Entity Types

Relation Types

Add Entity

Add Relation

Query Graph

Memory Consolidation

Export & Import

Memory Scopes

Best Practices

Use Scopes

Set Confidence

Metadata

Consolidate

Next Steps

Agents API

Workflows API

REST API

CLI Reference

OpenAI Compatibility

​Overview

​Key-Value Store

​Get All Keys

​Get Value by Key

​Set Value

​Delete Key

​Semantic Memory

​Memory Fragment Structure

​Store Memory

​Recall Memories

​Memory Filters

​Knowledge Graph

​Entity Types

​Relation Types

​Add Entity

​Add Relation

​Query Graph

​Memory Consolidation

​Export & Import

​Memory Scopes

​Best Practices

Use Scopes

Set Confidence

Metadata

Consolidate

​Next Steps

Agents API

Workflows API

Overview

Key-Value Store

Get All Keys

Get Value by Key

Set Value

Delete Key

Semantic Memory

Memory Fragment Structure

Store Memory

Recall Memories

Memory Filters

Knowledge Graph

Entity Types

Relation Types

Add Entity

Add Relation

Query Graph

Memory Consolidation

Export & Import

Memory Scopes

Best Practices

Next Steps