docs: document KG supersede usage (#2059)

* docs: document KG supersede usage

Requested-by: Grace Gettert <grace.gettert@carpe.io>

* docs: update recall skills for KG supersede

Requested-by: Grace Gettert <grace.gettert@carpe.io>

* docs: update Claude recall skill supersede guidance

Requested-by: Grace Gettert <grace.gettert@carpe.io>

Author: ggettert

.antigravity-plugin/skills/mempalace-recall/SKILL.md

@@ -65,8 +65,11 @@ and violates MemPalace's "memory should feel instant" budget.
 5. **After a substantive session**, record continuity with
    `mempalace_diary_write` (background hooks may already do this — do not
    double-file).
-6. **When a fact changes**, call `mempalace_kg_invalidate` on the old
-   fact, then `mempalace_kg_add` for the new one.
+6. **When a fact changes**, choose the operation that preserves temporal
+   history: use `mempalace_kg_supersede` for single-valued replacements
+   (model, employer, owner, address, current status),
+   `mempalace_kg_invalidate` for facts that ended without replacement,
+   and `mempalace_kg_add` for independent/coexisting facts.
 
 The full canonical protocol — shared verbatim with the Antigravity
 recall rule and the other integrations — lives in
@@ -78,6 +81,7 @@ recall rule and the other integrations — lives in
 |---|---|
 | Find any memory by meaning | `mempalace_search` (start here) |
 | Relational / time-bound facts about an entity | `mempalace_kg_query` |
+| Replace a single-valued fact | `mempalace_kg_supersede` |
 | The chronological story of an entity | `mempalace_kg_timeline` |
 | Recent session continuity | `mempalace_diary_read` |
 | Which wings / rooms exist (scope unknown) | `mempalace_list_wings`, `mempalace_list_rooms` |
@@ -97,8 +101,9 @@ question — not a system prompt or pasted conversation) plus optional
   installer `hooks/antigravity/install.sh`). Do not silently fall back
   to guessing from model memory.
 - **Stale or conflicting facts.** Prefer the knowledge graph's
-  time-valid answer; if a fact has changed, invalidate the old one and
-  add the new one rather than overwriting context silently.
+  time-valid answer. Use `mempalace_kg_supersede` for single-valued replacements,
+  `mempalace_kg_invalidate` for facts that ended without replacement,
+  and `mempalace_kg_add` for independent/coexisting facts.
 
 ## Anti-patterns — never do these
 

.claude-plugin/skills/mempalace-recall/SKILL.md

@@ -44,8 +44,10 @@ a variable, fixing a typo). Recall is question-driven, not reflexive.
    stored content.
 4. After a substantive session, record continuity with
    `mempalace_diary_write` (skip if a background hook already saved).
-5. When a fact changes: `mempalace_kg_invalidate` the old fact, then
-   `mempalace_kg_add` the new one.
+5. When a fact changes: use `mempalace_kg_supersede` for
+   single-valued replacements, `mempalace_kg_invalidate` for facts that
+   ended without replacement, and `mempalace_kg_add` for
+   independent/coexisting facts.
 
 ## Unhappy paths
 
