ai-memory · Types — every public struct and enum

Core domain

Tierenumsince v0.1

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] · #[serde(rename_all = "snake_case")]

Memory tier — mirrors human memory systems. Default TTL: Short = 6h, Mid = 7d, Long = none.

Shortworking memory; short-lived contexts; default TTL 6h.

Midsession-spanning facts; default TTL 7d. Default tier for new memories.

Longdurable knowledge; no TTL; subject to governance gates on promote.

// helper API Tier::default_ttl_secs(self) -> Option<i64> Tier::as_str(&self) -> &'static str Tier::from_str(&str) -> Option<Tier>

Memorystructsince v0.1 · grew to 26 fields at v0.7.0

#[derive(Debug, Clone, Serialize, Deserialize)]

The stored record returned by HTTP GET /memories/:id and MCP memory_get. Persisted into the memories table; mirrored to FTS5 + HNSW vector index. 26 fields at v0.7.0 (was 15 at v0.6.x; canonical truth in src/models/memory.rs::Memory, FIELD_COUNT = 26) — adds reflection_depth (Task 1/8 recursive learning), memory_kind (Batman Form-6 vocabulary), entity_id + persona_version (QW-2 persona artefact), citations + source_uri + source_span (Form-4 fact provenance), confidence_source + confidence_signals + confidence_decayed_at (Form-5 calibration), and the version BIGINT (Gap-1 optimistic concurrency, schema v45).

