feat(memory): derivation-kind tag on graph edges and extracted facts

[prakashUXtech]

Summary

Add a derivation-kind tag to graph edges (and extracted facts) that records how a relation was produced: read directly from the source, inferred by the LLM, or ambiguous. This is distinct from the confidence/weight we already store.

Why

While comparing our memory layer against graphify (an LLM-wiki project that builds a concept graph), one of its primitives stood out: every relationship edge carries an EXTRACTED / INFERRED / AMBIGUOUS tag.

We already have more provenance than they do:

• GraphNode.provenance / GraphEdge.provenance: source memory IDs (runtime/memory/graph_types.py:85,106)
• GraphEdge.weight: LLM confidence score 0–1 (graph_types.py:105)
• MemoryEntry.confidence: 0–1 (runtime/types.py:376)

What we can't express today is the kind of derivation. A weight=0.6 edge could be a low-confidence literal extraction or a medium-confidence inference, and a reader can't tell which. That distinction matters for trust: a fact the soul read from a real turn is not the same as one it guessed.

Proposal

1. Add a DerivationKind StrEnum (extracted, inferred, ambiguous) next to RelationType in graph_types.py (open-string contract, same as the other vocab enums).
2. Add a derivation: DerivationKind | None = None field on GraphEdge, and optionally on MemoryEntry for facts that come out of the observe() pipeline. Default None so pre-0.5 souls round-trip with no migration (backfill on awaken, same pattern as retrieval_weight / prediction_error).
3. Have the extractor in update_graph() set it when it writes edges.
4. Capture it in the trust-chain payload alongside prediction_error, so a verifier can see whether a claim was read or inferred.
5. Let recall filter on it (e.g. extracted-only), so callers that want grounded facts can ask for them.

Scope

Enum + field + extractor wiring + trust-payload capture + a recall filter. No UI, no new dependency.

Related

• Graph entity extraction produces fragmented, mistyped nodes and zero edges #250 (graph extraction quality): a derivation tag also gives that work a place to mark uncertain edges instead of dropping them.
• Trust-chain integrity work: trust: harden _canonical_json against non-JSON-native types #200, trust: chain pruning + archival for long-running souls #203, trust: tighten compute_payload_hash typing + reject Pydantic models #205.
• Fits the 0.5.0 "Intelligence + Integrity" tracker (Release tracker: 0.5.0 — Intelligence + Integrity #218).

[github-actions]

This issue has been automatically marked as stale because it has not had activity in the last 30 days. It will be closed in 14 days if no further activity occurs. If this is still relevant, please comment or update.