@@ -61,7 +63,9 @@ a variable, fixing a typo). Recall is question-driven, not reflexive.
   --archive-existing --yes`), not re-mine, which drops MCP-added drawers
   and diary entries (#1843). Do not repair in-process.
 - **Conflicting facts** — trust the knowledge graph's time-valid answer;
-  invalidate-then-add rather than overwriting silently.
+  use `mempalace_kg_supersede` for single-valued replacements,
+  `mempalace_kg_invalidate` for facts that ended without replacement,
+  and `mempalace_kg_add` for independent/coexisting facts.
 
 The canonical protocol, shared across all MemPalace integrations, lives
 in `integrations/shared/recall-protocol.md`.

integrations/shared/recall-protocol.md

@@ -41,15 +41,19 @@ question-driven, not reflexive.
 5. **After a substantive session**, record continuity with
    `mempalace_diary_write` (background hooks may already do this — do not
    double-file).
-6. **When a fact changes**, call `mempalace_kg_invalidate` on the old
-   fact, then `mempalace_kg_add` for the new one.
+6. **When a fact changes**, choose the operation that preserves temporal
+   history: use `mempalace_kg_supersede` for single-valued replacements
+   (model, employer, owner, address, current status),
+   `mempalace_kg_invalidate` for facts that ended without replacement,
+   and `mempalace_kg_add` for independent/coexisting facts.
 
 ## Tool selection
 
 | You need | Tool |
 |---|---|
 | Find any memory by meaning | `mempalace_search` (start here) |
 | Relational / time-bound facts about an entity | `mempalace_kg_query` |
+| Replace a single-valued fact | `mempalace_kg_supersede` |
 | The chronological story of an entity | `mempalace_kg_timeline` |
 | Recent session continuity | `mempalace_diary_read` |
 | Which wings / rooms exist (when scope unknown) | `mempalace_list_wings`, `mempalace_list_rooms` |
@@ -75,8 +79,9 @@ question — not a system prompt or pasted conversation) plus optional
   by re-mining. See "Recovering a corrupt index" below. Do not attempt an
   in-process repair from the agent; guide the user to run the CLI.
 - **Stale or conflicting facts.** Prefer the knowledge graph's
-  time-valid answer; if a fact has changed, invalidate the old one and
-  add the new one rather than overwriting context silently.
+  time-valid answer. Use `mempalace_kg_supersede` for single-valued replacements,
+  `mempalace_kg_invalidate` for facts that ended without replacement,
+  and `mempalace_kg_add` for independent/coexisting facts.
 
 ## Recovering a corrupt index
 

skills/mempalace-recall/SKILL.md

@@ -60,8 +60,10 @@ and violates MemPalace's "memory should feel instant" budget.
    stored content — quoting the exact words is the point of the system.
 5. After a substantive session, record continuity with
    `mempalace_diary_write` (skip if a background hook already saved).
-6. When a fact changes: `mempalace_kg_invalidate` the old fact, then
-   `mempalace_kg_add` the new one.
+6. When a fact changes: use `mempalace_kg_supersede` for
+   single-valued replacements, `mempalace_kg_invalidate` for facts that
+   ended without replacement, and `mempalace_kg_add` for
+   independent/coexisting facts.
 
 The full canonical protocol — shared verbatim with the Cursor recall
 rule and the other integrations — lives in
@@ -73,6 +75,7 @@ rule and the other integrations — lives in
 |---|---|
 | Find any memory by meaning | `mempalace_search` (start here) |
 | Relational / time-bound facts about an entity | `mempalace_kg_query` |
+| Replace a single-valued fact | `mempalace_kg_supersede` |
 | The chronological story of an entity | `mempalace_kg_timeline` |
 | Recent session continuity | `mempalace_diary_read` |
 | Which wings / rooms exist (scope unknown) | `mempalace_list_wings`, `mempalace_list_rooms` |
@@ -112,7 +115,9 @@ search. The canonical protocol lives in
   Do not attempt an in-process repair from the agent. Full steps are in
   the shared protocol's "Recovering a corrupt index" section.
 - **Conflicting facts.** Trust the knowledge graph's time-valid answer;
-  invalidate-then-add rather than overwriting silently.
+  use `mempalace_kg_supersede` for single-valued replacements,
+  `mempalace_kg_invalidate` for facts that ended without replacement,
+  and `mempalace_kg_add` for independent/coexisting facts.
 
 ## Anti-patterns — never do these
 

website/concepts/knowledge-graph.md

@@ -11,6 +11,7 @@ Subject → Predicate → Object [valid_from → valid_to]
 ```
 
 Facts have time windows. When something stops being true, you invalidate it — and historical queries still find it.
+When a single-valued fact changes, supersede it so the old and new values meet at one precise boundary.
 
 ## Usage
 
@@ -49,6 +50,28 @@ kg.invalidate("Kai", "works_on", "Orion", ended="2026-03-01")
 
 Now queries for Kai's current work won't return Orion. Historical queries still will.
 
+### Superseding Facts
+
+When a single-valued fact changes, use `supersede()` instead of hand-rolling `invalidate()` plus `add_triple()`:
+
+```python
+kg.add_triple("Kai", "uses_model", "gpt-4.1", valid_from="2026-01-01")
+
+kg.supersede(
+    "Kai",
+    "uses_model",
+    old_obj="gpt-4.1",
+    new_obj="gpt-5.6",
+    at="2026-07-20",
+)
+```
+
+`supersede()` closes the old fact and opens the new one in a single transaction with the same precise boundary.
+A query at the handoff returns only the successor, not both values.
+
+Use it for relationships that should have one current value, such as `uses_model`, `works_at`, or `lives_at`.
+Keep `invalidate()` for facts that simply ended, and use `add_triple()` for facts that can coexist.
+
 ### MCP Tools
 
 Through the MCP server, the knowledge graph is available as tools:
