let alaya = Alaya::open("memory.db")?;
alaya.episodes().store(&episode)?;           // store
let results = alaya.knowledge().query(&query)?; // retrieve
alaya.lifecycle().consolidate(&provider)?;   // distill knowledge
alaya.lifecycle().transform()?;              // dedup, LTD, discover categories
alaya.lifecycle().forget()?;                 // decay what's stale
let cats = alaya.admin().categories(None)?;  // emergent ontology
alaya.admin().purge(PurgeFilter::Session("s1"))?; // cascade delete + tombstones

{
  "mcpServers": {
    "alaya": {
      "command": "npx",
      "args": ["-y", "alaya-mcp"]
    }
  }
}

{
  "mcpServers": {
    "alaya": {
      "command": "npx",
      "args": ["-y", "alaya-mcp"],
      "env": {
        "ALAYA_LLM_API_KEY": "sk-...",
        "ALAYA_LLM_API_URL": "https://api.openai.com/v1/chat/completions",
        "ALAYA_LLM_MODEL": "gpt-4o-mini"
      }
    }
  }
}

git clone https://github.com/SecurityRonin/alaya.git
cd alaya
cargo build --release --features "mcp llm"

{
  "mcpServers": {
    "alaya": {
      "command": "/path/to/alaya/target/release/alaya-mcp"
    }
  }
}

Agent: [calls remember(content="User prefers dark mode", role="user", session_id="s1")]
Alaya: Stored episode 1 in session 's1'

Agent: [calls recall(query="user preferences")]
Alaya: Found 1 memories:
  1. [user] (score: 0.847) User prefers dark mode

Agent: [calls status()]
Alaya: Memory Status:
  Episodes: 1 (1 this session, 1 unconsolidated)
  Knowledge: none
  Categories: 0
  Preferences: 0 crystallized, 0 impressions accumulating
  Graph: 0 links
  Embedding coverage: 0/1 nodes (0%)

[dependencies]
alaya = "0.2.2"

use alaya::{Alaya, NewEpisode, Role, EpisodeContext, Query, NoOpProvider};

// Open a persistent database (or use open_in_memory() for tests)
let alaya = Alaya::open("memory.db")?;

// Store a conversation episode
alaya.episodes().store(&NewEpisode {
    content: "I've been learning Rust for about six months now".into(),
    role: Role::User,
    session_id: "session-1".into(),
    timestamp: 1740000000,
    context: EpisodeContext::default(),
    embedding: None, // pass Some(vec![...]) if you have embeddings
})?;

// Query with hybrid retrieval (BM25 + vector + graph + RRF)
let results = alaya.knowledge().query(&Query::simple("Rust experience"))?;
for mem in &results {
    println!("[{:.2}] {}", mem.score, mem.content);
}

// Get crystallized preferences
let prefs = alaya.admin().preferences(Some("communication_style"))?;

// Run lifecycle (NoOpProvider works without an LLM)
alaya.lifecycle().consolidate(&NoOpProvider)?;
alaya.lifecycle().transform()?;
alaya.lifecycle().forget()?;

git clone https://github.com/SecurityRonin/alaya.git
cd alaya
cargo run --example demo

Your Agent                          Alaya
─────────                           ─────

Via MCP (stdio):                    alaya-mcp binary
  remember(content, role, session)    ──▶ episodic store + graph links
  recall(query, boost_category?)      ──▶ BM25 + vector + graph → RRF → rerank
  learn(facts, session_id?)           ──▶ agent-driven knowledge extraction
  status()                            ──▶ rich stats (episodes, knowledge, graph, embeddings)
  preferences(domain?)                ──▶ crystallized behavioral patterns
  knowledge(type?, category?)         ──▶ consolidated semantic nodes
  maintain()                          ──▶ dedup + decay
  purge(scope)                        ──▶ selective or full deletion
  categories(min_stability?)          ──▶ emergent ontology with hierarchy
  neighbors(node, depth?)             ──▶ graph spreading activation
  node_category(node_id)              ──▶ category assignment lookup
  import_claude_mem(path?)            ──▶ import from claude-mem.db
  import_claude_code(path)            ──▶ import from Claude Code JSONL

Via Rust library:                   Alaya coordinator
  alaya.episodes().store(ep)           ──▶ episodic store + graph links
  alaya.knowledge().query(q)           ──▶ BM25 + vector + graph → RRF → rerank
  alaya.admin().preferences(domain?)   ──▶ crystallized behavioral patterns
  alaya.knowledge().filter(f?)         ──▶ consolidated semantic nodes
  alaya.admin().categories(min?)       ──▶ emergent ontology with hierarchy
  alaya.admin().subcategories(id)      ──▶ children of a parent category
  alaya.graph().neighbors(node, d)     ──▶ graph spreading activation
  alaya.admin().node_category(id)      ──▶ category assignment lookup
  alaya.set_embedding_provider(p)      ──▶ auto-embed in store + query
  alaya.set_extraction_provider(p)     ──▶ enable auto-consolidation
  alaya.lifecycle().consolidate(p)     ──▶ episodes → semantic knowledge
  alaya.knowledge().learn(nodes)       ──▶ provider-less knowledge injection
  alaya.lifecycle().auto_consolidate() ──▶ extract + learn (needs ExtractionProvider)
  alaya.lifecycle().perfume(i, p)      ──▶ impressions → preferences
  alaya.lifecycle().transform()        ──▶ dedup, LTD, prune, split categories
  alaya.lifecycle().forget()           ──▶ Bjork strength decay + archival
  alaya.admin().purge(scope)           ──▶ cascade deletion + tombstones

