io.github.CueCrux/vaultcrux-memory-core

query_memory

Search the user's conversation memory. Returns ranked results with content, source timestamps, and confidence scores. For KNOWLEDGE UPDATE questions ('current', 'now', 'most recent'): make two calls — one with scoring_profile='balanced' and one with scoring_profile='recency' — then use the value from the most recent source_timestamp. For COUNTING questions ('how many', 'total'): results may not be exhaustive — search with varied terms and enumerate explicitly before counting. If all results score below 0.3, reformulate with synonyms or specific entity names from the question.

list_topics

List VaultCrux Memory Core topic groups with freshness metadata.

get_versioned_snapshot

Get the latest versioned snapshot for a VaultCrux Memory Core topic at an optional timestamp.

get_audit_trail

Read VaultCrux Memory Core import audit history and linked receipt hashes for a topic.

check_claim

Verify a proposed answer against memory before committing to it. Pass your candidate answer as claim_text. Returns supporting and contradicting evidence with confidence scores. Use as a pre-answer gate: if contradicting evidence exists or support is weak, investigate further before answering.

memory_claim_check

agent-ux-04 paid-tier source-linked claim check. Same upstream API as check_claim, plus three additional gates: (1) token_budget is REQUIRED — caps total response size by per-match token estimate (QC.2); (2) reserved-prefix topics (__agent::*, __ops::*, __bootstrap__::*) are stripped from matches (T.1); (3) per-match audit_links carry an offline-verify CLI hint (`corecruxctl receipts verify <id>`) so the host IDE can render a one-click verify badge per supporting / contradicting memory. Gated by FEATURE_MEMORY_CLAIM_CHECK=1 (default off).

get_freshness_report

Check how recent the stored knowledge is across topics. Returns staleness indicators per topic. Use this when answering time-sensitive questions to verify your evidence isn't outdated. Topics with stale data may have been superseded by newer conversations not yet retrieved.

memory_freshness_report

Aligned with the Crux free-tier `memory_freshness` surface. Same backend as get_freshness_report with a token_budget knob (QC.2). Gated by FEATURE_MEMORY_FRESHNESS_REPORT=1.

get_contradictions

Find conflicting information across the user's memory. Returns groups of artefacts that contradict each other on the same topic. Use after gathering evidence for an answer — if your evidence sources disagree, this reveals which version is correct (typically the most recent).

get_decision_context

Retrieve agent session decisions from the CoreCrux Decision Plane, including decision IDs, outcomes, and cursor positions.

get_causal_chain

Get the causal chain graph for a specific decision, showing how decisions, actions, and supersessions relate.

reconstruct_knowledge_state

Reconstruct what the system knew at a specific point in time. Returns both current and superseded artefacts as of that timestamp. Use for temporal reasoning: 'what was true in January?' vs 'what is true now?' Compare two calls at different timestamps to see what changed.

get_correction_chain

Trace how a fact or decision evolved over time. When you find a value (e.g. 'Rachel moved to Chicago'), call this to check if a more recent session supersedes it. Returns the full version chain with timestamps. ALWAYS use for 'current', 'now', 'most recent' questions before answering with the first value you find.

get_decisions_on_stale_context

Find decisions in a session that may have been made on stale memory context.

record_decision_context

Record a decision context event in the CoreCrux Decision Plane. This is a mutation operation.

get_pressure_status

Get Engine knowledge pressure status for the tenant — indicates whether knowledge bases are under update pressure.

No parameters.

get_active_alerts

Get active watch alerts across all watches for the tenant from the last 7 days.

get_signals_feed

Get the signals feed for the tenant from the WebCrux platform.

declare_constraint

Declare an organisational constraint (boundary, relationship, policy, or context flag) that agents must respect. This is a mutation operation.

update_constraint

Update an existing constraint. Content changes create a new version (append-only). Status-only changes update in place. This is a mutation operation.

get_constraints

List active organisational constraints, optionally filtered by type, status, or team.

check_constraints

Check an action against all active constraints. Returns matched constraints, match types (structural/semantic), and a combined verdict (pass/warn/block).

verify_before_acting

Pre-action and pre-conclusion verification gate. Checks Shield policy, org constraints, watch alerts, knowledge pressure, and memory freshness. Returns a combined verdict: proceed, warn, require_approval, or block. Use before committing to an answer when the stakes are high or when your evidence is thin — it catches constraint conflicts and stale-context risks that query_memory alone won't surface.

suggest_constraint

Propose an organisational constraint discovered during work for human review. Agents can suggest boundaries, policies, or context flags they discover — humans decide whether to promote them to active constraints. Low barrier (1 credit); authority gate is on promotion, not suggestion.

