Symphony Knowledge Graph for Agent Memory

A Symphony knowledge graph is an optional repository-intelligence layer around Symphony events, not a feature built into Symphony. It can help long-running coding agents retrieve revision-bound system facts and record verified outcomes, but it should never turn task logs or unreviewed agent guesses into permanent memory.

Agent Memory Runs on Three Different Clocks

The Symphony specification describes workflow, workspaces, and structured observability, not a graph or a durable-memory service. The useful architecture starts by separating three time scales so that an old task note does not masquerade as a current repository fact.

This is especially important for long-running agent programs. An issue may outlive a session; a repository relationship can change with every merge; a design decision can remain relevant for months. A single memory store without time and provenance will confuse those lifetimes.

Current task state

Task state answers what this issue is doing now: assigned, running, blocked, ready for review, or closed. It may include a workspace reference, current base revision, selected commands, and a handoff receipt. This state changes quickly and should have a short retention policy. It is not a substitute for a source of truth in code.

Current repository structure

Repository structure answers what the code says at a named revision: modules, call paths, declared interfaces, dependencies, test relationships, and generated-code boundaries. A graph can represent these relationships with source locations and extraction time. It must be refreshed when the revision changes; otherwise it is only a discovery lead.

Historical engineering decisions

Historical decisions answer why a constraint exists: a merge that changed an API, an approved design record, a rollback, or a review finding. This layer should contain only reviewed and attributable records. It is useful because code alone often cannot explain a compatibility or operational boundary.

What Belongs in a Knowledge Graph

Keep facts that can be checked and scoped: repository identity, commit, entity type, relationship type, source path, evidence link, owner, freshness timestamp, and confidence status. Examples include “this test covers this API contract at this commit” and “this design record superseded that decision.”

Do not store secret values, raw prompts, agent chain-of-thought, customer data, speculative architecture summaries, or a successful command without its environment context. A graph is not a data-retention exception. The Graphify hub is a useful neutral starting point for revision-bound code-relationship design.

Require an evidence model before ingestion. At minimum, a node or edge needs its source, repository and revision, extraction or verification date, owner, access classification, and retention class. The graph can then answer “where did this fact come from?” before an agent acts on it.

The data model can stay modest. A module node, a test node, a design-record node, and an issue or pull-request event can be enough when their relationships are precise. Avoid creating generic “context” nodes that obscure whether an assertion is code structure, a workflow event, or a human decision.

Follow Memory From Issue to Merged Pull Request

Symphony can provide a lifecycle in which an optional memory layer has places to read and write. The official materials support the orchestration events; the graph behavior below is a proposed governance model.

Retrieve relevant system facts

At intake, query for the task's affected modules, interfaces, owners, related tests, recent merged changes, and active dependency risks. Return source links and the revision used. A low-confidence relationship should be marked as a hypothesis and verified before it guides an edit.

Record verified outcomes

After review and merge, write compact receipts: the ticket, merged commit, validated test or CI evidence, decision reference, and facts that were confirmed or corrected. Do not auto-promote an agent's plan into shared memory simply because it produced a pull request.

Prefer append-only event receipts over broad rewrites of historical facts. They make it possible to trace a decision from issue to merged pull request without pretending that a later summary was always true. A reviewer can approve the narrow assertion that a named test passed at a named commit.

Retire facts invalidated by the merge

When a merge changes an interface or replaces a decision, create a supersession or invalidation edge rather than leaving conflicting records alive. If no reviewer has confirmed the change, retain it as task-local status, not as repository truth.

Define Read and Write Permissions for Agents

Give agents broad read access only when repository policy permits it, and make writes narrower than reads. A planner may read current facts; an implementer may attach evidence to a task; only a trusted review or merge process should publish durable relationships. The SPEC makes trust implementation-defined, so this separation is a local governance decision, not a default Symphony guarantee.

Write receipts should be idempotent and attributable. If an agent retries a task, the graph should link the retry to the same ticket and evidence instead of creating a second unqualified “success.” If a human corrects an edge, record the correction rather than overwriting the original observation without history.

For the packet that carries facts between roles, read Symphony Context Engineering. For coordination patterns beyond one orchestration run, see Multiple Ralph Loops Shared Context.

Resolve Stale, Conflicting, and Unsupported Memories

Every retrieved fact needs a revision, source, extraction date, and confidence. If two facts conflict, prefer the current authoritative source, retain provenance for the conflict, and escalate when it changes a safety decision. If a fact has no source, keep it outside the graph or label it explicitly unverified. A graceful failure is safer than a fluent answer that cites obsolete structure.

Confidence should describe evidence quality, not model confidence. For example, a direct parser result at the current revision may be high confidence, while an old review comment is historical context. Never use a high score to bypass source review; the score should prompt the right verification step.

When Durable Agent Memory Creates More Work Than Value

A graph adds ingestion, access control, freshness checks, review work, and incident response. It earns that cost when repeated work crosses module boundaries, important decisions are difficult to rediscover, and teams can name owners for facts. It is probably premature when the repository is small, work is mostly isolated, or basic tests and code ownership are still unreliable.

Start with read-only retrieval for one recurring task type. Measure whether it reduces missed dependencies or review clarification, then add controlled writes. Do not claim that a graph automatically saves tokens or improves accuracy; those outcomes depend on coverage, retrieval quality, and governance.

An adoption review should include the cost of extraction, freshness failures, privacy review, and reviewer time, not only model-token measurements. If the graph cannot point to a decision that it made easier to verify, keep the architecture simpler.

The goal is not a comprehensive digital twin of the organization. It is a bounded evidence layer that lets the next agent and reviewer verify a material repository relationship without re-creating the same investigation from scratch.

FAQ

How long should orchestration logs be retained?

There is no universal Symphony retention rule in the SPEC. Set retention by security, legal, operational, and debugging needs; redact sensitive values and keep durable graph facts separate from raw logs.

Must agents cite the graph facts they use?

Yes for decision-driving facts. A source path, revision, and retrieval time let a reviewer determine whether the context is current enough to rely on.

How should abandoned branch knowledge be removed?

Mark branch-specific task records as abandoned or expired. Do not delete verified historical evidence merely because a branch closed; retire only facts that are invalidated or no longer permitted to retain.

Who can approve new historical decision records?

Use the same authority that approves the underlying decision: designated maintainers for code facts, owners for service boundaries, and security or architecture reviewers for policy records.

Which evidence should never become persistent memory?

Secrets, private customer content, raw unredacted logs, speculative summaries, and unreviewed agent reasoning should not become persistent shared memory.