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.
Task 1.11 — truncate a scored recall list to fit within an optional
token budget. Iterates in rank order; stops at the first memory whose
inclusion would exceed the budget. Returns (truncated, tokens_used).
When budget_tokens is None the list is returned untouched, still
with an accurate tokens_used tally so callers can surface it in
response metadata.
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.
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).
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.
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).
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.
Task 1.11 — rough token estimate for a memory. Uses the “~4 chars per
token” heuristic on title + content. Deliberately byte-length-based:
fast, deterministic, and correct enough for budget gating.
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).
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.
Resolve the explicit governance policy for a namespace from its standard
memory’s metadata.governance. Returns None when no policy is set —
enforcement is opt-in, so namespaces without explicit policy skip
every governance check (historical behavior preserved). The “default
policy” ({ write: Any, promote: Any, delete: Owner, approver: Human })
is surfaced by get_standard for display purposes only; it does not
gate operations.
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).