checkpoint_decision_state

Create a receipted snapshot of your current decision state during a long-running session. Records decisions made, assumptions in effect, and open questions. Enables resumption by the same or different agent from the last checkpoint rather than replaying from zero.

get_checkpoints

Retrieve decision checkpoints for a session. Returns the linked list of checkpoints in reverse chronological order. Use this to resume work from a prior checkpoint after session failure or handoff.

assess_coverage

Question-scoped readiness check. Given a task description, returns what the system knows and doesn't know: artefact counts by domain, freshness stats, and knowledge gaps. Use BEFORE answering to decide if you should search more or commit. If coverage is thin on the question's topic, search with different terms before answering. Addresses 'do I have enough evidence to answer this?'

get_relevant_context

Task-scoped context briefing. Returns a prioritised context payload shaped by your task description, ranked by risk-if-missed. Constraints and alerts rank above general knowledge. Use at the START of reasoning about a question to get the system's best assessment of what's relevant. Complements query_memory: this gives breadth, query_memory gives depth.

escalate_with_context

Contextual escalation — packages your full reasoning state (evidence gathered, options considered, recommended action) and routes to a human for review. Preserves work so the human responds with full context, not from scratch. Use when you hit genuine uncertainty that the system cannot evaluate.

get_platform_capabilities

Machine-queryable manifest of all available MemoryCrux tools, required trust tiers, and credit costs. Returns structured data for agent-to-service evaluation without reading documentation. Free (0 credits) at all tiers — discovery drives adoption.

admit_character_kernel_entry

Privileged curation tool for MemoryCrux v2.4 AgentCharacterKernel. Adds or supersedes an invariant expected behaviour tuple for an agent; operator-class API credentials are required by the API.

get_character_kernel

Return active AgentCharacterKernel entries for an agent, including expected behaviour tuples and sufficiency bands used by drift checks.

assess_character_drift

Run the on-demand AgentCharacterKernel distribution-layer sweep for an agent and return emitted drift events for the requested window.

issue_passport

Issue an agent passport with identity, sponsor lineage, and a 5-tier reputation system. Stored as a BLAKE3-hashed fact. Tiers: unverified (0), basic (10+ receipts), established (100+), trusted (500+), elite (2000+). Required before sync operations. Idempotent: calling twice returns the existing passport.

get_passport

Return the calling agent's passport with current reputation tier and receipt count. Recalculates receipt count on every call and auto-upgrades the tier when new thresholds are met (basic 10+, established 100+, trusted 500+, elite 2000+). Includes a hint for the next tier upgrade.

No parameters.

sync_pull

Pull enriched facts from a remote memory instance into the local fact store. Uses cursor-based pagination and resumes from the last pull cursor. Pulled facts carry a sync:source_receipt so they are never pushed back. Requires an agent passport with at least basic tier (10+ receipts).

sync_push

Push local facts to a remote memory instance. Private facts and sensitive entity prefixes (finance:, health:, credentials:, etc.) are never pushed. Call without confirm=true for a preview. Requires established passport tier (100+ receipts).

submit_skill

Submit a procedural workflow skill discovered during work. Pro+ private skills auto-approve; Starter skills enter a review queue. ATAM injection scanning runs automatically — quarantined skills cannot be promoted. Returns submission ID, approval status, and scan results.

promote_skill

Promote a reviewed skill submission to Engine artifacts, making it retrievable via get_relevant_context. Only pending_review skills can be promoted. Returns the promoted artifact ID.

dismiss_skill

Dismiss a pending or quarantined skill submission. The skill is marked as dismissed and will not be promoted.

retract_skill

Retract a previously promoted skill. Sets the Engine artifact's living status to 'retracted', removing it from future retrieval results. Use when a skill is found to be incorrect or outdated.

session_debrief

Structured session-end reflection. Routes discoveries to appropriate capture tools (suggest_constraint, submit_skill, flag_for_review). Produces a receipted debrief record. Call before closing any session longer than 10 minutes.

get_domain_changelog

Cross-artefact-type changelog for specified domains since a given timestamp. Returns constraints added/updated, knowledge changes, decisions recorded, and alerts raised/resolved. Use at session start to learn what changed in your domain since your last session.

get_my_tasks

Read-through to PlanCrux task graph. Returns tasks assigned to or relevant to the calling agent, filtered by status and priority. Includes stage progress, blockers, and linked MemoryCrux artefact counts.

get_task_context

Full task context: task metadata, stages with status and weight, active blockers, linked artefacts (constraints, decisions, knowledge), recent log entries, and pinned master plan version. Assembles the full picture from PlanCrux and MemoryCrux.

log_progress

