Ralph Knowledge Graph Integration

A repeated coding loop benefits from a stable task and fresh inspection of the repository. It does not benefit from reconstructing the same module boundaries and dependency paths from scratch. A code graph can reduce that orientation cost, but only if it returns scoped, current, and verifiable evidence.

This article describes a proposed Ralph knowledge graph integration. It is not a built-in feature of Ralph, Anthropic’s Ralph Loop plugin, or Ralph Orchestrator. The design keeps the graph read-only to the implementation loop, treats results as candidates rather than truth, and preserves source inspection and tests as backpressure.

Before Adding a Knowledge Graph

Establish the failure you are trying to fix. If iterations repeatedly miss indirect consumers, reopen the same ownership files, or choose the wrong tests, structural retrieval may help. If the repository is small and module boundaries are obvious, a graph may add more maintenance than value. Start from observed retrieval failures, not the attractiveness of the architecture.

A Ralph code graph is justified only when those failures require repeatable relationship queries. Define that need before choosing a schema, transport, or vendor.

Define the Ralph implementation too. Huntley’s original pattern uses an outer loop, a stable plan, one task per iteration, and executable feedback. The snarktank implementation launches a fresh Amp or Claude process for each iteration. Anthropic’s official plugin continues in the current Claude Code session through a Stop hook. Those choices determine when graph context is fetched and how long it remains valid.

Freeze an integration contract before connecting tools. It should name the task ID, active commit, allowed read and write scope, graph schema version, freshness policy, maximum result size, and required provenance. The graph can orient the loop; it cannot expand the authorized task.

A Ralph knowledge graph database should also have a clear ownership model. Decide who builds it, who can query it, which repositories and paths it includes, and how index failures are reported. Do not let an empty or partial result silently mean “no dependency exists.”

Map Ralph Tasks to Graph Queries

A Ralph code graph query should turn acceptance criteria into explicit structural questions. “Change the retry policy” might become: which module defines the client, which entry points call it, which wrappers override the policy, and which tests exercise timeout and retry behavior? “Rename a public type” might request its definition, implementations, imports, generated bindings, and external package boundaries.

Each query should begin narrow. Retrieve the owner, definition, and direct relationships first. Expand to transitive consumers only when the task or source evidence requires it. This prevents a graph traversal from becoming another repository dump.

A Ralph knowledge graph database should expose the same narrow query boundary to every iteration. It should not turn a request for one owner or relation into an unrestricted graph export.

The result contract matters. Each node or edge should carry a file path, symbol, relationship type, active or indexed commit, and index version. If the system assigns confidence or marks an edge as inferred, expose that status to the agent. A path with no source provenance is an architectural suggestion, not evidence.

Keep text search beside graph retrieval. ripgrep deterministically searches line-oriented text and, by default, respects ignore rules while skipping hidden and binary files. It can find literals, configuration keys, and registration strings that a static graph may not model. The graph answers relationship questions; text search answers text questions.

Retrieve Modules, Dependencies, and Tests

A Ralph knowledge graph database needs only the relationships required by its approved task classes. The minimum useful graph often contains modules, definitions, imports, references, calls, implementations, and test relationships. Repository-specific edges may connect schemas to generated files, routes to handlers, migrations to models, or packages to owners. Add them only when extraction is reliable enough to support the tasks that need them.

For a change to an interface, the loop might retrieve the defining module, every implementation, direct consumers, package-boundary crossings, and related tests. It should then open those source locations. If a language feature, macro, runtime registry, or dependency-injection container makes an edge uncertain, the query result should say so and point to the configuration that needs manual inspection.

Test mapping deserves particular caution. File proximity and name similarity are weak evidence that a test covers a behavior. Prefer relationships derived from imports, executed call paths, build metadata, or an explicit repository mapping. A human owner should validate mappings used for security, migrations, and public contracts.

