Epiphany/notes/epiphany-memory-graph-unified-plan.md

Epiphany Memory Graph Unified Plan

The repo fractal dataflow graph and agent memory are one architecture.

They differ in policy, not substrate. A source module, a durable role memory, an incubating thought, an agency pressure, and an evidence record are all typed claims in a domain. They need anchors, edges, lifecycle, summaries, freshness, and semantic recall. Building separate engines for them would duplicate authority and then charge us rent forever.

The shared organ is EpiphanyMemoryGraph.

typed domain claim
-> memory graph node / edge / anchor
-> lifecycle state
-> conservative summary
-> embedding manifest
-> semantic cache
-> context cut
-> role/repo/Persona/coordinator packet

Core Principle

Memory is not a bag of text. Memory is a graph of typed claims with lifecycle.

Qdrant is not memory. Qdrant is the fast semantic nerve wrapped around memory. It may rank candidate nodes and summaries. It may not be the only place a claim exists.

Domain Profiles

The substrate is shared. Profiles define policy.

repo_architecture

Owns:

• modules
• crates
• binaries
• schemas
• runtime contracts
• adapters
• test seams
• ownership/invariant claims

Lifecycle:

• observed
• proposed
• accepted
• stale
• retired

repo_dataflow

Owns:

• inputs
• durable stores
• transformations
• outputs
• read/write/derive/adapt/persist edges
• runtime and wire contracts

Lifecycle:

• observed
• proposed
• accepted
• stale
• retired

role_self

Owns:

• lane-local semantic memory
• episodic memory
• relationship memory
• goals
• values
• habits
• private notes

Lifecycle:

• proposed
• accepted
• revised
• retired
• crystallized

short_term

Owns:

• rumination residue
• provisional thoughts
• fresh anchors
• unresolved local tensions

Lifecycle:

• active
• clustered
• distilled
• incubated
• pruned

incubation

Owns:

• thoughts not ready for durable memory, speech, or action
• support memories
• open questions
• saturation/refractory state

Lifecycle:

• active
• deepening
• cooling
• promoted
• retired

agency_pressure

Owns:

• discomforts
• self-advocacy requests
• world-advocacy requests
• wiring requests

Lifecycle:

• active
• obligated
• cooled
• answered
• retired

candidate_intervention

Owns:

• possible Persona speech
• possible coordinator note
• possible selfPatch
• possible future review action

Lifecycle:

• queued
• deferred
• spoken
• applied
• retired

evidence

Owns:

• verifier receipts
• source anchors
• artifact refs
• accepted/rejected scars

Lifecycle:

• observed
• reviewed
• accepted
• contradicted
• superseded

Shared Typed Documents

First-class documents:

• EpiphanyMemoryGraphSnapshot
• EpiphanyMemoryDomain
• EpiphanyMemoryNode
• EpiphanyMemoryEdge
• EpiphanyMemoryAnchor
• EpiphanyMemorySummary
• EpiphanyMemoryLifecycleReceipt
• EpiphanyMemoryEmbeddingManifest
• EpiphanyMemoryFreshness
• EpiphanyMemoryContextQuery
• EpiphanyMemoryContextPacket
• EpiphanyMemoryPatchCandidate

Node minimum:

• id
• domain_id
• profile
• kind
• title
• claim
• question
• tension
• action_implication
• anchors
• source_hashes
• lifecycle
• salience
• confidence
• created_at
• updated_at

Edge minimum:

• id
• source_id
• target_id
• kind
• profile
• claim
• anchors
• lifecycle
• confidence

Summary minimum:

• id
• domain_id
• covers_node_ids
• covers_edge_ids
• target
• claim
• tension
• action_implication
• anchor_count
• source_hashes
• freshness
• confidence
• known_omissions

Shared Operations

Generic graph operations:

• upsert_node
• upsert_edge
• retire_node
• revise_node
• merge_nodes
• attach_anchor
• summarize_cluster
• mark_stale
• refresh_embedding
• select_context_cut

Profile-specific operations:

• repo profiles may propose architecture/dataflow graph patches
• role profiles may apply reviewed selfPatch-derived memory
• short-term profile may cluster/prune/distill
• incubation profile may deepen/cool/promote/retire
• agency profile may queue obligation or cool pressure
• candidate profile may mark spoken/applied/retired

