Stella Graph Memory Sync

Status: Partially shipped — verified against the codebase on 2026-07-03 by an automated audit.

Stella Graph Memory Sync is partially shipped. Phase 0 (ADR-018 transport) landed. Phase 1-2 partially implemented: CLI records episodic memory via engram and basic execution lineage, but memory up-sync contract and business-binding contracts (Phase 3) are absent. Rule enforcement infrastructure exists locally in CLI but lacks cloud sync, compliance judges, and decay (Phases 4-5).

Implementation evidence

• /Users/macanderson/Workspaces/oxagen-platform/apps/cli/src/agent/memory.ts — CLI engram integration for episodic remember()
• /Users/macanderson/Workspaces/oxagen-platform/apps/cli/src/agent/adapters/graph-sync-provider.ts — execution lineage recording with TOUCHED_FILE edges
• /Users/macanderson/Workspaces/oxagen-platform/packages/oxagen/src/contracts/agent.execution.record.ts — execution record contract exists
• /Users/macanderson/Workspaces/oxagen-platform/apps/cli/src/rules/ — local rule loading and enforcement infrastructure
• /Users/macanderson/Workspaces/oxagen-platform/packages/engram/src/sync/ — CRDT primitives exist but not wired to agent.memory.sync contract

Known gaps at time of archive

• agent.memory.sync contract for engram CRDT peer endpoint (Phase 1)
• CLI wiring for engram assert() and pin() (Phase 1)
• Memory up-sync to cloud graph (Phase 1)
• execution.link contract for attaching MODIFIED/SERVED/DERIVED_FROM edges (Phase 3)
• process.executions.list contract for process-scoped execution queries (Phase 3)
• execution.lineage.get contract for traversing execution→file→feature→process (Phase 3)
• SERVED edge inference joining MODIFIED×IMPLEMENTS (Phase 3)
• Compliance judge extension for rule violation detection (Phase 4)
• Violation episodic recording and rule decay on failures (Phase 4-5)
• Scheduled consolidation with distill/promotePatterns and ROI reporting (Phase 5)

Source documents (archived verbatim below)

• docs/specs/stella-graph-memory-sync/spec.md

Spec — spec.md

Stella ⇄ Oxagen Graph — Memory, Execution Lineage & Business-Process Binding

Status: Draft · Owner: Mac Anderson · Surface: apps/cli (Stella) + packages/engram + packages/oxagen contracts + Neo4j ontology Related: ADR-018 (CLI ↔ workspace graph bidirectional sync — down-sync shipped, up-sync in flight on feat/graph-sync-bidirectional), [[connector-dual-write-pattern]], [[graph-node-anchor-and-is-system-model]], [[cli-claude-code-parity-stack]]

Coordinate before building. A parallel session owns feat/graph-sync-bidirectional (ADR-018 up-sync). This spec is the design layer above the transport — it says what Stella records and how it obeys, and reuses ADR-018's sync plumbing. Land the transport first; this rides on it.

0. One-paragraph thesis

Every other coding agent (Cursor, Copilot, Claude Code, Windsurf, Cody) keeps memory as flat, per-repo, per-user text that never learns across sessions, never crosses repos, and has no idea what the code is for. Oxagen already stores, per workspace, (a) a business ontology (Customer, Invoice, Order, :Feature, processes) ingested from the company's real systems, (b) the code graph (:SourceFile/:SourceSymbol) linked to those features via IMPLEMENTS, and (c) a portable, confidence-decayed memory substrate (@oxagen/engram) with a built-in CRDT sync protocol. Stella is the only coding agent that can stand on all three. The win is a flywheel: Stella writes code → records what it did as graph lineage bound to the business process it served → distills reusable facts and rules → obeys those rules on the next run, everywhere, for every agent and human. This document specifies that flywheel.

1. Current state (ground truth — do not re-invent)

1.1 The substrate already exists: @oxagen/engram

packages/engram is a mature memory substrate. It is the standard Oxagen memory format and it is already a CLI dependency.

1.2 What Stella records today (all local, mostly un-synced)

