Struct Memory 

pub struct Memory {

    pub id: String,
    pub tier: Tier,
    pub namespace: String,
    pub title: String,
    pub content: String,
    pub tags: Vec<String>,
    pub priority: i32,
    pub confidence: f64,
    pub source: String,
    pub access_count: i64,
    pub created_at: String,
    pub updated_at: String,
    pub last_accessed_at: Option<String>,
    pub expires_at: Option<String>,
    pub metadata: Value,
    pub reflection_depth: i32,
    pub memory_kind: MemoryKind,
    pub entity_id: Option<String>,
    pub persona_version: Option<i32>,
    pub citations: Vec<Citation>,
    pub source_uri: Option<String>,
    pub source_span: Option<SourceSpan>,
    pub confidence_source: ConfidenceSource,
    pub confidence_signals: Option<ConfidenceSignals>,
    pub confidence_decayed_at: Option<String>,
    pub version: i64,
}

Fields

id: String

tier: Tier

namespace: String

title: String

content: String

tags: Vec<String>

priority: i32

confidence: f64

0.0-1.0 — how certain is this memory

source: String

Who/what created this row. Role-categorical, not vendor-specific. Canonical closed set lives in [crate::validate::VALID_SOURCES] at v0.7.0: user, nhi (crate::validate::DEFAULT_NHI_SOURCE — the vendor-neutral substrate default for AI-NHI-minted writes per #1175), claude (deprecated; back-compat only, removal in v0.8.x), hook, api, cli, import, consolidation, system, chaos, notify (S32 inbox replication path). Validator surface: crate::validate::validate_source.

access_count: i64

created_at: String

updated_at: String

last_accessed_at: Option<String>

expires_at: Option<String>

metadata: Value

reflection_depth: i32

v0.7.0 Task 1/8 (recursive learning) — depth in the substrate-native reflection recursion tree. 0 for memories minted directly from a caller (or any pre-v0.7.0 row), positive for memories synthesised by the reflection pass over lower-depth peers. Operators can cap recursion depth at write time; readers can filter / sort by it.

#[serde(default)] lets pre-v0.7.0 JSON payloads (and older federation peers) deserialize cleanly — missing → 0, which matches the SQL DEFAULT 0 on the column added in schema v29 (SQLite) / v31 (Postgres).

memory_kind: MemoryKind

L1-1 (v0.7.0) — typed memory-kind discriminator. Stored in memories.memory_kind TEXT NOT NULL DEFAULT 'observation' (schema v30). Observation for every pre-v30 row (SQL default); Reflection for memories minted by memory_reflect or the curator reflection pass.

#[serde(default)] ensures round-trips with pre-v30 federation peers that don’t yet emit the field.

entity_id: Option<String>

v0.7.0 QW-2 — populated only when memory_kind == Persona. Identifies the subject of the persona. Stored on the SQL column memories.entity_id TEXT NULL (schema v36). skip_serializing_if = "Option::is_none" keeps the absent shape on the wire for pre-QW-2 federation peers.

persona_version: Option<i32>

v0.7.0 QW-2 — monotonic per-(entity_id, namespace) version counter for the Persona artefact. Populated only when memory_kind == Persona. Each PersonaGenerator::generate call writes a new row with version + 1; older rows stay queryable for audit / rollback.

citations: Vec<Citation>

v0.7.0 Form 4 (issue #757) — fact-provenance citations array. Each entry carries a typed Citation envelope (uri, accessed_at, optional hash, optional span). Stored on the memories.citations TEXT column (schema v38) as a JSON-encoded array — legacy rows default to an empty vector via the SQL DEFAULT '[]' clause and the serde default below. Validator surface lives at crate::validate::validate_citation.

NSA CSI MCP Security mapping. Part of the Form 4 fact-provenance triple (citations + source_uri + source_span) that addresses NSA concerns (b) Insecure context or data serialization + (g) Poor or missing audit logs, and contributes to NSA recommendations (c) Validate parameters + (f) Filter and monitor output pipelines per the National Security Agency Cybersecurity Information document on MCP security (U/OO/6030316-26 | PP-26-1834, May 2026 Version 1.0). Capability inventory anchor: form_4_fact_provenance. The mapping is described — without implying NSA endorsement of ai-memory or AlphaOne LLC — at docs/compliance/nsa-csi-mcp.html §3.2 / §3.7 / §4.3 / §4.6.

source_uri: Option<String>

v0.7.0 Form 4 (issue #757) — first-class URI-form pointer to the cited source body. Distinct from the role-label source column. Accepted schemes: uri: (HTTP URL), doc: (substrate doc id), file: (filesystem path). Validator surface lives at crate::validate::validate_source_uri. Mapped onto the memories.source_uri TEXT column (schema v38). NULL on legacy rows and on rows that do not yet carry a URI form.

source_span: Option<SourceSpan>

v0.7.0 Form 4 (issue #757) — byte-range into the parent source body. Populated by the WT-1-B atomisation writer for each atom (atom-grain span fact-provenance) and may be set by callers who can pin the offset of a memory inside its referenced source. Mapped onto the memories.source_span TEXT column (schema v38) as a JSON {start, end} envelope. Validator surface lives at crate::validate::validate_source_span.

confidence_source: ConfidenceSource

v0.7.0 Form 5 (issue #758) — typed discriminator naming the provenance of the confidence value. Stored on memories.confidence_source TEXT NOT NULL DEFAULT 'caller_provided' (schema v39 sqlite / v38 postgres). Defaults to CallerProvided for every legacy row and every write that arrives with the auto-derive engine disabled.

confidence_signals: Option<ConfidenceSignals>

v0.7.0 Form 5 — JSON snapshot of the signals that produced an auto-derived or calibrated confidence value. Mapped onto memories.confidence_signals TEXT NULL (schema v39 sqlite / v38 postgres). NULL on legacy rows and on rows whose confidence_source = CallerProvided.

confidence_decayed_at: Option<String>

v0.7.0 Form 5 — RFC3339 stamp of the last decay computation. Mapped onto memories.confidence_decayed_at TEXT NULL (schema v39 sqlite / v38 postgres). NULL on legacy rows and on rows never touched by the decay updater.

version: i64

v0.7.0 Provenance Gap 1 (issue #884, schema v45 sqlite) — optimistic-concurrency counter. Bumped on every mutation: storage::update AND the (title, namespace) upsert-merge arm of storage::insert (#1632). Two callers writing against the same expected_version race exactly one winner; the loser receives a typed CONFLICT envelope naming the current stored version. The confidence-decay sweep is the only documented non-bumping mutator (tests/non_version_bumping_sites_1036.rs). Legacy rows land at version = 1 via the SQL DEFAULT clause. #[serde(default = "default_memory_version")] keeps pre-v45 federation peers / JSON payloads deserialising cleanly.

Implementations

impl Memory

pub const FIELD_COUNT: usize = 26

Total number of declared pub <name>: <type> fields on the Memory struct at v0.7.0. SSOT for the “26-field struct at v0.7.0 (was 15 at v0.6.x)” narrative in CLAUDE.md / README.md / ROADMAP.md / release-notes. Adding or removing a field requires bumping this const in the same commit, OR the parity test pin at tests/memory_field_count_invariant.rs fails the build.

Multi-agent literal-sweep reference: scanner B finding F-B1.x (Memory shape drift), mirrors the MemoryLinkRelation::COUNT + EXPECTED_CLI_SUBCOMMANDS_* drift-blocker pattern landed in commits 960578cfd + 233e8a247.

pub fn effective_expires_at(&self) -> Option<String>

v0.7.0 #1466 — the expires_at value a fresh store must persist. An explicit value the caller supplied wins; otherwise a non-Long row is stamped with created_at + Tier::default_ttl_secs() so it is reapable by GC (expires_at IS NOT NULL AND expires_at < now). Long rows have no TTL and stay immortal (returns None).

Single SSOT for the tier-default backfill across every store backend (SQLite storage::insert + the insert_with_conflict / insert_if_newer / consolidate siblings, and the Postgres store path). Before this, those paths bound expires_at verbatim, so any internal caller that hand-built a mid/short Memory with expires_at: None created an immortal row GC could never collect. The interval comes from Tier::default_ttl_secs() — no hardcoded TTL literal — so it can never drift from the canonical per-tier TTL. Output mirrors the normal store path (to_rfc3339) so the string comparison in gc() stays monotonic; a malformed created_at falls back to now rather than silently dropping the expiry.

impl Memory

pub fn confidence_tier(&self) -> ConfidenceTier

v0.7.0 Gap 4 (#887) — derived ConfidenceTier for this memory’s confidence value. Stable mapping; see ConfidenceTier::from_confidence for the thresholds.

Trait Implementations

impl Clone for Memory

fn clone(&self) -> Memory

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Memory

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Memory

fn default() -> Self

All-zero / empty defaults. Useful as a base for ad-hoc test fixtures — Memory { id: ..., title: ..., ..Default::default() } — and for #[serde(default)] deserialisation of partial JSON. Tier defaults to Mid to match the API-layer default in CreateMemory.

impl<'de> Deserialize<'de> for Memory

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Memory

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.