Graphify is one possible codebase graph layer for these queries. The defensible claim is that structure-aware retrieval may help an agent assemble a smaller context slice in repositories where relationships are otherwise expensive to recover. It does not guarantee complete architecture, lower cost, or safer edits for every codebase.

Feed Results Into the Implementation Loop

At the start of an iteration, pass the task, current commit, and write scope to a read-only graph query. Return a ranked context packet containing the likely owner, entry points, dependencies, tests, and provenance. The agent should confirm the packet against the checkout before planning edits.

Next, use the verified relationships to choose files and checks. The graph may suggest that an interface has three implementations and two test suites. The agent opens all three implementations, confirms which tests exercise the changed contract, and uses exact search for configuration or string-based registration that the graph might miss.

After the edit, run the repository’s normal tests, builds, linters, type checks, or static analysis. In Ralph’s model, these checks provide backpressure. They do not prove that the graph was complete, but failures can reveal a missed edge and supply data for improving the index.

Persist only the useful task-scoped findings between iterations: verified owner, relevant paths, failed retrieval assumptions, and the commit against which they were checked. Do not copy an entire subgraph into an append-only prompt. Query again when the repository state or task changes.

Claude Code supports external tool connections through MCP, which is one possible transport for a graph query. That does not mean the Anthropic Ralph plugin or any other Ralph implementation includes a graph service by default.

Drift, Access, and Review Risks

Drift is the primary technical risk. An index built at commit A can return plausible but wrong relationships at commit B. Require a matching commit or an explicitly documented delta, and fail closed when provenance is missing. Rebuild or incrementally update after structural edits, generation changes, or schema-version changes.

Access is separate from write scope. A graph may contain paths the current agent is not allowed to read, or reveal names across repository boundaries. Apply source permissions to indexing and retrieval. Even when a result is readable, it does not authorize the loop to edit that module.

Review should expose the graph’s role. For material changes, keep the query, returned source locations, index version, relationships the agent verified, and known blind spots. Reviewers should be able to reproduce the retrieval path and challenge a missing consumer without trusting an opaque summary.

Ralph Orchestrator requires an additional distinction. Its parallel-loop documentation describes worktree-isolated loops, and its MCP server exposes orchestrator state as an inbound workspace-scoped control plane. That is not a native outbound bridge to a code graph. A graph connection would be a separate integration with its own permissions and lifecycle.

Finally, audit false positives and false negatives on real tasks. If graph retrieval frequently needs broad correction, simplify the graph or improve extraction before making it a default dependency.

FAQ

What graph facts should stay read-only?

Derived definitions, imports, calls, implementations, test mappings, and ownership edges should be read-only to the implementation loop. The loop can report a suspected error, but the graph should be rebuilt from source or corrected through a reviewed annotation workflow. This preserves the distinction between evidence and agent memory.

Who validates test mappings?

The code owner or team responsible for the behavior should validate high-impact mappings. Automated extraction can propose tests, but a mapping should not be treated as coverage proof unless its basis is clear. Security, migration, and public-interface changes deserve explicit human review.

When should the graph be rebuilt?

Rebuild or incrementally update it after relevant commits, structural refactors, dependency or generation changes, parser upgrades, and schema-version changes. Force a rebuild when provenance does not match the active checkout or when a verified false negative suggests the index is incomplete.

What is the Ralph Wiggum strategy?

It is an iterative coding-agent approach that repeatedly works from a task or plan and uses repository changes plus executable checks to make progress. Implementations vary in prompt handling, process lifetime, persisted state, stopping conditions, and concurrency. A code graph is an optional extension, not part of the definition.

Conclusion

A useful Ralph knowledge graph integration is a narrow retrieval boundary, not a second source of truth. Map each task to structural questions, return a small packet with provenance, confirm it in source, and keep standard tests and review in control of the edit.

Build the graph only where repeated failures justify it, and document freshness and permissions as part of the integration. For the wider structural model, see knowledge graphs for AI coding assistants. For sharing verified context across concurrent workers, see multiple Ralph loops and shared context.