kyma_memory/lib.rs
1//! Agentic Memory substrate for Kyma.
2//!
3//! Memory is stored as ordinary Kyma columnar tables (`memory_nodes` /
4//! `memory_edges`) registered as the `memory` graph, so it is first-class
5//! queryable (`run_sql`/`run_kql`/Discover) and renders in the unified
6//! GraphView. Embeddings are a `FixedSizeList<Float32>` column searched via the
7//! platform `cosine_distance` UDF. Storage is append-only; mutations write a new
8//! version and recall dedups to the latest by `updated_at`.
9//!
10//! See `docs/superpowers/specs/2026-05-31-agentic-memory-design.md` (M1).
11
12pub mod embed;
13pub mod error;
14pub mod rows;
15pub mod schema;
16pub mod sql;
17pub mod types;
18mod writer;
19
20pub use embed::{build_embedding_backend, shared_embedding};
21pub use error::{MemoryError, Result};
22pub use types::{CreateMemory, MemoryStatus, MemoryType, RecallFilter};
23pub use writer::MemoryWriter;
24
25/// Dedicated database that holds the memory tables.
26pub const DEFAULT_DATABASE: &str = "memory";
27/// Registered graph name for memory.
28pub const GRAPH_NAME: &str = "memory";
29pub const NODE_TABLE: &str = "memory_nodes";
30pub const EDGE_TABLE: &str = "memory_edges";
31
32/// Default per-item realm when none is supplied.
33pub const DEFAULT_REALM: &str = "default";
34/// Shared realm for cross-project facts; recall unions project ∪ global.
35pub const GLOBAL_REALM: &str = "global";
36
37/// Recall re-rank blend: `score = RELEVANCE_WEIGHT*(1-distance) + IMPORTANCE_WEIGHT*importance`.
38pub const RELEVANCE_WEIGHT: f64 = 0.7;
39pub const IMPORTANCE_WEIGHT: f64 = 0.3;
40
41/// Canonical memory edge-relationship types.
42///
43/// - [`EDGE_REFERENCES`]: a memory → an entity/node it is about.
44/// - [`EDGE_RESOLVES_TO`]: a memory-side `entity` node → the real catalog graph
45/// node it denotes (carries `target_namespace` for cross-graph stitching).
46/// - [`EDGE_RELATES_TO`]: entity ↔ entity, with the predicate in `props`.
47/// - [`EDGE_DERIVED_FROM`]: a memory → the source firehose/connector row it was
48/// extracted from (provenance edge).
49/// - [`EDGE_INVALIDATES`]: a new memory → the memory it supersedes (bi-temporal).
50/// - [`EDGE_MERGED_INTO`]: a memory → the memory it was merged into.
51pub const EDGE_REFERENCES: &str = "REFERENCES";
52pub const EDGE_RESOLVES_TO: &str = "RESOLVES_TO";
53pub const EDGE_RELATES_TO: &str = "RELATES_TO";
54pub const EDGE_DERIVED_FROM: &str = "DERIVED_FROM";
55pub const EDGE_INVALIDATES: &str = "INVALIDATES";
56pub const EDGE_MERGED_INTO: &str = "MERGED_INTO";
57
58/// Graph-aware hybrid recall blend. The final score fuses reciprocal-rank
59/// fusion (RRF) of the vector + keyword candidate lists with semantic
60/// similarity, keyword match, graph proximity, importance, and recency (see
61/// the `memory_retrieve` orchestrator). Tunable; sane defaults below.
62pub const W_RRF: f64 = 1.0;
63pub const W_SEMANTIC: f64 = 0.6;
64pub const W_KEYWORD: f64 = 0.3;
65pub const W_GRAPH: f64 = 0.5;
66pub const W_IMPORTANCE: f64 = 0.4;
67pub const W_RECENCY: f64 = 0.3;
68/// Reciprocal-rank-fusion constant in `1/(RRF_K + rank)`.
69pub const RRF_K: f64 = 60.0;
70/// Half-life (days) for recency decay `exp(-ln2 * age_days / HALF_LIFE_DAYS)`.
71pub const HALF_LIFE_DAYS: f64 = 30.0;