Store one or more factual observations under an entity in the knowledge graph. Automatically creates the entity if missing, evaluates pre-insertion contradiction detection against existing facts, assigns authority tiers, and records logical dependencies.

WHEN TO USE:

• Use "remember" to record new knowledge, user preferences, architectural decisions, or verified facts.

• DO NOT use to invalidate or delete outdated facts — use "forget" instead.

• DO NOT use to query memory — use "recall" or "context" instead.

CONTRADICTION & RETURN BEHAVIOR:

• Evaluates semantic opposition. If a contradiction is detected, a warning is returned and recorded in the audit log while persisting the fact.

• Returns JSON containing { ok: true, entity, domain, tier, observationIds, contradictionWarnings }.

Search memory observations and facts matching keywords or concepts using SQLite FTS5 BM25. Enforces a strict token budget to prevent context window overflow.

WHEN TO USE:

• Use "recall" for focused keyword search, retrieving specific past facts, or when under a strict token budget.

• DO NOT use for exploring structural, multi-hop entity relationships — use "context" instead.

RETURNS:

• JSON object containing matched entities, facts with authority tiers and statuses, estimated tokens used, and truncation flag.

Invalidate or permanently remove an entity or a specific observation UUID. Supports soft invalidation, hard permanent deletion, and automatic cascading invalidation of dependent facts.

WHEN TO USE:

• Use "forget" when a fact is superseded, contradicted, or deprecated.

• Prefers soft invalidation (hard=false) to preserve audit trails. Use hard=true only when permanently expunging sensitive data.

• DO NOT use to update a fact with new info — use "remember" with updated content.

PERMISSIONS & FAILURE BEHAVIOR:

• Operates locally on SQLite storage. Returns an error if the target entity name or UUID is not found in the database.

• Returns JSON containing { ok: true, type, targetId/entity, mode, cascadedStaleCount }.

Traverse the knowledge graph starting from query seed entities outward up to N hops using GraphRAG relational discovery.

WHEN TO USE:

• Use "context" when you need holistic, multi-hop relational knowledge around an entity (e.g. architecture, connections, dependencies).

• DO NOT use for simple keyword search or strict token-budget lookups — use "recall" instead.

RETURNS:

• Formatted relational Markdown document detailing seed entities, their attributes, active observations, and outward relation links.