flowchart LR
    Q[Query] --> BM25[BM25 / FTS5]
    Q --> VEC[Vector / Cosine]
    Q --> GR[Graph Neighbors]

    BM25 --> RRF[Reciprocal Rank Fusion]
    VEC --> RRF
    GR --> RRF

    RRF --> RR[Context-Weighted Reranking]
    RR --> SA[Spreading Activation + Enrichment]
    SA --> RIF[Retrieval-Induced Forgetting]
    RIF --> OUT[Top 3-5 Results<br/>Episodes + Semantic + Preferences]

use alaya::*;

struct MyProvider { /* your LLM client */ }

impl ConsolidationProvider for MyProvider {
    fn extract_knowledge(&self, episodes: &[Episode]) -> Result<Vec<NewSemanticNode>> {
        // Ask your LLM: "What facts/relationships can you extract?"
        todo!()
    }

    fn extract_impressions(&self, interaction: &Interaction) -> Result<Vec<NewImpression>> {
        // Ask your LLM: "What behavioral signals does this contain?"
        todo!()
    }

    fn detect_contradiction(&self, a: &SemanticNode, b: &SemanticNode) -> Result<bool> {
        // Ask your LLM: "Do these two facts contradict each other?"
        todo!()
    }
}

use alaya::*;

struct MyExtractor { /* your LLM client */ }

impl ExtractionProvider for MyExtractor {
    fn extract(&self, episodes: &[Episode]) -> Result<Vec<NewSemanticNode>> {
        // Ask your LLM: "Extract facts from these conversations"
        todo!()
    }
}

let mut alaya = Alaya::open("memory.db")?;
alaya.set_extraction_provider(Box::new(MyExtractor { /* ... */ }));

// Now auto_consolidate() works without a ConsolidationProvider
let report = alaya.lifecycle().auto_consolidate()?;

use alaya::LlmExtractionProvider;

let provider = LlmExtractionProvider::builder()
    .api_key("sk-...")
    .model("gpt-4o-mini")      // default; any small model works
    .build()?;

impl Alaya {
    // Open / create
    pub fn open(path: impl AsRef<Path>) -> Result<Self>;
    pub fn open_in_memory() -> Result<Self>;

    // Providers (on coordinator)
    pub fn set_embedding_provider(&mut self, provider: Box<dyn EmbeddingProvider>);
    pub fn set_extraction_provider(&mut self, provider: Box<dyn ExtractionProvider>);

    // Sub-manager accessors
    pub fn episodes(&self) -> Episodes<'_>;
    pub fn knowledge(&self) -> Knowledge<'_>;
    pub fn lifecycle(&self) -> Lifecycle<'_>;
    pub fn graph(&self) -> Graph<'_>;
    pub fn admin(&self) -> Admin<'_>;
}

impl Episodes<'_> {
    pub fn store(&self, episode: &NewEpisode) -> Result<EpisodeId>;
    pub fn by_session(&self, session_id: &str) -> Result<Vec<Episode>>;
    pub fn unconsolidated(&self, limit: u32) -> Result<Vec<Episode>>;
}

impl Knowledge<'_> {
    pub fn query(&self, q: &Query) -> Result<Vec<ScoredMemory>>;
    pub fn learn(&self, nodes: Vec<NewSemanticNode>) -> Result<ConsolidationReport>;
    pub fn filter(&self, filter: Option<KnowledgeFilter>) -> Result<Vec<SemanticNode>>;
}

impl Lifecycle<'_> {
    pub fn consolidate(&self, provider: &dyn ConsolidationProvider) -> Result<ConsolidationReport>;
    pub fn auto_consolidate(&self) -> Result<ConsolidationReport>;
    pub fn transform(&self) -> Result<TransformationReport>;
    pub fn forget(&self) -> Result<ForgettingReport>;
    pub fn perfume(&self, interaction: &Interaction, provider: &dyn ConsolidationProvider) -> Result<PerfumingReport>;
    pub fn dream(&self, provider: &dyn ConsolidationProvider, interaction: Option<&Interaction>) -> Result<DreamReport>;
}

impl Admin<'_> {
    pub fn status(&self) -> Result<MemoryStatus>;
    pub fn purge(&self, filter: PurgeFilter) -> Result<PurgeReport>;
    pub fn preferences(&self, domain: Option<&str>) -> Result<Vec<Preference>>;
    pub fn categories(&self, min_stability: Option<f32>) -> Result<Vec<Category>>;
    pub fn subcategories(&self, parent_id: CategoryId) -> Result<Vec<Category>>;
    pub fn node_category(&self, node_id: NodeId) -> Result<Option<Category>>;
}

graph LR
    AGENT["AI Agent"]

    subgraph SIMPLE["Simple"]
        FILE["File-Based<br/><i>MEMORY.md<br/>OpenClaw</i>"]
    end

    subgraph INTEGRATED["Integrated"]
        FW["Framework Memory<br/><i>LangChain · CrewAI<br/>Letta</i>"]
        CODE["Coding Agent<br/><i>Beads · Engram<br/>via MCP</i>"]
    end

    subgraph ENGINES["Memory Engines"]
        DED["Dedicated Systems<br/><i><b>Alaya</b> · Vestige<br/>mem0 · Zep</i>"]
    end

    subgraph INFRA["Infrastructure"]
        VDB["Vector DBs<br/><i>Pinecone · Chroma<br/>Weaviate</i>"]
    end

    RESEARCH["Research<br/><i>Generative Agents<br/>SYNAPSE · HippoRAG</i>"]

    AGENT <--> FILE
    AGENT <--> FW
    AGENT <--> CODE
    AGENT <--> DED
    DED -.->|storage| VDB
    FW -.->|storage| VDB
    RESEARCH -.->|ideas| DED
    RESEARCH -.->|ideas| FW