Memory and knowledge

Entities, observations, relations

The knowledge graph holds three things:

Entities are named things: people, vendors, topics, decisions. Names are unique within the visible scope; creating an existing name resolves to that identity (reviving it when retired) rather than duplicating it.
Observations are individual facts attached to an entity ("Acme Print offers same-day turnaround"). Facts accumulate; duplicates are skipped; re-adding retired text revives the original.
Relations are typed links between two live, visible entities ("Acme Print supplies Paul Pack"). Both endpoints must resolve or the entry is skipped; re-creating a retired triple revives it.

Create with create_entities, add_observations, create_relations.

Reading: search, open, graph

Three read paths for three situations:

Know the names? open_nodes returns exactly those entities with observations and the relations between them. Unknown or out-of-scope names read as missing.
Exploring freely? search_nodes ranks by free text and packs evidence under a wire budget, with an accounting block describing coverage. Its project hint is affinity only.
Need a guarantee of one project? search_by_project searches strictly inside the named project; every hit is in-project.
Want the whole visible world? read_graph pages the graph snapshot. find_by_title finds across tasks, notes, and entities from a half-remembered phrase.

All reads are scope-gated end to end, including one-hop neighbour expansion: foreign content never enters candidates, evidence, or counts.

Retiring, not deleting

delete_entities, delete_observations, and delete_relations retire content: it resolves as absent everywhere but stays preserved with its history, and re-creating revives the same identity. There is no cascade: retiring an entity leaves its observations and relations in place, absent alongside it, reviving independently. Unknown or invisible names contribute zero with no error, so retirement cannot probe foreign projects.

Despite their names, these tools never physically delete. The names stay for compatibility; the behaviour is lifecycle, per the no-delete invariant (03-security-and-boundaries).

Linking tasks to entities

Work and knowledge meet through links: link_task_entity creates a manual link (upgrading any auto-discovered one), get_task_links and get_entity_tasks read both directions, suggest_task_links proposes candidates with explainable scores but never links by itself, and unlink_task_entity removes while keeping the removal as evidence (rejecting a high-confidence suggestion keeps it suppressed as an evaluation label).

Candidate claims and governance

The pipeline can extract typed candidate claims (subject, predicate, object, scope) from context. Candidates are not facts: they need evidence and an explicit governance decision (promote_candidate, govern_fact) before becoming canonical, and sensitive scopes demand confirmed human approval. Provenance (which chunk, which session, which decision produced a fact) travels with the claim so audits can replay it. See 07-reflection for the review flows that consume this machinery.

When to use, when not to

Use entities for things you will refer to again; use tasks for things you will do; use observations for facts, not running commentary.
Prefer search_by_project when the project is known; prefer search_nodes for open exploration; prefer open_nodes when names are exact.
Retire stale knowledge promptly: an absent-with-history fact beats a present-but-wrong one, but never "clean up" foreign or unknown names; the silent skip means you cannot tell the difference, by design.