Skip to main content

​
vault_fact

Creates a directed edge between two entities with searchable fact text. Use this for immediate, precise fact storage. Unlike record_memory (which distills asynchronously), facts from vault_fact appear in the graph right away. Auto-creates target or source entities when their type is provided. Includes semantic near-duplicate detection to keep the graph clean.

​
Parameters

ParameterTypeRequiredDefaultDescription
source_namestringYes—Name of the source entity
target_namestringYes—Name of the target entity
relation_typestringYes—Short snake_case verb phrase, max 3 words (e.g., "works_at", "prefers", "uses_technology")
rationalestringYes—Why this fact is being asserted
fact_textstringNonullHuman-readable fact statement. Embedded and searchable
source_typestringNonullEntity type to auto-create the source if it doesn’t exist
target_typestringNonullEntity type to auto-create the target if it doesn’t exist
valid_atstringNonullISO date (YYYY-MM-DD) when this fact became true
expires_atstringNonullISO date (YYYY-MM-DD) when this fact should soft-expire. Faded facts are hidden from summaries but still searchable
skip_taxonomy_checkbooleanNonullBypass taxonomy similarity check when you’ve confirmed this relation_type is intentionally distinct

​
Read-only

No. This tool writes to your memory.

​
Example usage

{
  "source_name": "Alice",
  "target_name": "Acme Corp",
  "target_type": "organization",
  "relation_type": "works_at",
  "rationale": "User mentioned Alice works at Acme",
  "fact_text": "Alice is a senior engineer at Acme Corp"
}

{
  "source_name": "User",
  "target_name": "Four Seasons",
  "target_type": "organization",
  "relation_type": "prefers",
  "rationale": "User stated hotel preference directly",
  "fact_text": "Prefers Four Seasons hotels when traveling, boutique luxury as fallback"
}

{
  "source_name": "my-api",
  "source_type": "project",
  "target_name": "PostgreSQL",
  "target_type": "technology",
  "relation_type": "uses_technology",
  "rationale": "Confirmed during architecture discussion",
  "fact_text": "my-api uses PostgreSQL 15 as its primary datastore",
  "valid_at": "2025-01-15"
}

​
Edge taxonomy snapping

BaseLayer automatically normalizes similar relation_type values to maintain a clean, consistent graph. For example, "employed_at" and "works_at" may be snapped to the same canonical type. If you intentionally want a distinct relation type and the taxonomy check is flagging it as a near-duplicate, set skip_taxonomy_check to true.

​
Temporal facts

Use expires_at for facts that are temporary or transient:
  • Durable facts (preferences, relationships, traits): Omit expires_at
  • Transient facts (currently researching X, reading book Y, troubleshooting issue Z): Set expires_at to a reasonable date
Expired facts become “faded” — hidden from entity summaries but still findable via search.
Use valid_at to record when a fact became true, not when it was recorded. This helps build an accurate timeline for entities.