Takeaway: Stella already reads the workspace graph locally and already uses engram's episodic store. It does not yet (a) use engram's assert/pin/consolidation, (b) up-sync any memory or execution, or (c) connect what it did to the business graph. That is the work.

1.3 The platform graph model (what we write into)

• Universal anchor (:GraphNode:<Label>) with publicId, displayName, properties, is_system, optional embedding float[1536]; graph_node_embedding_index powers NL search via graph.search (kinds: entity·file·symbol·chunk·memory·execution·document·message·asset). Cite nodes by knowledgeNodeRef{id,label,displayName,properties}, never raw UUID ([[ui-node-edge-citation-rule]]).
• Memory (Gen-1): agent.memory.write/recall/policy.* → (:AgentMemory) with REMEMBERS/ABOUT edges, vector recall, half-life decay.
• Executions: Postgres agent_executions (status, tokens, cost, parent_execution_id, synced_to_graph_at) projected to (:Execution) with INVOKED/ORIGINATED_FROM/CALLED_TOOL edges (packages/ontology/src/mutations/record-execution.ts).
• Business ontology: customer entities are (:<Type>:EntityNode) keyed by naturalKey="{connector}:{conn}:{externalId}", entityType property, multi-label via graph.node.label.add/remove. Code is (:SourceFile)/(:SourceSymbol)/(:SourceChunk); (:Feature)-[:IMPLEMENTS]->(:SourceFile|:SourceSymbol) is inferred today.

1.4 The three greenfield gaps this spec fills

1. Memory up-sync — Stella's engram records (episodic/semantic/procedural) never reach the cloud graph. (Build on ADR-018 + engram sync/.)
2. Execution-as-lineage with code + process binding — no (:Execution)-[:MODIFIED]->(:SourceFile|:Feature) and no (:Execution)-[:SERVED]->(business process/entity). The agent runs but the graph never learns what code it changed or what the business it served.
3. Rule adherence — nothing retrieves the workspace's rules/facts before a turn, enforces them during tool use, or records violations. Memory is written but never obeyed.

2. Highest-value data to record

Two streams: executions (what happened) and memories (what we learned). Record by value, not by volume — every record costs sync bandwidth, graph size, and recall noise.

2.1 Executions → graph (the audit + lineage stream)

One (:Execution) per Stella turn/fleet-task, written after the turn (we know the outcome). Priority = highest first.

Raw per-event firehose (every token, every keystroke) stays in ClickHouse (append-only telemetry), not the graph — the graph gets the distilled :Execution node + edges. This respects the four-store boundary.

2.2 Memories → graph (the learning stream)

The killer alignment: this repo's CLAUDE.md + MEMORY.md are hand-maintained semantic+procedural memory. This spec makes Stella generate and obey the same thing automatically, per workspace, graph-anchored, and shareable — the manual memory file becomes the bootstrap seed, not the ceiling.

3. Observation → Memory → Fact: what gets stored, and what gets promoted

Engram already encodes this lifecycle. Stella must use it deliberately. The gates below prevent the #1 failure of agent memory: noise (storing everything → recall returns garbage → agent ignores memory).

   tool result / user msg / judge verdict
                │
                ▼
        ┌───────────────┐   keep only if "decision-relevant" (§3.1)
        │  EPISODIC      │   remember(): confidence 1.0, ttl ~30–90d, decays
        └───────┬───────┘
                │   distill(): cluster ≥N related episodics across runs
                ▼
        ┌───────────────┐   assert(): confidence = cluster agreement
        │  SEMANTIC FACT │   supersedes[] older contradicting facts
        └───────┬───────┘
                │   promotePatterns(): repeated successful procedure
                ▼   (DEFAULT_PROMOTION_CONFIG: ≥80% success, ≥5 occurrences,
        ┌───────────────┐    not already covered by an existing rule)
        │  PROCEDURAL    │   pin(): a RULE — retrieved + enforced every run (§4)
        │  RULE / FACT   │
        └───────────────┘

3.1 What becomes an episodic (the noise filter)

Write an episodic only if it could change a future decision. Concretely, Stella records:

