Memory API

The Memory API provides persistent storage for agent data through key-value stores, session management, and knowledge graph queries.

Key-Value Store

Each agent has a private KV store namespace (self.*) and can access shared global keys based on capability grants.

List All Keys

Retrieve all KV pairs for an agent.

curl http://127.0.0.1:4200/api/memory/agents/{id}/kv

string

required

Agent UUID

kv_pairs

array

Show KV pair object

key

string

Key name

value

any

Value (JSON object, string, number, etc.)

{
  "kv_pairs": [
    {"key": "preferences", "value": {"theme": "dark"}},
    {"key": "state", "value": {"step": 3}}
  ]
}

Get Key

Retrieve a specific key’s value.

curl http://127.0.0.1:4200/api/memory/agents/{id}/kv/{key}

string

required

Agent UUID

key

string

required

Key name

key

string

Key name

value

any

Value

{
  "key": "preferences",
  "value": {"theme": "dark"}
}

Set Key

Create or update a key-value pair.

curl -X PUT http://127.0.0.1:4200/api/memory/agents/{id}/kv/{key} \
  -H "Content-Type: application/json" \
  -d '{"value": {"theme": "dark", "language": "en"}}'

string

required

Agent UUID

key

string

required

Key name

value

any

required

Value (any JSON-serializable data)

{
  "status": "stored",
  "key": "preferences"
}

Delete Key

Remove a key-value pair.

curl -X DELETE http://127.0.0.1:4200/api/memory/agents/{id}/kv/{key}

string

required

Agent UUID

key

string

required

Key name

{
  "status": "deleted",
  "key": "preferences"
}

Session Management

Sessions store conversation history and context window state.

List All Sessions

Retrieve all active sessions across agents.

curl http://127.0.0.1:4200/api/sessions

sessions

array

Show Session object

string

Session UUID

agent_id

string

Agent UUID

agent_name

string

Agent name

message_count

integer

Total messages

created_at

string

Creation timestamp

{
  "sessions": [
    {
      "id": "s1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "agent_name": "coder",
      "message_count": 12,
      "created_at": "2025-01-15T10:30:00Z"
    }
  ]
}

Get Session

Retrieve a specific session’s conversation history.

curl http://127.0.0.1:4200/api/agents/{id}/session

See Agents API - Get Session History for full response schema.

Delete Session

Remove a session and its conversation history.

curl -X DELETE http://127.0.0.1:4200/api/sessions/{id}

string

required

Session UUID

