Crate ainl_memory 

AINL Memory - Graph-based agent memory substrate

Graph-as-memory for AI agents. Execution IS the memory.

AINL Memory implements agent memory as an execution graph. Every agent turn, tool call, and delegation becomes a typed graph node. No separate retrieval layer—the graph itself is the memory.

Quick Start

use ainl_memory::GraphMemory;
use std::path::Path;

let memory = GraphMemory::new(Path::new("memory.db")).unwrap();

// Record an episode
memory.write_episode(
    vec!["file_read".to_string(), "agent_delegate".to_string()],
    Some("agent-B".to_string()),
    None,
).unwrap();

// Recall recent episodes
let recent = memory.recall_recent(100).unwrap();

Architecture

AINL Memory is designed as infrastructure that any agent framework can adopt:

• Zero dependencies on specific agent runtimes
• Simple trait-based API via GraphStore
• Bring your own storage backend

Graph store: query, export, validation (since 0.1.4-alpha)

• SqliteGraphStore: SQLite backend with PRAGMA foreign_keys = ON, FOREIGN KEY constraints on ainl_graph_edges, one-time migration for legacy DBs (see CHANGELOG.md).
• GraphQuery: store.query(agent_id) — agent-scoped SQL helpers (episodes, lineage, tags, …).
• Snapshots: AgentGraphSnapshot, SnapshotEdge, SNAPSHOT_SCHEMA_VERSION; SqliteGraphStore::export_graph / SqliteGraphStore::import_graph (strict vs repair via allow_dangling_edges).
• Validation: GraphValidationReport, DanglingEdgeDetail; SqliteGraphStore::validate_graph for agent-scoped semantics beyond raw FK enforcement.
• GraphMemory forwards the above where hosts should not reach past the facade (see impl block).

Node Types

• Episode: What happened during an agent turn (tool calls, delegations)
• Semantic: Facts learned with confidence scores
• Procedural: Reusable compiled workflow patterns
• Persona: Agent traits learned over time
• Runtime state (RuntimeStateNode, node_type = runtime_state): Optional persisted session counters and persona snapshot JSON for ainl-runtime (see GraphMemory::read_runtime_state / GraphMemory::write_runtime_state).
• Trajectory (TrajectoryNode): execution traces for replay / learning.
• Failure (FailureNode): typed failures (e.g. loop guard) with optional FTS search (GraphMemory::search_failures_for_agent).

Re-exports

pub use anchored_summary::anchored_summary_id;

pub use anchored_summary::ANCHORED_SUMMARY_TAG;

pub use node::AinlEdge;

pub use node::AinlMemoryNode;

pub use node::AinlNodeKind;

pub use node::AinlNodeType;

pub use node::EpisodicNode;

pub use node::FailureNode;

pub use node::MemoryCategory;

pub use node::PersonaLayer;

pub use node::PersonaNode;

pub use node::PersonaSource;

pub use node::ProceduralNode;

pub use node::ProcedureType;

pub use node::RuntimeStateNode;

pub use node::SemanticNode;

pub use node::Sentiment;

pub use node::StrengthEvent;

pub use node::TrajectoryNode;

pub use query::count_by_topic_cluster;

pub use query::find_high_confidence_facts;

pub use query::find_patterns;

pub use query::find_strong_traits;

pub use query::recall_by_procedure_type;

pub use query::recall_by_topic_cluster;

pub use query::recall_contradictions;

pub use query::recall_delta_by_relevance;

pub use query::recall_episodes_by_conversation;

pub use query::recall_episodes_with_signal;

pub use query::recall_flagged_episodes;

pub use query::recall_low_success_procedures;

pub use query::recall_recent;

pub use query::recall_strength_history;

pub use query::recall_task_scoped_episodes;

pub use query::walk_from;

pub use query::GraphQuery;

pub use snapshot::AgentGraphSnapshot;

pub use snapshot::DanglingEdgeDetail;

pub use snapshot::GraphValidationReport;

pub use snapshot::SnapshotEdge;

pub use snapshot::SNAPSHOT_SCHEMA_VERSION;

pub use store::GraphStore;

pub use store::GraphValidationError;

pub use store::SnapshotImportError;

pub use store::SqliteGraphStore;

pub use trajectory_table::TrajectoryDetailRecord;

Modules

anchored_summary

Persistence helpers for ainl-context-compiler anchored summaries (Phase 6 of SELF_LEARNING_INTEGRATION_MAP.md).

node

AINL graph node types - the vocabulary of agent memory.

pattern_promotion

Gate for when an extracted tool-sequence pattern is treated as a reusable, prompt-visible procedure (Phase 3 — pattern promotion; see docs/SELF_LEARNING_INTEGRATION_MAP.md).

query

Graph traversal and querying utilities.

snapshot

Serializable graph snapshots and validation reports.

store

Graph storage backends for AINL memory.

trajectory_table

Row-oriented trajectory storage in ainl_trajectories (sibling to graph nodes).

Structs

GraphMemory

High-level graph memory API - the main entry point for AINL memory.

Functions

persist_trajectory_coarse_tools

Convenience when only coarse tool names are known (no per-call timings).

persist_trajectory_for_episode

Write trajectory graph node, trajectory_of edge, and ainl_trajectories detail row.

trajectory_env_enabled

When unset or any non-falsy value, trajectory rows are written after each successful episode (same opt-out semantics as AINL_EXTRACTOR_ENABLED in OpenFang: 0, false, no, off).