• ✅ A verification outcome (test/build/lint ran and its result) — feeds rule success/failure counts.
• ✅ A surprise: a tool result that contradicted the agent's expectation, an error + its root cause, a path/config that wasn't where expected.
• ✅ A human signal: the user corrected, rejected, or confirmed an approach (high salience).
• ✅ A convention observed: "this package uses .js import extensions," "tests live in __tests__."
• ❌ Not stored: every file read, every successful no-op tool call, restating the prompt, intermediate reasoning, anything already a high-confidence fact (would just duplicate).

Salience at write time (computeSalience) is boosted by: human-originated, failure outcome, security/billing/auth domain, breadth of files. Low-salience episodics decay out within the TTL and never get synced (sync prioritization, §5.3).

3.2 What gets promoted to a fact / rule (and what doesn't)

• Episodic → semantic fact (distill): only when ≥N (config) episodics across different runs agree on a generalization, and it isn't already asserted. A one-off is never a fact. Contradictions bump supersedes[] and lower confidence rather than spawning a duplicate.
• Semantic/episodic → procedural rule (promotePatterns, DEFAULT_PROMOTION_CONFIG): a tool/action sequence that succeeded ≥80% over ≥5 occurrences becomes a pinned rule. Below threshold it stays a fact (advice), not a rule (enforced).
• Demotion / decay: a rule whose live success rate drops (violations + failures, §4.4) loses confidence and, past a floor, is auto-unpinned — rules that stop working stop being enforced. This is what hand-maintained CLAUDE.md can't do.

3.3 Authority tiers (which memory wins)

When memories conflict, precedence is: workspace policy / human-pinned rule > org-curated fact > distilled procedural rule > semantic fact > episodic. Human-authored (incl. the seed CLAUDE.md) and explicitly-pinned rules are is_system/locked and never auto-demoted.

4. Rule adherence — making Stella obey, and proving it didn't violate

Recording rules is worthless if the agent ignores them. This is the part competitors don't have and the part that reuses the gate Stella already shipped ([[cli-claude-code-parity-stack]]: apps/cli/src/settings/ permission gate + hooks). Three enforcement tiers, defense-in-depth:

4.1 Tier 1 — Retrieve + inject (soft, every turn)

Before a turn, retrieve the active rule set for this context and inject it into the system prompt (a dedicated, cache-stable section):

• Procedural rules (pin) whose appliesTo matches the turn's files/domain/intent, ranked by confidence.
• High-confidence semantic facts relevant to the touched files (vector recall via agent.memory.recall / graph.search kinds=[memory], scoped to the files' :Feature/domain).
• Workspace policies (agent.memory.policy.read).

Retrieval is graph-local first (the down-synced DuckDB projection — zero latency, offline-capable) with a cloud agent.memory.recall fallback. This is the same recallContext() seam already in runAgent; we upgrade it from "recent episodics" to "applicable rules + facts."

4.2 Tier 2 — Gate (hard, per tool call)

This is the teeth. Stella's PreToolUse hook + permission gate (already built) is extended with a rule check: when the model proposes a tool call, evaluate it against active deny-shaped rules before it runs.

• A procedural rule can carry a machine-checkable guard, e.g. { rule: "never edit an applied migration", guard: { tool: "edit_file", denyPathGlob: "packages/database/migrations/*-applied/**" } }.
• The gate (reusing evaluateLocalPermission + the hooks runner) blocks the call and returns the rule text to the model ("⛔ blocked by rule: add a forward migration instead"), so the agent self-corrects mid-turn instead of shipping a violation.
• Rules without a machine guard fall back to Tier 1 (prompt) + Tier 3 (judge).

This means rules are enforced by the same mechanism as permissions and MCP tool gating — one coherent guard surface, not a second system.

4.3 Tier 3 — Verify + attest (post-hoc judge)

The existing completeness judge is extended to a compliance judge: given the diff + the active rule set, it returns { violated: ruleId[], evidence }. On a violation:

• The turn is marked non-compliant; in fleet/isolation mode the work can be held (not merged) pending the fix, reusing the worktree-integration gate.
• A negative episodic is recorded against the violated rule (outcome:"failure", causality→ruleId), which lowers the rule's success rate (§3.2 demotion) and is the audit artifact ("Stella violated rule X here, caught, corrected").

4.4 The adherence flywheel

Tier-2 blocks and Tier-3 catches both feed successCount/failureCount back into the rule. Rules that keep working get reinforced and rise in recall; rules that misfire decay and unpin. The guardrail tunes itself from real outcomes — no human re-curation. This is the answer to "ensure agents adhere and don't violate": retrieve → gate → verify → score → decay, on the same substrate that records the memory.

5. Sync architecture (CLI ⇄ cloud)

5.1 Reuse, don't rebuild

• Down (cloud→CLI): shipped — graph.export → local DuckDB projection (graph.pull.ts). Gives Tier-1 retrieval offline.
• Up (CLI→cloud): ride ADR-018's graph.sync.push for the execution + code-lineage delta, and engram's CRDT syncWithPeer for the memory delta. Both are content-addressed and idempotent, so retries and concurrent agents are safe.

5.2 What syncs where

5.3 Offline-first + prioritized

The CLI must work on a plane. All writes go to the local store immediately; sync is a background, resumable reconcile. prioritizeForSync + batchByPriority (already in engram) push high-salience, human-originated, rule-affecting records first; low-salience episodics may never sync (they decay locally). Merkle-tree diff (diffMerkleTrees) means a reconnect transfers only the delta, not the whole store. Vector clocks + OR-sets resolve concurrent writes from multiple agents/machines without a coordinator — critical because [[concurrent-main-commits]] shows many sessions run at once.

5.4 Tenancy + privacy

Namespaces ({org,workspace,session,agent}) scope every record; sync is org+workspace-scoped through the API key, enforced server-side like every contract. Memories are customer-owned and portable (Neo4j = the customer's carry-away graph, per the four-store law) — secrets/credentials are never stored as memory content (the noise filter + a redaction pass on episodic payloads).

6. The moat: binding code-agent executions to business processes

This is the section competitors structurally cannot copy, because they have no business ontology.

6.1 The new edges (greenfield)

(:Execution)-[:MODIFIED   {hunk, linesAdded, linesRemoved, contentHash}]->(:SourceFile)
(:Execution)-[:SERVED     {confidence, rationale}]->(:Feature)        // or :EntityNode (a process)
(:Execution)-[:DERIVED_FROM]->(:Execution)                            // fleet/revision lineage

SERVED is resolved by joining what Stella MODIFIED to the existing (:Feature)-[:IMPLEMENTS]->(:SourceFile) edges (already inferred from the code+connector graph). So: Stella edits billing/grants.ts → MODIFIED→ that file → which IMPLEMENTS← the :Feature{Billing Grants} → which the connector graph ties to the :EntityNode{Subscription} business object. The chain code change → feature → business process is computed, not guessed.

6.2 What this unlocks (the "cool things")

1. Process-aware impact analysis, pre-merge. Before Stella opens a PR: "this change touches code implementing the Invoicing and Dunning processes; 3 automations and the month-end-close workflow depend on it." Reviewers see business blast-radius, not just file diffs.
2. Process-scoped planning & retrieval. A goal like "speed up checkout" resolves to the :Checkout process → its IMPLEMENTS code + its past :Executions + the rules learned on it. The planner ([[cli-agent-fleet-subsystem]]) seeds tasks and assigns the right named agent ([[cli-claude-code-parity-stack]]) from real process context, not a grep.
3. Compliance & audit by business meaning. "Show every Stella execution that modified code serving a SOC2-relevant or PII-touching process in the last 90 days, with the rules it obeyed/violated." That's a one-hop graph query feeding the SOC2 evidence story ([[soc2-blocker-backlog]]) — auto-generated change-management evidence.
4. Business-process regression targeting. When code for the Payments process changes, select exactly the tests/e2e tied to that process (via IMPLEMENTS/PART_OF), instead of running everything — money-path tests first ([[testing-philosophy-hybrid-agent-e2e]]).
5. Cross-repo, cross-agent learning bound to the business. A rule learned while editing Payments in repo A applies when any agent edits Payments code in repo B, because the rule's appliesTo is the process/feature, not a path. No competitor's per-repo memory can do this.
6. "Explain this code" in business terms. Hover a file → "implements the refund step of the Returns process; last changed by execution E (served Returns, tests green); 2 rules apply here." The knowledgeNodeRef citation UX already exists for this.
7. ROI & drift reporting. Per business process: agent executions, cost, success rate, rules, open violations. Leadership sees "engineering effort per business capability" — derived, not surveyed.

6.3 Why this beats every competitor (summary)

7. Contracts & surfaces (capability-parity: contract → API → MCP → CLI)

New/changed capabilities (each gets a contract in packages/oxagen/src/contracts/, an API route, an MCP tool, and CLI wiring — [[no-drift-across-surfaces]]):

CLI: extend runAgent/the pipeline to write engram records + queue an execution; add oxagen memory list/show/sync, oxagen exec list/show, and surface rule blocks in the REPL. Reuse the settings permission gate + hooks for Tier-2.

8. Phased delivery (coordinate with ADR-018)

• Phase 0 — Land the transport. Merge ADR-018 up-sync (graph.sync.push) and confirm down-sync. (Other session; this spec waits on it.)
• Phase 1 — Memory write + sync. Wire the CLI agent loop to engram remember/assert/pin with the §3.1 noise filter; stand up agent.memory.sync (engram CRDT peer) and up-sync memories. Verification: write a fact in the CLI, see it in graph.search kinds=[memory] in the web app.
• Phase 2 — Execution lineage. execution.record + MODIFIED edges from the turn's filesTouched. Verification: run Stella on a file, query execution.lineage.get, see the :Execution→:SourceFile edge.
• Phase 3 — Business binding. SERVED inference (join MODIFIED × IMPLEMENTS), process.executions.list, impact-analysis surface. Verification: edit billing code → "served the Billing process" in the PR/UI.
• Phase 4 — Adherence loop. Tier-1 rule retrieval into the prompt, Tier-2 machine-guard gate (reuse permission gate), Tier-3 compliance judge + violation episodics + decay. Verification: pin a "no edits to applied migrations" rule, watch the gate block a violating edit and the judge attest compliance.
• Phase 5 — Consolidation & ROI. Scheduled distill/promotePatterns (Inngest), rule demotion/decay, per-process ROI reporting.

Each phase is independently shippable and additive; Phases 1–2 don't need 3–5 to deliver value.

9. Risks & open decisions

• Recall noise is the existential risk. If memory recall returns junk, the agent learns to ignore it and the whole flywheel dies. Mitigation: aggressive §3.1 filter, confidence/salience thresholds on recall, decay, dedupe. Treat recall precision as the headline metric.
• SERVED confidence. Inferred process binding will be imperfect. Ship it as a suggested edge (low confidence, inferred:true) routed through the existing semantic.edge.suggest approval flow before it's load-bearing for audit.
• Privacy of code as memory. Never sync secret-bearing payloads; redact episodic payloads; memories are customer-owned and deletable (GDPR erase path already exists).
• Open: (a) machine-guard rule DSL — start with the permission-rule syntax already shipped (Tool(glob)), extend only as needed. (b) Decay constants for procedural rules (separate from the memory half-life policy). (c) Whether :Execution lineage lives only in Neo4j or also mirrors a Postgres edge table for transactional joins. (d) Coordinate the agent.memory.sync peer contract with the ADR-018 author so memory + code-lineage share one push session.

10. Acceptance (definition of done for the vision)

A developer runs oxagen "add a refund cap to the returns flow" in repo A. Stella: retrieves the rules learned on the Returns process (incl. ones first learned in repo B), is blocked by the gate from editing an applied migration and self-corrects, opens a PR that says "modifies code serving the Returns process; 2 dependent automations; all Returns money-path tests green; obeyed 4 rules, 0 violations," and — back in the web app — a teammate sees that execution on the Returns process node, the new fact Stella learned, and the rule that now applies workspace-wide. No other coding agent on the market can produce that sentence.