431 lines
8.7 KiB
Markdown
431 lines
8.7 KiB
Markdown
# 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`.
|
|
|
|
```text
|
|
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.
|
|
|
|
Landed 2026-07-15: the shared typed projection, strict Qdrant/Ollama backend,
|
|
Mind/Modeling physical partitions, canonical candidate reload, scoped sync,
|
|
typed projection receipts, BM25 fallback, CLI index/context path, and Persona
|
|
recall migration are live. See
|
|
`notes/memory-graph-semantic-projection-authority-map.md`. Remaining work is
|
|
daemon scheduling/CultMesh advertisement and refreshing stale Modeling anchors;
|
|
do not rebuild a Persona-specific semantic cache.
|
|
|
|
### 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:
|
|
|
|
```powershell
|
|
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.
|