Phase P6 — outcome of applying a token budget to a ranked recall
list. Carries everything mcp::handle_recall needs to populate the
new RecallMeta block (budget_tokens_used, budget_tokens_remaining,
memories_dropped, budget_overflow).
Maximum sync-clock skew in seconds across the sync_state table —
the largest gap between last_pulled_at (when this peer last heard
from a peer) and last_seen_at (the peer’s own updated_at advance).
Returns Ok(None) when sync_state is empty or the columns are
missing on a pre-T3 schema.
v0.6.3.1 P2 (G4): error returned by set_embedding when a write would
introduce a new embedding dimensionality into a namespace that has already
established one via an earlier write. Surfaced as a typed error so the
MCP/HTTP handlers can map it to a 409 Conflict rather than letting cosine
silently return 0.0 on every subsequent recall.
Outcome of invalidate_link (Pillar 2 / Stream C —
memory_kg_invalidate). valid_until is the timestamp now stored on
the link; previous_valid_until is the prior value, or None if
this was the first invalidation. Callers can use the prior value to
distinguish a fresh supersession from an idempotent retry.
Default cosine similarity threshold for declaring a candidate a
duplicate. Empirically tuned for MiniLM-L6-v2 (the local embedder):
near-paraphrases of the same memory tend to land at 0.88+, while
loosely related content sits well below 0.85. Callers can override.
Hard floor for duplicate-check threshold. Below this, anything can match
random unrelated content — refuse to honor the lookup so callers don’t
silently get garbage merge suggestions.
Default cap on rows returned by kg_query when the caller does not
specify one (Pillar 2 / Stream C). Mirrors kg_timeline’s default so
the two traversal tools behave consistently for agents driving them.
Maximum traversal depth supported by kg_query. The recursive-CTE
implementation enforces an explicit ceiling so a crafted call cannot
run an unbounded traversal; the charter (v0.6.3-grand-slam.md
§ Performance Budgets) sets the published budget at depth ≤ 5.
Default cap on rows returned by kg_timeline when the caller does
not specify one (Pillar 2 / Stream C). Sized to fit a reasonable
agent context window without paging — callers needing more should
pass an explicit limit.
Phase P6 (R1) — context-budget greedy fill. Iterates over scored
candidates in rank order; stops at the first memory whose inclusion
would exceed the budget — UNLESS the output is still empty, in
which case the highest-ranked memory is returned anyway with
budget_overflow = true. This preserves the R1 guarantee that a
successful recall always returns at least one result when any
matched, even if the user supplied an unrealistically tight budget.
Move a memory from memories to archived_memories. Used by the
HTTP /api/v1/archive explicit-archive endpoint (S29) and by
sync_push when a peer pushes an archives: [id] record.
Build the namespace inheritance chain in top-down order
(["*", root, ..., leaf]). Mirrors and replaces the historical
mcp::build_namespace_chain so non-MCP call sites (db-layer
governance enforcement, HTTP handlers, future hook pipelines) can
reuse the same walk.
v0.6.3 (capabilities schema v2): count namespace standards whose
metadata.governance is non-null. A “rule” here means a namespace
has an explicit governance policy attached to its standard memory.
The count is a transparent passthrough — the full permission system
arrives in v0.7 (arch-enhancement-spec §3).
Phase P6 — token cost of a memory’s content only (not title), per
the R1 spec which budgets against the LLM context window. Title and
metadata are caller-side ornament; content is what gets stuffed
into the prompt.
v0.6.3 (capabilities schema v2): count pending_actions rows whose
status matches the predicate. Used by handle_capabilities to
surface live approval queue depth.
v0.6.3 (capabilities schema v2): count rows in the subscriptions
table. Used by handle_capabilities as a proxy for “registered
hooks” — the hook pipeline itself is v0.7 Bucket 0 work.
Phase P6 (R1) — count tokens in text using OpenAI’s cl100k_base
BPE encoding. This is the de-facto standard for Claude / GPT context
budgeting and is shipped with tiktoken-rs (the BPE table is embedded
in the crate, ~1.7 MB, so the count is offline-deterministic across
all hosts). The encoder is built lazily and cached process-wide via
OnceLock — cl100k_base() itself parses the embedded table on every
call, which adds a few ms; we pay that cost once.
Mark a pending action as approved or rejected. Returns true on status
transition. Does NOT execute the action itself — the caller replays
the payload on approval (the db layer doesn’t know how to execute
cross-interface write semantics).
Count rows whose stored embedding_dim does not match what the BLOB
contains (or where the column is missing while a BLOB exists). Surfaced
in Stats::dim_violations and consumed by P7 doctor.
Count rows whose embedding_dim (post-P2) does not match the modal
dim within their namespace. On pre-P2 schemas the embedding_dim
column doesn’t exist; the function returns Ok(None) so the doctor
can render “not yet observed (pre-P2 schema)”.
Count of namespaces that have a standard registered with a non-null
metadata.governance block, and the count without (just a standard
memory but no policy attached).
Distribution of the parent_namespace chain depth across
namespace_meta rows. Returns a Vec where index i is the count of
namespaces with chain depth i (depth 0 = no parent).
Age in seconds of the oldest pending row in pending_actions, or
None if the queue is empty (or the column is unparseable). The
doctor uses this to flag a backlog older than 24h as critical.
Sum of subscriptions.dispatch_count and subscriptions.failure_count
across all rows. Returns (dispatched, failed). Used by the doctor to
estimate webhook delivery success rate.
Enforce governance for a GovernedAction. On GovernanceDecision::Pending,
a row is inserted into pending_actions and the returned pending_id is
embedded in the decision.
Phase P6 — kept for backward compatibility with the Task 1.11 byte-
heuristic surface. New code should use count_memory_tokens. The
returned value is now BPE-accurate (cl100k_base) rather than the
prior len/4 estimate, so callers reading this through the public
API get the more accurate value automatically.
Task 1.10 — Execute an approved pending action’s payload. Callers invoke
this after approve_with_approver_type returns Approved. Returns the
affected memory id (new id for store, existing id for delete/promote).
v0.6.3.1 P2 (G6) — quick existence check for (title, namespace). Used by
on_conflict='error' callers to short-circuit before the full upsert
machinery runs. Returns the existing row id if there is one.
Look up a memory by ID prefix. Returns the memory if exactly one match is found.
Returns Ok(None) if no matches. Returns an error if the prefix is ambiguous (>1 match).
v0.6.2 (S35): read the full namespace_meta row for a namespace so the
caller can fan it out to peers. Returns None when no standard is set.
Mirrors the (namespace, standard_id, parent_namespace, updated_at)
tuple used by set_namespace_standard.
Insert with timestamp-aware conflict resolution for sync.
Only overwrites if the incoming memory is newer (by updated_at,
tiebroken by memory.id for a total order across peers —
ultrareview #344, #345).
Mark a KG link as superseded by setting its valid_until column
(Pillar 2 / Stream C — memory_kg_invalidate). Returns Ok(None)
when the (source_id, target_id, relation) triple does not match an
existing link. The supplied valid_until defaults to the current
wall-clock time in RFC3339 form when omitted; callers needing
historical or future supersession can pass an explicit value.
Outbound KG traversal from a source memory (Pillar 2 / Stream C —
memory_kg_query). Returns one row per link reachable within
max_depth hops, filtered by:
Ordered fact timeline for an entity (Pillar 2 / Stream C —
memory_kg_timeline). Returns outbound assertions from
source_id, ordered by valid_from ASC and tie-broken by
created_at ASC for deterministic display.
Return memories whose updated_at > since, ordered by updated_at
ascending. Used by GET /api/v1/sync/since to stream incremental
updates to a peer. Caps at limit rows (caller-chosen pagination).
Task 1.12 — proximity boost applied to a memory’s score based on its
depth distance from the queried agent namespace. Uses the formula
1 / (1 + depth_distance * 0.3) per spec. Distance 0 = full strength
(1.0), each step up the hierarchy dampens linearly.
Hybrid recall — FTS5 keyword search + semantic cosine similarity.
Returns memories ranked by a blended score of keyword and semantic relevance.
When an HNSW vector_index is provided, uses approximate nearest-neighbor
search instead of scanning all embeddings linearly.
v0.6.3.1 (P3): hybrid recall preserving the existing 2-tuple return
shape for HTTP / CLI / bench callers. Delegates to
recall_hybrid_with_telemetry and discards the telemetry. Kept so
the dozen-plus call sites need no churn for a feature only MCP
handle_recall consumes.
v0.6.3.1 (P3 + P6): hybrid recall reporting per-stage candidate counts,
the average semantic blend weight, and the full budget outcome. MCP
handle_recall uses the telemetry to populate the meta block (closes
audit gaps G2/G8/G11) and the BudgetOutcome to populate R1 budget fields.
Recall — fuzzy OR search + touch + auto-promote + TTL extension.
Task 1.11: after ranking, applies optional budget_tokens cap.
Phase P6: returns the full BudgetOutcome (tokens_used,
tokens_remaining, memories_dropped, budget_overflow) instead of just
the prior bare tokens_used. Callers that only need tokens_used
read outcome.tokens_used.
v0.6.3.1 (P3): keyword-only recall with retrieval-stage telemetry.
Record a capability-expansion attempt. Used by
handle_capabilities_family after the allowlist decision is made.
Records BOTH grant and deny outcomes so operators can see attempted
access patterns even when the gate refused.
Look up this peer’s last-push watermark for peer_id. Returns None
if we’ve never successfully pushed to them (foundation-era rows also
return None because the column was added in schema v12).
Record the latest updated_at this local agent has observed from peer_id.
Monotonic by timestamp — older writes do not overwrite newer ones.
Lazily creates the row on first observation.
v0.6.2 (S34): upsert a pending_actions row from a canonical PendingAction
struct — used by sync_push to apply a peer-originated pending row so
governance state is cluster-consistent. Preserves approvals and
decision fields verbatim so re-plays converge. Uses INSERT ... ON CONFLICT(id) DO UPDATE because the originator’s id is stable across
peers (unlike queue_pending_action which mints a fresh UUID per
queue call).