> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baselayer.id/llms.txt
> Use this file to discover all available pages before exploring further.

# vault_fact

> Assert a fact connecting two entities in the knowledge graph.

# 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

| Parameter             | Type    | Required | Default | Description                                                                                                           |
| --------------------- | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `source_name`         | string  | Yes      | --      | Name of the source entity                                                                                             |
| `target_name`         | string  | Yes      | --      | Name of the target entity                                                                                             |
| `relation_type`       | string  | Yes      | --      | Short snake\_case verb phrase, max 3 words (e.g., `"works_at"`, `"prefers"`, `"uses_technology"`)                     |
| `rationale`           | string  | Yes      | --      | Why this fact is being asserted                                                                                       |
| `fact_text`           | string  | No       | `null`  | Human-readable fact statement. Embedded and searchable                                                                |
| `source_type`         | string  | No       | `null`  | Entity type to auto-create the source if it doesn't exist                                                             |
| `target_type`         | string  | No       | `null`  | Entity type to auto-create the target if it doesn't exist                                                             |
| `valid_at`            | string  | No       | `null`  | ISO date (`YYYY-MM-DD`) when this fact became true                                                                    |
| `expires_at`          | string  | No       | `null`  | ISO date (`YYYY-MM-DD`) when this fact should soft-expire. Faded facts are hidden from summaries but still searchable |
| `skip_taxonomy_check` | boolean | No       | `null`  | Bypass taxonomy similarity check when you've confirmed this `relation_type` is intentionally distinct                 |

## Read-only

No. This tool writes to your memory.

## Example usage

```json theme={null}
{
  "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"
}
```

```json theme={null}
{
  "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"
}
```

```json theme={null}
{
  "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.

<Tip>
  Use `valid_at` to record when a fact became true, not when it was recorded. This helps build an accurate timeline for entities.
</Tip>