{
  "status": "deleted",
  "session_id": "s1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Label Session

Assign a human-readable label to a session for easy retrieval.

curl -X PUT http://127.0.0.1:4200/api/sessions/{id}/label \
  -H "Content-Type: application/json" \
  -d '{"label": "project-alpha-discussion"}'

string

required

Session UUID

label

string

required

Session label

{
  "status": "updated",
  "session_id": "s1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "label": "project-alpha-discussion"
}

Find Session by Label

Retrieve a session by its label.

curl http://127.0.0.1:4200/api/agents/{id}/sessions/by-label/{label}

string

required

Agent UUID

label

string

required

Session label

session_id

string

Session UUID

message_count

integer

Total messages

label

string

Session label

List Agent Sessions

Get all sessions for a specific agent.

curl http://127.0.0.1:4200/api/agents/{id}/sessions

string

required

Agent UUID

sessions

array

Array of session objects (same schema as List All Sessions)

Create Agent Session

Create a new session for an agent.

curl -X POST http://127.0.0.1:4200/api/agents/{id}/sessions \
  -H "Content-Type: application/json" \
  -d '{"label": "new-topic"}'

string

required

Agent UUID

label

string

Optional session label

{
  "status": "created",
  "session_id": "s5e6f7g8-h9i0-1234-jklm-nopqrstuv567",
  "label": "new-topic"
}

Switch Agent Session

Switch an agent to a different session.

curl -X POST http://127.0.0.1:4200/api/agents/{id}/sessions/{session_id}/switch

string

required

Agent UUID

session_id

string

required

Session UUID to switch to

{
  "status": "switched",
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "session_id": "s5e6f7g8-h9i0-1234-jklm-nopqrstuv567"
}

Knowledge Graph

OpenFang stores message embeddings and enables semantic search across conversation history.

The knowledge graph API is under active development. Current endpoints are subject to change.

Query Similar Messages

Find messages semantically similar to a query.

curl -X POST http://127.0.0.1:4200/api/memory/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do I configure authentication?",
    "limit": 5,
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

query

string

required

Query text

limit

integer

default:"10"

Max results to return

agent_id

string

Optional: filter to specific agent

results

array

Show Result object

message

string

Message text

score

number

Similarity score (0-1)

session_id

string

Source session UUID

agent_name

string

Source agent name

timestamp

string

Message timestamp

Memory Capabilities

Agents must declare memory access in their manifest:

agent.toml

[capabilities]
memory_read = ["*"]           # Read all keys
memory_write = ["self.*"]      # Write to own namespace only

Access patterns:

["*"] — Full access (read or write all keys)
["self.*"] — Own namespace only (agent_id.*)
["shared.*"] — Shared global keys
["team.alpha.*"] — Team-specific namespace
[] — No memory access

Security:

Agents cannot read/write outside their granted capabilities
Memory operations are logged in the audit trail
KV keys are isolated by namespace

Memory Backend

OpenFang uses SQLite for memory persistence:

KV store — ~/.openfang/data/memory.db table kv_store
Sessions — ~/.openfang/data/memory.db table sessions
Embeddings — ~/.openfang/data/memory.db table embeddings (future)

All writes are immediately flushed to disk for durability.

Best Practices

Use namespaces for organization

Prefix keys with namespaces for clarity:

# User preferences
PUT /api/memory/agents/{id}/kv/user.preferences

# Application state
PUT /api/memory/agents/{id}/kv/app.state

# Temporary cache
PUT /api/memory/agents/{id}/kv/cache.search_results

Label important sessions

Use descriptive labels for sessions you’ll need to reference later:

PUT /api/sessions/{id}/label -d '{"label": "project-alpha-kickoff"}'

Then retrieve by label:

GET /api/agents/{id}/sessions/by-label/project-alpha-kickoff

Compact long sessions regularly

Sessions with 100+ messages should be compacted to reduce context window usage:

POST /api/agents/{id}/session/compact

This summarizes old messages while keeping recent ones intact.

Delete unused sessions

Clean up old sessions to reduce storage:

DELETE /api/sessions/{id}

Or reset an agent’s session:

POST /api/agents/{id}/session/reset

Use KV store for structured data

Store JSON objects for complex state:

PUT /api/memory/agents/{id}/kv/workflow_state -d '{
  "value": {
    "current_step": 3,
    "completed_steps": ["analyze", "review"],
    "pending_steps": ["summarize", "report"]
  }
}'

Next Steps

Agents API

Manage agent sessions

Workflows API

Store workflow state in KV

Usage Tracking

Monitor memory usage

Security

Memory capability grants

Overview

Core Endpoints

Tools & Extensions

OpenAI Compatible

Key-Value Store

List All Keys

Get Key

Set Key

Delete Key

Session Management

List All Sessions

Get Session

Delete Session

Label Session

Find Session by Label

List Agent Sessions

Create Agent Session

Switch Agent Session

Knowledge Graph

Query Similar Messages

Memory Capabilities

Memory Backend

Best Practices

Next Steps

Agents API

Workflows API

Usage Tracking

Security

Build docs developers (and LLMs) love

Overview

Core Endpoints

Tools & Extensions

OpenAI Compatible

​Key-Value Store

​List All Keys

​Get Key

​Set Key

​Delete Key

​Session Management

​List All Sessions

​Get Session

​Delete Session

​Label Session

​Find Session by Label

​List Agent Sessions

​Create Agent Session

​Switch Agent Session

​Knowledge Graph

​Query Similar Messages

​Memory Capabilities

​Memory Backend

​Best Practices

​Next Steps

Agents API

Workflows API

Usage Tracking

Security

Build docs developers (and LLMs) love

Key-Value Store

List All Keys

Get Key

Set Key

Delete Key

Session Management

List All Sessions

Get Session

Delete Session

Label Session

Find Session by Label

List Agent Sessions

Create Agent Session

Switch Agent Session

Knowledge Graph

Query Similar Messages

Memory Capabilities

Memory Backend

Best Practices

Next Steps