Memory

Agents have two memory mechanisms: persistent memory (per-agent SQLite KV store, survives restarts) and blackboard (shared, in-memory KV store).

Persistent Memory

Reading

#![allow(unused)]
fn main() {
let value: Option<serde_json::Value> = agent.memory_get("config").await?;
match value {
    Some(v) => println!("config = {}", v),
    None => println!("config not set"),
}
}

Writing

#![allow(unused)]
fn main() {
agent.memory_set("config", json!({"theme": "dark", "retries": 3})).await?;
}

TTL (Time-to-Live)

The SDK's memory_set does not support TTL directly. Use the underlying IPC client for TTL writes:

#![allow(unused)]
fn main() {
use libagent::ipc::Request;
agent.client.send(Request::MemoryWrite {
    agent_id: agent.id,
    key: "session".to_string(),
    value: json!("abc123"),
    ttl_secs: Some(3600),
}).await?;
}

Capabilities Required

spec:
  capabilities:
    - memory.read:*     # read any key
    - memory.write:*    # write any key

Scope to specific keys:

    - memory.read:config
    - memory.write:notes

Blackboard (Shared State)

The blackboard is shared across all agents. Use it for coordination.

#![allow(unused)]
fn main() {
use libagent::ipc::Request;

// Read from blackboard
let response = agent.client.send(Request::BlackboardRead {
    agent_id: agent.id,
    key: "task-queue-head".to_string(),
}).await?;

// Write to blackboard
agent.client.send(Request::BlackboardWrite {
    agent_id: agent.id,
    key: "task-queue-head".to_string(),
    value: json!(42),
    ttl_secs: None,
}).await?;

// Compare-and-swap
agent.client.send(Request::BlackboardCas {
    agent_id: agent.id,
    key: "lock".to_string(),
    expected: json!(null),  // only write if key is absent
    new_value: json!(agent.id.to_string()),
    ttl_secs: Some(30),
}).await?;
}

Memory vs Blackboard: When to Use Which