Receipted write-through to PlanCrux's log endpoint. Appends a structured log entry to a task with optional evidence references and stage binding. Cannot change task or stage status (human-only), but records work done, findings, and blockers encountered.

register_external_service

Register an external service and store its credential via Vault Transit. Human-only (admin or owner role). The credential is encrypted immediately on receipt and never stored in plaintext. Returns the service registration record without the credential.

request_credentialed_call

Proxied external API call with server-side credential injection. VaultCrux retrieves the credential from Vault Transit, injects it per the service's auth template, makes the call, and returns the response. The credential never appears in your context window. Request and response are receipted and audit-logged.

list_external_services

List registered external services available to the calling agent. Returns service IDs, display names, allowed methods/paths, and rate limit state. Does not return credentials or credential references.

enumerate_memory_facts

Deterministic fact-table extraction for aggregation questions and curated ESI lookups. Returns a structured row set (subject, predicate, object, date, session_id, confidence) instead of prose. Use this for 'how many', 'total', 'list all' questions — count the rows instead of hoping the LLM enumerates correctly. For curated ESI facts, pass `predicate` and optional `projectionVersionTag`; then `query` is optional and the server performs an exact predicate lookup without text search. Includes missing_dimensions to flag what might not have been found. Pass `mode: "aggregation"` (with `FEATURE_AGGREGATION_PREDICATE_EXPANSION=true` on the server) to enable: synonym expansion for pickup/return/acquire verbs, category-broadened counts from entity_categories, entity_type filters (expected_entity_types), and per-object dedup (dedup_by_object).

build_timeline

Deterministic timeline constructor for temporal reasoning. Finds all dated events matching your query, normalizes dates, and returns them sorted chronologically. Use for 'what order', 'before/after', 'earliest/latest' questions. Returns unresolved events (found but no date) separately.

expand_hit_context

Session-neighborhood expansion around promising retrieval hits. When you find a relevant chunk but the specific fact (name, date, amount) is in a nearby turn, use this to fetch ±N turns from the same session. Recovers facts like 'my parents', '$6', or 'Disney+' that are near but not in the retrieved chunk.

assess_answerability

Sufficiency gate — can this question be answered with current evidence? Pass your query and optionally the fact rows you have gathered. Returns: answerable (yes/no), missing fields, contradictory fields, recommended next tool, and confidence. Use this BEFORE forcing a best-guess answer. If answerable=false, it is better to say 'insufficient evidence' than to guess wrong.

derive_from_facts

Safe math and selection over a fact row set. Operations: sum, count, difference, max, min, latest, earliest. Pass the rows from enumerate_memory_facts and get a deterministic result with a computation trace. Removes arithmetic slop from totals, comparisons, and 'which is highest' questions.

extract_facts_from_sessions

Scan the tenant's seeded sessions with rule-based extractors (money, counts, dates, project-role, acquire, version-chain) and emit structured facts to the projection stream so they become queryable via enumerate_memory_facts. Use when enumerate_memory_facts returns insufficient rows for aggregation, version-chain, or money questions and you suspect the fact exists but was under-predicated at ingest. Idempotent — safe to re-run (duplicate fact_hashes skipped unless overwrite_existing=true). Profile 'comprehensive' runs all rule families; narrower profiles ('money', 'counts', 'dates', 'version_chains') target a single family. Returns facts_added + rules_matched + receipt_id. Gated by FACT_EXTRACTION_MODE on the server.

compare_versions

Temporal-ordered view of all values recorded for an (entity, predicate) pair, with the most-recent-before-as_of flagged as current. Use this when the agent sees contradictory facts ('Rachel moved to Chicago' AND 'Rachel moved to the suburbs') and needs to know which is current. Example calls: {entity:'user', predicate:'mortgage_amount'} returns every mortgage figure you've recorded, current first. {entity:'user', predicate:'family_trip_destination'} resolves the latest family-trip destination across sessions. {entity:'user', predicate:'previous_occupation'} returns the user's earlier roles when they changed jobs. Returns current_value directly plus has_multiple_versions so the caller can signal uncertainty, and may also include a cached narrative summary when FEATURE_CAUSAL_NARRATIVES is enabled.

get_session_dossiers

Retrieve pre-synthesized per-session memory dossiers (typed: experience | fact | preference; with When/Involving/To-purpose metadata). Use for multi-session or preference-style questions where stitching across conversations is the bottleneck — the dossier already summarises each session's key events. Two modes: mode='search' with a query (BM25-ish ranking over summary+purpose, optional type_filter), or mode='list' returns the tenant's most-recent dossiers chronologically. Tenants without FEATURE_SESSION_DOSSIERS enabled return an empty list (no error).

investigate_question

