Memory Integration

Memory Integration

Personas can declare a memory requirement in their pack manifest. The runtime satisfies it through a pluggable adapter trait with backends for HTTP APIs and local SQLite.

Declaring memory requirements

In pack.toml:

[capability_manifest]
memory_required = "required"    # or "optional" or "none"
memory_required_ops = ["search", "recall", "context"]

Valid operations: store, search, recall, context.

• "none" -- Persona does not use memory.
• "optional" -- Persona benefits from memory but works without it.
• "required" -- Persona will not activate without a configured memory backend.

MemoryAdapter trait

The frameshift-memory crate defines the adapter contract:

#[async_trait]
pub trait MemoryAdapter: Send + Sync {
    async fn store(&self, text: &str, tags: &[String], metadata: Metadata) -> Result<MemoryId>;
    async fn search(&self, query: &str, k: usize, filters: Filters) -> Result<Vec<Memory>>;
    async fn recall(&self, id: MemoryId) -> Result<Memory>;
    async fn list(&self, limit: usize, offset: usize) -> Result<Vec<Memory>>;
    async fn forget(&self, id: MemoryId) -> Result<()>;
    async fn health(&self) -> Result<HealthStatus>;
}

Available backends

HTTP adapter (frameshift-memory-http)

Connects to any memory service that implements the Frameshift memory API. Kleos is the reference integration.

Configuration is provided through the vault:

• Endpoint URL
• Bearer token authentication
• Configurable timeout and retry policy

SQLite FTS adapter (frameshift-memory-sqlite-fts)

Local full-text search backed by SQLite with FTS5. No external services required.

Features:

• FTS5 full-text search with BM25 ranking
• Tag intersection filtering
• Time-range queries
• Metadata filtering
• WAL journal mode for concurrent access
• Auto-schema migration

How the runtime uses memory

The frameshift-runtime crate loads the vault configuration, checks whether a memory adapter is available, and validates it against the persona's declared requirements. If memory_required = "required" and no adapter is configured, activation fails with a clear error.

During rendering, memory context can be injected into the persona output. During sessions, the growth system and memory adapter work together -- growth is local (JSONL), memory is shared (via the adapter).