ainl-memory

⚠️ Alpha — API subject to change

The unified graph substrate for AINL agents.
Execution IS memory. Memory IS the graph.

What it is

ainl-memory implements the AINL unified graph: a single typed, executable, auditable artifact that simultaneously encodes an agent's memory, persona, tools, and execution history.

Unlike systems that treat memory as a separate retrieval layer (RAG, vector stores, external graph DBs), ainl-memory makes the execution graph itself the memory substrate — no retrieval boundary, no translation step, no sync problem.

Documentation map

The five memory families

AinlNodeKind::RuntimeState matches the runtime_state SQL / JSON tag; MemoryCategory::RuntimeState is the same slice for exports and analytics.

Referential integrity & edges

SQLite enforces basic referential integrity on the graph edge table:

• Table ainl_graph_edges columns: from_id, to_id, label, weight, metadata (primary key (from_id, to_id, label)).
• FOREIGN KEY (from_id) and FOREIGN KEY (to_id) reference ainl_graph_nodes(id) with ON DELETE CASCADE.
• PRAGMA foreign_keys = ON is applied when opening a SqliteGraphStore (see open / from_connection).

Legacy databases (edges table created before FK metadata): on first open, a one-time migration rebuilds ainl_graph_edges. Only rows whose both endpoints exist in ainl_graph_nodes are copied; historical dangling rows are dropped (they cannot exist under FK rules). Details: CHANGELOG.md § 0.1.4-alpha.

Write paths

Repair / forensic import

• import_graph(snapshot, allow_dangling_edges): use false everywhere in production (strict). Use true only to load snapshots that violate referential integrity: FK checks are disabled only for that import, then restored. Always follow with validate_graph and fix data before resuming normal writes on the same connection.

Higher-level validation (orthogonal to FK row existence)

• validate_graph(agent_id) reports agent-scoped edges, dangling endpoint pairs, optional DanglingEdgeDetail (includes edge label), cross_agent_boundary_edges, orphans, and is_valid. Use this for semantics, exports alignment, and post-repair audits.

Rust snapshot type vs SQL

• SnapshotEdge uses source_id / target_id / edge_type; the database uses from_id / to_id / label. Import/export maps between them.

Core API

Store

use ainl_memory::{AinlMemoryNode, GraphStore, SqliteGraphStore};
use std::path::Path;

let store = SqliteGraphStore::open(Path::new("memory.db"))?;
let mut node = AinlMemoryNode::new_episode(
    uuid::Uuid::new_v4(),
    chrono::Utc::now().timestamp(),
    vec!["file_read".into()],
    None,
    None,
);
node.agent_id = "my-agent".into();
store.write_node(&node)?;

GraphQuery (SqliteGraphStore::query)

Builder scoped to one agent: COALESCE(json_extract(payload, '$.agent_id'), '') = <agent_id>. Edge traversal uses SQL columns from_id, to_id, label.

Legacy helpers (recall_recent, find_patterns, walk_from, …) live in the same crate and take GraphStore plus explicit agent_id where needed.

use ainl_memory::SqliteGraphStore;

let store = SqliteGraphStore::open(std::path::Path::new("memory.db"))?;
let recent = store.query("my-agent").recent_episodes(10)?;
let lineage = store.query("my-agent").lineage(some_node_id)?;
let internal = store.query("my-agent").subgraph_edges()?;

Export / import snapshots

use ainl_memory::SqliteGraphStore;

let store = SqliteGraphStore::open(std::path::Path::new("memory.db"))?;
let snapshot = store.export_graph("my-agent")?;
// snapshot.schema_version is typically "1.0" (see SNAPSHOT_SCHEMA_VERSION).

let mut fresh = SqliteGraphStore::open(std::path::Path::new("copy.db"))?;
fresh.import_graph(&snapshot, false)?; // strict: FK on

Graph validation

use ainl_memory::SqliteGraphStore;

let store = SqliteGraphStore::open(std::path::Path::new("memory.db"))?;
let report = store.validate_graph("my-agent")?;
assert!(report.is_valid);
// `dangling_edge_details`: source_id, target_id, edge_type (label)
// `cross_agent_boundary_edges`: touches agent on one side only (informational)

Session state (read_runtime_state / write_runtime_state)

Stable one row per agent_id (deterministic UUIDv5 over the agent id) — use the helpers instead of hand-rolling nodes:

use ainl_memory::{GraphMemory, RuntimeStateNode, SqliteGraphStore};
use std::path::Path;

let store = SqliteGraphStore::open(Path::new("memory.db"))?;
let memory = GraphMemory::from_sqlite_store(store);

let state = RuntimeStateNode {
    agent_id: "my-agent".into(),
    turn_count: 12,
    last_extraction_at_turn: 10,
    persona_snapshot_json: serde_json::to_string("compiled persona lines…").ok(),
    updated_at: chrono::Utc::now().timestamp(),
};
memory.write_runtime_state(&state)?;
let _loaded = memory.read_runtime_state("my-agent")?;

let q = memory.sqlite_store().query("my-agent");
let _same = q.read_runtime_state()?;

Legacy rows may still carry JSON keys last_extraction_turn, last_persona_prompt, or RFC3339 updated_at strings; RuntimeStateNode deserializes them via serde aliases / a tolerant timestamp parser.

GraphMemory forwards

GraphMemory exposes validate_graph, export_graph, import_graph, agent_subgraph_edges, write_node_with_edges, insert_graph_edge_checked, read_runtime_state, and write_runtime_state so hosts like ainl-runtime can checkpoint or boot-gate without reaching past the high-level API.

Integration tests (pointers)

Crate ecosystem

• Publishing — order, dry-runs, and pre-release resolver pitfalls: scripts/publish-prep-ainl-crates.sh, docs/ainl-runtime-graph-patch.md (Pre-release versions and cargo publish).
• ainl-memory — this crate (storage + query); published version is 0.1.8-alpha on the workspace (aligns with ainl-runtime / ainl-graph-extractor pins — see crates.io and sibling Cargo.toml files).
• ainl-runtime — agent turn execution, depends on ainl-memory (+ persona, extractor, semantic-tagger)
• ainl-persona — persona evolution engine, depends on ainl-memory
• ainl-graph-extractor — periodic signal extraction, depends on ainl-memory + ainl-persona
• ainl-semantic-tagger — deterministic text tagging, no ainl-memory dependency

Why this is different

Traditional stacks bolt a vector index or key-value “memory” onto an LLM and hope embeddings stay aligned with what actually ran. AINL instead treats every tool call, fact, patch, and persona shift as first-class graph data you can traverse, validate, and export as one artifact — closer to a provenance-rich program trace than a fuzzy recall cache.

License

MIT OR Apache-2.0