field	type	notes
id	String	REQUUIDv4 primary key.
tier	Tier	REQOne of `short` · `mid` · `long`.
namespace	String	REQHierarchical path; up to 8 segments; default `"global"`.
title	String	REQ1–512 chars (`MAX_TITLE_LEN`); required.
content	String	REQ1–65 536 bytes (`MAX_CONTENT_SIZE`).
tags	Vec<String>	DEFDefault `[]`; max 50 tags (`MAX_TAGS_COUNT`), 128 bytes each (`MAX_TAG_LEN`).
priority	i32	DEFDefault 5; range 1-10.
confidence	f64	DEFDefault 1.0; range 0.0-1.0.
source	String	DEFDefault `"api"`; closed set (`VALID_SOURCES`): user · nhi · claude (deprecated) · hook · api · cli · import · consolidation · system · chaos · notify.
access_count	i64	Server-tracked; bumps on each `memory_get`/`memory_recall` hit.
created_at	String	RFC3339; server-stamped.
updated_at	String	RFC3339; updated on each `memory_update`.
last_accessed_at	Option<String>	OPTRFC3339; `skip_serializing_if = None`.
expires_at	Option<String>	OPTRFC3339; computed from `ttl_secs` or tier default.
metadata	serde_json::Value	DEFDefault `{}`; carries `governance`, `scope`, `agent_id`, taxonomy fields.
reflection_depth	i32	DEFv0.7.0 Task 1/8: recursion depth in the substrate-native reflection tree. `0` for caller-minted (or legacy) rows; positive for reflection-pass outputs. Stored on `memories.reflection_depth` NOT NULL DEFAULT 0 (schema v29 sqlite / v31 postgres).
memory_kind	MemoryKind	DEFv0.7.0 L1-1: Batman Form-6 typed discriminator (`observation` / `reflection` / `persona` / `concept` / `entity` / `claim` / `relation` / `event` / `conversation` / `decision`). Schema v30 column default `'observation'` for pre-v30 rows.
entity_id	Option<String>	OPTv0.7.0 QW-2: persona artefact subject. Populated only when `memory_kind == Persona`. Stored on `memories.entity_id` NULL (schema v36).
persona_version	Option<i32>	OPTv0.7.0 QW-2: monotonic `(entity_id, namespace)` version counter; `PersonaGenerator::generate` bumps. Older rows remain queryable for audit/rollback.
citations	Vec<Citation>	DEFv0.7.0 Form 4 (#757): fact-provenance citation array. Each entry: `{ uri, accessed_at, hash?, span? }`. Schema v38 column; legacy rows default to `'[]'`. Validator: `validate_citation`.
source_uri	Option<String>	OPTv0.7.0 Form 4 (#757): first-class URI pointer (`uri:` / `doc:` / `file:` schemes). Distinct from the role-label `source` column. Schema v38; validator: `validate_source_uri`.
source_span	Option<SourceSpan>	OPTv0.7.0 Form 4 (#757): byte-range into the parent source body, JSON `{start, end}`. Populated by the WT-1-B atomisation writer per atom. Validator: `validate_source_span`.
confidence_source	ConfidenceSource	DEFv0.7.0 Form 5 (#758): typed discriminator naming the provenance of `confidence`. Defaults to `CallerProvided`. Schema v39 sqlite / v38 postgres column default `'caller_provided'`.
confidence_signals	Option<ConfidenceSignals>	OPTv0.7.0 Form 5: JSON snapshot of the signals that produced an auto-derived or calibrated confidence. NULL on legacy rows and on `CallerProvided` writes.
confidence_decayed_at	Option<String>	OPTv0.7.0 Form 5: RFC3339 stamp of the last decay-sweep touch. NULL on legacy / never-decayed rows.
version	i64	DEFv0.7.0 Provenance Gap 1 (#884, schema v45 sqlite): optimistic-concurrency counter. Bumped on every `storage::update`; two writers against the same `expected_version` race; loser receives a typed `CONFLICT` envelope. Legacy rows land at `version = 1` via SQL `DEFAULT` + serde `default_memory_version`.

MemoryLinkstructsince v0.1 · 6 relations at v0.7.0

#[derive(Debug, Clone, Serialize, Deserialize)]

A directed edge between two memories. The KG primitive — every typed-cognition / supersession relationship is one row in memory_links. 6 MemoryLinkRelation variants at v0.7.0 (was 4 at v0.6.x); canonical enum in src/models/link.rs::MemoryLinkRelation.

field	type	notes
source_id	String	REQFK to `memories.id`.
target_id	String	REQFK to `memories.id`.
relation	MemoryLinkRelation	REQOne of: `related_to` · `supersedes` · `contradicts` · `derived_from` · `reflects_on` (v0.7.0 Task 1/8 recursive learning) · `derives_from` (v0.7.0 WT-1-A atomisation atom→parent, schema v36 sqlite / v35 postgres).
created_at	String	RFC3339; server-stamped.
valid_from / valid_until	Option<String>	OPTv0.6.3 temporal validity window; `valid_until = None` means still valid.
observed_by	Option<String>	OPTagent_id of the observer; powers per-agent visibility.
signature	Option<Vec<u8>>	OPTv0.7.0 H4 — Ed25519 per-link attestation bytes.
attest_level	Option<String>	OPTv0.7.0 H4 — `unsigned` · `self_signed` · `peer_attested` · `signed_by_peer` · `daemon_signed`.

Request shapes — write path

CreateMemorystructsince v0.1

#[derive(Debug, Deserialize)]

Body of POST /memories and memory_store. Every field has a server-side default except title + content.

field	type	notes
tier	Tier	DEFDefault `Mid`.
namespace	String	DEFDefault `"global"`.
title	String	REQ1–512 chars (`MAX_TITLE_LEN`).
content	String	REQ1–65 536 bytes.
tags	Vec<String>	DEFDefault `[]`.
priority	i32	DEFDefault 5.
confidence	f64	DEFDefault 1.0.
source	String	DEFDefault `"api"`.
expires_at	Option<String>	OPTRFC3339; explicit override.
ttl_secs	Option<i64>	OPTConvenience: `expires_at = now + ttl_secs`.
metadata	Value	DEFDefault `{}`.
agent_id	Option<String>	OPTAuto-resolved by `identity` when omitted.
scope	Option<String>	OPTOne of `VALID_SCOPES`; default `"private"`.
on_conflict / detect_conflicts / force	Option<String> / Option<bool> / bool	OPTDedup-and-synthesis controls (Form 1): conflict disposition, contradiction probe, duplicate-gate override.
citations / source_uri / source_span	Vec<Citation> / Option<String> / Option<SourceSpan>	OPTv0.7.0 Form-4 fact provenance (#757).
kind	Option<String>	OPTv0.7.0 Batman Form-6 `memory_kind` discriminator.
signature	Option<String>	OPTv0.7.0 Layer-3 — caller-presented Ed25519 write attestation (verified against the agent's bound key).
created_at	Option<String>	OPTRFC3339 backdating for imports; server-stamped when omitted.

UpdateMemorystructsince v0.1

#[derive(Debug, Deserialize)]

Body of PUT /memories/:id and memory_update. Every field is optional — only the present fields are mutated; the rest are preserved.

field	type	notes
title	Option<String>	OPT1–512 chars (`MAX_TITLE_LEN`) when set.
content	Option<String>	OPT1–65 536 bytes when set.
tier	Option<Tier>	OPTPromoting Mid→Long passes through governance.
namespace	Option<String>	OPTRe-namespacing; depth ≤ 8.
tags	Option<Vec<String>>	OPTReplaces tag set entirely (not merged).
priority	Option<i32>	OPT1-10 range.
confidence	Option<f64>	OPT0.0-1.0 range.
expires_at	Option<String>	OPTRFC3339.
metadata	Option<Value>	OPTReplaces metadata wholesale (not merged); `metadata.agent_id` is preserved.
source_uri	Option<String>	OPTv0.7.0 Form-4 provenance pointer update.
agent_id	Option<String>	OPTCaller identity for owner-write checks; the stored row's `metadata.agent_id` remains immutable.

LinkBodystructsince v0.1

#[derive(Debug, Deserialize)]

Body of POST /links and memory_link. Creates a directed edge in the KG.

field	type	notes
source_id	String	REQUUID; must exist in `memories`.
target_id	String	REQUUID; must exist in `memories`.
relation	String	DEFDefault `"related_to"`.

ForgetQuerystructsince v0.1

#[derive(Debug, Deserialize)]

Body of POST /api/v1/forget and memory_forget (v0.7.0: route registered at /api/v1/forget, not /api/v1/memories/forget). Pattern-based delete; archives matched memories rather than hard-deleting.

field	type	notes
namespace	Option<String>	OPTRestricts the sweep to a namespace.
pattern	Option<String>	OPTFTS5 pattern; matches title+content.
tier	Option<Tier>	OPTRestricts to one tier.

Request shapes — read path

SearchQuerystructsince v0.1 · agent fields v0.6

#[derive(Debug, Deserialize)]

Query string for GET /search and body for memory_search. FTS5-backed.

field	type	notes
q	String	REQFTS5 expression; supports `AND`/`OR`/`NEAR`/`"phrase"`.
namespace	Option<String>	OPTRestricts to one namespace prefix.
tier	Option<Tier>	OPT
limit	Option<usize>	DEFDefault 20.
min_priority	Option<i32>	OPT
since / until	Option<String>	OPTRFC3339 created_at window.
tags	Option<String>	OPTComma-separated; AND semantics.
agent_id	Option<String>	OPTFilters by `metadata.agent_id` exact.
as_agent	Option<String>	OPTQuerying agent's namespace position; drives scope filtering.

ListQuerystructsince v0.1

#[derive(Debug, Deserialize)]

Query string for GET /memories and memory_list. Pagination + filter by namespace/tier/tags.

field	type	notes
namespace	Option<String>	OPT
tier	Option<Tier>	OPT
limit	Option<usize>	DEFDefault 20.
offset	Option<usize>	OPT
min_priority	Option<i32>	OPT
since / until	Option<String>	OPTRFC3339 window.
tags	Option<String>	OPTComma-separated.
agent_id	Option<String>	OPT

RecallQuerystructsince v0.1 · budget_tokens Task 1.11

#[derive(Debug, Deserialize)]

Query string for GET /recall. Hybrid FTS5 + HNSW fusion with adaptive blending — semantic weight 0.50 (short content) → 0.15 (long content), cosine gate RECALL_COSINE_GATE = 0.2; optional context-budget pruning.

field	type	notes
context	Option<String>	OPTFree-form context to retrieve against.
namespace	Option<String>	OPT
limit	Option<usize>	DEFDefault 10.
tags	Option<String>	OPT
since / until	Option<String>	OPT
as_agent	Option<String>	OPTVisibility filter (Task 1.5).
budget_tokens	Option<usize>	OPTCap on cumulative tokens; top-N items that fit (Task 1.11).

RecallBodystructsince v0.1

#[derive(Debug, Deserialize)]

JSON body of POST /recall and memory_recall. Same shape as RecallQuery but context is required.

field	type	notes
context	String	REQ
namespace	Option<String>	OPT
limit	Option<usize>	DEFDefault 10.
tags / since / until / as_agent / budget_tokens	…	Same as RecallQuery.

field	type	notes
total	usize	Count of non-archived memories.
by_tier	Vec<TierCount>	3 rows: short / mid / long.
by_namespace	Vec<NamespaceCount>	One row per distinct namespace.
expiring_soon	usize	Count expiring within 24h.
links_count	usize	Total `memory_links` rows.
db_size_bytes	u64	SQLite file size.

field	type	notes
tier	String	`"short"` · `"mid"` · `"long"`
count	usize

Governance — Task 1.8 / 1.9 / 1.10

GovernanceDecisionenumsince Task 1.9 (v0.6)

#[derive(Debug, Clone, PartialEq, Eq)]

The outcome of a governance check. Callers MAY execute on Allow, MUST reject on Deny, and SHOULD queue + return the pending_id on Pending.

Allowproceed with the action.

Deny(GovernanceRefusal)reject; the typed envelope carries the canonical wire message (Display reads "<action> denied by governance: <reason>") plus the structured policy context (denied_level, namespace, owner, agent_id, reason). Wire shape byte-identical to the pre-#963 Deny(String) envelope; pattern-match consumers read refusal.reason for the bare string.

Pending(String)queued for approval; the caller receives the new pending_id.

GovernedActionenumsince Task 1.9 (v0.6)

#[derive(Debug, Clone, Copy, PartialEq, Eq)]

Actions that governance gates. Stored as the action_type column in pending_actions; discriminator for enforcement calls.

Storecreating a new memory in a governed namespace.

Deletedeleting an existing memory.

Promotetier promotion (Mid → Long).

Reflectv0.7.0 L1-8 — memory_reflect approval gate; queued when the proposed reflection depth exceeds require_approval_above_depth.

GovernanceLevelenumsince Task 1.8 (v0.6)

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] · #[serde(rename_all = "snake_case")]

Who is permitted to perform a governed action. Stored in a namespace standard's metadata.governance.

Anyno gate; any caller succeeds.

Registeredcaller must be a registered agent (_agents namespace).

Owneronly the memory's metadata.agent_id owner may perform the action.

Approverequires explicit approval by an ApproverType.

ApproverTypeenumsince Task 1.10 (v0.6)

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] · #[serde(rename_all = "snake_case")]

Who approves actions gated by GovernanceLevel::Approve. Externally-tagged.

Humanserialized as "human"; interactive or out-of-band approval.

Agent(String)serialized as {"agent": "alice"}; specific registered agent must approve.

Consensus(u32)serialized as {"consensus": 3}; consensus of N approvers required.

GovernancePolicystructsince Task 1.8 (v0.6)

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]

Attached to a namespace's standard memory at metadata.governance. Default policy: { write: Any, promote: Any, delete: Owner, approver: Human }. v0.6.2 (S34) made promote/delete/approver tolerant of missing fields for partial-policy payloads.

field	type	notes
write	GovernanceLevel	REQRequired — core knob a policy is setting.
promote	GovernanceLevel	DEFDefault `Any`.
delete	GovernanceLevel	DEFDefault `Owner`.
approver	ApproverType	DEFDefault `Human`.

// helper API GovernancePolicy::from_metadata(&Value) -> Option<Result<Self, _>> GovernancePolicy::default() // { write: Any, promote: Any, delete: Owner, approver: Human }

Approvalstructsince Task 1.10 (v0.6)

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]

A single approval vote on a consensus-gated pending action.

field	type	notes
agent_id	String	Approving agent's id.
approved_at	String	RFC3339.

PendingActionstructsince Task 1.9 (v0.6)

#[derive(Debug, Clone, Serialize, Deserialize)]

Row returned by db::list_pending_actions. Mirrors the pending_actions table.

field	type	notes
id	String	UUID.
action_type	String	`store` · `delete` · `promote` · `reflect` (v0.7.0).
memory_id	Option<String>	Set for delete/promote; null for pending stores.
namespace	String
payload	Value	Action-shaped JSON for replay.
requested_by	String	agent_id of requester.
requested_at	String	RFC3339.
status	String	`pending` · `approved` · `rejected`.
decided_by	Option<String>	OPT
decided_at	Option<String>	OPT
approvals	Vec<Approval>	Consensus vote log (Task 1.10); empty for Human/Agent paths.

PendingDecisionstructsince v0.6.2 S34

#[derive(Debug, Clone, Serialize, Deserialize)]

A pending-action decision (approve/reject) propagated to peers so callers on any peer see consistent state. Shipped as additive sync_push.pending_decisions field; peers apply via db::decide_pending_action.

field	type	notes
id	String	pending_action UUID.
approved	bool	true → approve; false → reject.
decider	String	agent_id of decider.

Federation — issue #224 / agent registry

NamespaceMetaEntrystructsince v0.6.2 S35

#[derive(Debug, Clone, Serialize, Deserialize)]

A namespace-standard metadata row propagated to peers. Without this, a peer sees the standard memory (fanned via broadcast_store_quorum) but not the (namespace, standard_id, parent_namespace) tuple, so inheritance-chain walks fall back to auto_detect_parent.

field	type	notes
namespace	String
standard_id	String	UUID of the standard memory.
parent_namespace	Option<String>	OPT
updated_at	String	RFC3339.

RegisterAgentBodystructsince Task 1.3 (v0.6)

#[derive(Debug, Deserialize)]

Body of POST /agents/register. Persists into the _agents namespace.

field	type	notes
agent_id	String	REQStable identifier; max 64 chars.
agent_type	String	REQOne of `VALID_AGENT_TYPES`.
capabilities	Option<Vec<String>>	OPTFree-form capability tags.

AgentRegistrationstructsince Task 1.3 (v0.6)

#[derive(Debug, Serialize)]

Response to POST /agents/register and rows in GET /agents.

field	type	notes
agent_id	String
agent_type	String
capabilities	Vec<String>	Empty when none registered.
registered_at	String	RFC3339.
last_seen_at	String	RFC3339; bumps on agent activity.

VectorClockstructsince v0.6.0 — Phase 3 foundation (#224)

#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq, Eq)]

Tracks the latest updated_at this peer has seen from each known remote. Populated lazily on /sync/push and /sync/since. CRDT-lite merge semantics arrive in Task 3a.1; the foundation ships the wire format so adding semantics later does not force a schema migration.

field	type	notes
entries	BTreeMap<String, String>	DEFpeer agent_id → latest RFC3339 updated_at.

// helper API VectorClock::observe(&mut self, peer_id: &str, at: &str) // monotonic: never overwrite newer VectorClock::latest_from(&self, peer_id: &str) -> Option<&str>

SyncStateEntrystructsince v0.6.0 — Phase 3 foundation (#224)

#[derive(Debug, Clone, Serialize, Deserialize)]

One row of the sync_state table serialized for diagnostic / API responses. Consumed by Task 3b.2 sync diagnostics.

field	type	notes
agent_id	String	Local agent's id.
peer_id	String	Remote peer's id.
last_seen_at	String	RFC3339; latest `updated_at` seen on receive.
last_pulled_at	String	RFC3339; cursor advanced on send.

The types, end to end.

All 27 types, indexed.

Core domain

Request shapes — write path

Request shapes — read path

Response shapes — telemetry

Governance — Task 1.8 / 1.9 / 1.10

Federation — issue #224 / agent registry

Constants — wire-format closed sets