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

#[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.

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–500 chars; required.
content	String	REQ1–65 536 bytes (`MAX_CONTENT_SIZE`).
tags	Vec<String>	DEFDefault `[]`; max 32 tags, 64 chars each.
priority	i32	DEFDefault 5; range 1-10.
confidence	f64	DEFDefault 1.0; range 0.0-1.0.
source	String	DEFDefault `"api"`; closed set: user · claude · hook · api · import.
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.

MemoryLinkstructsince v0.1

#[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.

field	type	notes
source_id	String	REQFK to `memories.id`.
target_id	String	REQFK to `memories.id`.
relation	String	REQOne of: `related_to` · `supersedes` · `contradicts` · `derived_from`.
created_at	String	RFC3339; server-stamped.

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–500 chars.
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"`.

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–500 chars 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).

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 /memories/forget and memory_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 70/30 fusion (FTS5 + HNSW); 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.

Response shapes — telemetry

Statsstructsince v0.1

#[derive(Debug, Serialize)]

Response of GET /stats and memory_stats.

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.

TierCountstructsince v0.1

#[derive(Debug, Serialize)]

Embedded in Stats.by_tier.

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

NamespaceCountstructsince v0.1

#[derive(Debug, Serialize)]

Embedded in Stats.by_namespace.

field	type	notes
namespace	String
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(String)reject; the wrapped string surfaces the reason to the caller.

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).

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`.
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.

Constants — wire-format closed sets

MAX_CONTENT_SIZEconst

usize = 65_536 — hard cap on memory content bytes. Validated at write time.

MAX_NAMESPACE_DEPTHconst

usize = 8 — maximum number of /-delimited segments in a namespace path. Sample: alphaone/engineering/platform/team/squad/pod/role/agent.

VALID_SCOPESconst

&[&str] = &["private", "team", "unit", "org", "collective"] — closed set stamped into metadata.scope (Task 1.5). Drives hierarchical visibility matching.

VALID_AGENT_TYPESconst

Closed set of agent types accepted by POST /agents/register. Persisted; extend carefully.

&[ "ai:claude-opus-4.6", "ai:claude-opus-4.7", "ai:codex-5.4", "ai:grok-4.2", "human", "system", ]

AGENTS_NAMESPACEconst

&str = "_agents" — namespace reserved for agent registrations (Task 1.3). Listed via memory_agent_list.

namespace_depth(ns: &str) → usizefn

Free function. Returns the count of /-delimited segments. Flat namespaces return 1; empty returns 0.

namespace_depth("global") // 1 namespace_depth("alphaone/engineering") // 2 namespace_depth("alphaone/engineering/platform") // 3

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