The validator enforces profile law before generic graph mutation.

Context Packets

A context packet is a cut through the memory graph.

It may contain:

• exact nodes
• exact edges
• conservative summaries
• anchors/evidence refs
• stale/missing warnings
• contradiction guards
• verification seams
• lifecycle receipts
• profile-specific obligations

Repo work gets architecture/dataflow-heavy packets.

Role work gets role_self/short_term/incubation/agency-heavy packets.

Persona gets candidate/agency/incubation packets with public-surface filters.

Coordinator gets pressure, stale state, obligations, and receipts.

Same graph. Different cuts.

Invariants

• One memory graph substrate owns typed claims.
• Profiles own policy and lifecycle restrictions.
• Qdrant stores vectors for graph documents, not canonical graph documents.
• Deleting Qdrant leaves a slower but correct typed graph.
• Model output proposes operations; core validation applies or rejects.
• Short-term memory cannot survive forced sleep unaccounted.
• Repo graph candidates cannot become accepted architecture truth without review.
• Role memory cannot store project truth.
• Evidence anchors must remain distinguishable from remembered claims.
• Conservative summaries must preserve target, claim/question, tension, implication, anchors, freshness, and known omissions.

Implementation Roadmap

Phase 1: Shared Memory Graph Types

Files:

• epiphany-state-model/src/lib.rs
• epiphany-core/src/memory_graph.rs
• epiphany-core/src/memory_graph/documents.rs

Add shared document structs and enums.

Tests:

• serde round trip
• stable id helpers
• edge references existing node ids
• summaries cannot cover missing ids
• profile enum covers repo and agent memory domains

Phase 2: Shared Validation And Context Cut

Files:

• epiphany-core/src/memory_graph/validation.rs
• epiphany-core/src/memory_graph/context_cut.rs
• epiphany-core/src/memory_graph/freshness.rs

Tests:

• parent summary used when fresh/high-confidence
• descent required when stale/low-confidence/high-relevance
• Qdrant absence is irrelevant to correctness
• stale source hash propagates through summaries

Phase 3: Repo Profile

Files:

• epiphany-core/src/memory_graph/profiles/repo.rs
• notes/archive/repo-fractal-dataflow-cache-plan.md

Implements repo domain/node/edge policy on shared graph.

Phase 4: Agent Memory Profile

Files:

• epiphany-core/src/memory_graph/profiles/agent.rs
• epiphany-core/src/agent_memory_model.rs
• notes/archive/agent-memory-fractal-cache-plan.md

Implements short-term/durable/incubation/agency/candidate policy on shared graph.

Phase 5: CultCache Store

Store shared graph docs as typed CultCache documents.

Commands should query memory graph status and context packets without Qdrant.

Phase 6: Qdrant Cache

Embed shared graph nodes, edges, and summaries.

Qdrant candidate ranking feeds context-cut planning but never emits canonical memory payloads.

Phase 7: Sleep And Repo Refresh

Sleep maintenance and repo scanning become profile-specific producers of typed memory graph operations.

Phase 8: CultNet And Prompt Integration

Advertise memory graph read/mutation/context contracts through runtime-spine. Render context packets into role prompts and operator surfaces.

First Implementable Ticket

Title: Add shared EpiphanyMemoryGraph typed documents and pure validation

Scope:

• Add shared memory graph document types.
• Add stable id helpers.
• Add pure validation for nodes, edges, summaries, anchors, and profile/lifecycle legality.
• Add pure context-cut fixture tests.
• Update repo/agent memory plans to point at this substrate.

Out of scope:

• no Qdrant
• no scanner
• no sleep runner
• no app-server route
• no prompt integration

Verification:

cargo fmt --manifest-path .\epiphany-core\Cargo.toml
cargo test --manifest-path .\epiphany-core\Cargo.toml --lib memory_graph
cargo check --manifest-path .\epiphany-core\Cargo.toml

Definition of done:

• The shared creature has a skeleton.
• Repo modeling and agent memory can add profiles without duplicating graph, cache, freshness, or context-packet machinery.