Composite server-side investigation tool. Pass a question and the server automatically: (1) detects intent (aggregation/temporal/ordering/knowledge-update/recall), (2) queries the entity index for structured facts, (3) builds a timeline for temporal questions, (4) retrieves memory chunks with the right scoring profile, (5) expands context around sparse hits, (6) derives counts/sums for aggregation, (7) assesses answerability, and (8) returns a recommendation. Use this as your FIRST tool for any non-trivial question — it does the multi-step investigation that would otherwise take 4-6 individual tool calls. The response includes structured facts, timeline, retrieved chunks, derived results, answerability assessment, and a recommendation for how to answer.

submit_correction

Submit a correction for a knowledge item with evidence chain. The original item is never mutated — a versioned enrichment layer is created.

get_enrichment_status

Check the status of submitted corrections (pending, corroborated, merged, retracted, expired).

get_knowledge_gaps

List gap receipts (coverage + enumeration) for the tenant, filterable by topic and recency.

fill_gap

Fill a previously reported gap with new knowledge. Gap must have been reported by a different tenant for cross-tenant credit.

declare_available_models

Declare which models are available in this session for orchestration routing. Called once at session start.

get_escalation_recommendation

Get model routing recommendation for a query based on composite confidence and difficulty profile. Returns escalation advice: none, recommended, or required.

get_incident_context

What went wrong last time we touched this module? Returns past incidents, deploy failures, gotchas, and active constraints for a module or system. Use BEFORE modifying infrastructure code, deploy scripts, or any module with a history of fragility. Surfaces the kind of tribal knowledge that prevents repeat failures — Docker bind mount traps, Vault agent write patterns, stale dist/ artifacts, port conflicts, and similar operational landmines.

get_architecture_rationale

Why is this module built this way? Aggregates all architectural decisions, active constraints, corrections, and skills for a domain into a coherent narrative. Use BEFORE refactoring or questioning a design choice — the answer is often 'it's that way because of compliance/performance/incident X'. Returns decisions sorted by recency, active constraints that still apply, and correction history showing what was tried and reverted.

check_deploy_readiness

Is it safe to deploy these changes? Cross-references your changed modules against active constraints, recent incidents, knowledge freshness, and active alerts. Returns a composite verdict (ready/caution/block) with per-module breakdown and actionable recommendations. Use BEFORE deploying to catch constraint violations, recent regressions in the same area, stale knowledge that needs verification, and active alerts that might interact with your changes.

get_operator_profile

Retrieve the human operator's working context: role, domain expertise, communication preferences, quality bar, trusted/distrusted sources. Returns the latest version of the profile. Defaults to the operator linked to the calling agent's passport.

update_operator_profile

Update the operator profile. Creates a new version with provenance receipt (does not mutate). Accepts partial updates — fields not provided are preserved from the previous version.

run_elicitation

Start or resume a structured elicitation session for a specific knowledge layer. Layers: operating_rhythm, recurring_decisions, dependencies, friction, judgment_patterns, quality_standards, or 'full' for all layers. Returns the first question and session metadata. Use answer_elicitation to submit answers.

answer_elicitation

Submit an answer to an elicitation question. Triggers coverage re-assessment, follow-up question selection, and automatic output routing to appropriate record types (operating rhythms, constraints, decision context, operator profile). Returns the next question or session completion.

get_operating_rhythms

Retrieve operating rhythm records for an operator — temporal behavioural patterns capturing what the human actually does (not what their calendar says). Filterable by cadence (daily, weekly, monthly) and delegation status. Returns structured sequences with delegation readiness signals.

assess_delegation_readiness

Multi-dimensional delegation readiness assessment. Checks operator profile completeness, operating rhythm coverage, constraint coverage, knowledge coverage, and decision framework coverage relative to the task. Returns overall readiness signal (ready/likely_ready/needs_work/not_ready), dimension-level gaps, and prioritised recommended actions. This is the pre-flight check for delegation, not for action (that's verify_before_acting).

provision_agent_context

Generate a structured, receipted context package for a new agent — the equivalent of soul.md + heartbeat.md + user.md but machine-queryable and backed by MemoryCrux records. Includes identity, operator context, active constraints, operating rhythms, knowledge briefing, and heartbeat schedule. Scope: minimal (identity + constraints), standard (all), comprehensive (standard + full knowledge).

decompose_expertise

Decompose a high-level task class (e.g. 'handle marketing', 'review contracts') into specific steps with knowledge requirements, judgment requirements, delegation difficulty (trivial/moderate/hard/expert_only), existing coverage, and elicitation signals. Identifies which steps can be immediately delegated, which need elicitation first, and which are genuinely expert-only.