@@ -58,6 +81,7 @@ Through the MCP server, the knowledge graph is available as tools:
 | `mempalace_kg_query` | Query entity relationships with time filtering |
 | `mempalace_kg_add` | Add facts |
 | `mempalace_kg_invalidate` | Mark facts as ended |
+| `mempalace_kg_supersede` | Atomically replace one current fact with another |
 | `mempalace_kg_timeline` | Chronological entity story |
 | `mempalace_kg_stats` | Graph overview |
 

website/guide/mcp-integration.md

@@ -91,6 +91,7 @@ This protocol is what turns storage into memory — the AI knows to verify befor
 | `mempalace_kg_query` | Entity relationships with time filtering |
 | `mempalace_kg_add` | Add facts |
 | `mempalace_kg_invalidate` | Mark facts as ended |
+| `mempalace_kg_supersede` | Atomically replace one current fact with another |
 | `mempalace_kg_timeline` | Chronological entity story |
 | `mempalace_kg_stats` | Graph overview |
 

website/reference/api-reference.md

@@ -128,6 +128,7 @@ Default path: `~/.mempalace/knowledge_graph.sqlite3`
 | `add_entity(name, entity_type='unknown', properties=None)` | Name, type, props dict | `str` (entity ID) | Add or update entity node |
 | `add_triple(subject, predicate, obj, valid_from, valid_to, confidence, source_closet, source_file)` | See below | `str` (triple ID) | Add relationship triple |
 | `invalidate(subject, predicate, obj, ended=None)` | Entity names, end date | — | Mark relationship as ended |
+| `supersede(...)` | Entity names, replacement value, optional boundary | `str` (new triple ID) | Atomically replace one current relationship with another |
 
 **`add_triple` parameters:**
 
@@ -142,6 +143,42 @@ Default path: `~/.mempalace/knowledge_graph.sqlite3`
 | `source_closet` | `str` | `None` | Link to verbatim memory |
 | `source_file` | `str` | `None` | Original source file |
 
+**`supersede` signature:**
+
+```python
+supersede(
+    subject,
+    predicate,
+    old_obj,
+    new_obj,
+    at=None,
+    confidence=1.0,
+    source_closet=None,
+    source_file=None,
+    source_drawer_id=None,
+    adapter_name=None,
+)
+```
+
+**`supersede` parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `subject` | `str` | — | Source entity name |
+| `predicate` | `str` | — | Single-valued relationship type |
+| `old_obj` | `str` | — | Current value to close if it is open |
+| `new_obj` | `str` | — | Replacement value to open |
+| `at` | `str` | current UTC instant | Handoff boundary; date-only values normalize to midnight UTC |
+| `confidence` | `float` | `1.0` | Confidence score 0.0–1.0 |
+| `source_closet` | `str` | `None` | Link to verbatim memory |
+| `source_file` | `str` | `None` | Original source file |
+| `source_drawer_id` | `str` | `None` | Source drawer provenance |
+| `adapter_name` | `str` | `None` | Source adapter provenance |
+
+Use `supersede` when a single-valued relationship changes, such as a model, employer, address, or primary assignment.
+It closes the old fact and opens the new fact at the same precise boundary, so an as-of query at the handoff returns only the successor.
+Use `invalidate` for facts that simply ended, and `add_triple` for facts that can coexist.
+
 #### Query Methods
 
 | Method | Parameters | Returns |

website/reference/python-api.md

@@ -61,6 +61,14 @@ kg = KnowledgeGraph()  # uses default path: ~/.mempalace/knowledge_graph.sqlite3
 kg.add_entity("Kai", entity_type="person")
 kg.add_triple("Kai", "works_on", "Orion", valid_from="2025-06-01")
 kg.invalidate("Kai", "works_on", "Orion", ended="2026-03-01")
+kg.add_triple("Kai", "uses_model", "gpt-4.1", valid_from="2026-01-01")
+kg.supersede(
+    "Kai",
+    "uses_model",
+    old_obj="gpt-4.1",
+    new_obj="gpt-5.6",
+    at="2026-07-20",
+)
 
 # Read
 facts = kg.query_entity("Kai", as_of="2026-01-15", direction="both")
@@ -69,6 +77,9 @@ timeline = kg.timeline("Orion")
 stats = kg.stats()
 ```
 
+Use `supersede()` when a single-valued fact changes.
+It writes the old fact's `valid_to` and the new fact's `valid_from` at the same boundary, avoiding overlapping values at the handoff.
+
 ## Palace Graph
 
 Room-based navigation graph built from ChromaDB metadata.