Claims

A claim is one structured fact Vault stores:

Entity keys

Entities group facts about one subject. Agents must agree on the same entity string before Vault compares them. Compatible facts on that subject can both stay active. Only a contradicts label starts recency or authority.

user.diet          → diet preferences
user.timezone      → IANA / regional timezone
user.schedule.*    → wildcard patterns in authority config

Entities are not a hardcoded enum. The extraction LLM picks a dotted-path string guided by the prompt (user.diet, user.timezone, etc.). Any non-empty string is accepted.

Entity resolution

After extraction and before classification, resolveEntity() aligns the extracted label with existing active claims when fact text is semantically similar. This fixes LLM drift (user.abc vs user.timezone) so cross-agent conflict can trigger.

Search is global across all active claims (no sourceAgent filter). Disable entirely with entityMatchThreshold: 0 or a custom resolveEntity hook.

On UPDATE, the stored entity is preserved from the target claim — extractor labels cannot rename via merge.

Entity registry (optional)

For production apps that need a canonical taxonomy, enable the entities table with useEntityRegistry: true:

import { Memory, seedEntities, EXAMPLE_ENTITY_SEED } from "vault-memory";

await seedEntities(db, EXAMPLE_ENTITY_SEED);

const memory = new Memory("my-agent", {
  db,
  apiKey: process.env.OPENAI_API_KEY,
  useEntityRegistry: true,
  entityRegistryAutoRegister: true, // default — register valid new: keys on first use
});

When enabled:

• The extraction prompt includes known keys from the registry
• The LLM must pick an existing key or use new:user.<domain> for new subjects
• ensureEntityInRegistry() validates keys against entityKeyPattern (default: user.<dotted.path>)

See Configuration for all entity-related options.

Claim status