A Codebase Should Remember: Repository Memory Comes to Synaptic

A Codebase Should Remember: Repository Memory Comes to Synaptic

On August 5, 2026, we plan to release repository memory for Synaptic and Synaptic Cloud. The new memory layer preserves source-grounded decisions, failed attempts, regressions, incidents, procedures, and verification outcomes, then brings the relevant evidence back when a developer or coding agent is about to change the same part of the system.

The result is not a model with a larger memory. It is a better engineering process: the current code graph still explains how the system is connected, while repository memory explains what happened here before, why a constraint exists, and which approaches have already failed.

What is Synaptic repository memory?

Synaptic repository memory is a durable, revision-aware history layer connected to the code graph. Every memory cites a source artifact—such as a commit, ADR, pull request, review, CI run, incident, or agent task—and can be anchored to the symbols and files it affected.

That distinction matters. A coding agent can already read source, search text, and ask Synaptic for callers or change impact. Those operations describe the repository as it exists now. They do not necessarily explain:

• why a seemingly awkward boundary is intentional;
• which implementation was tried and rolled back six months ago;
• which incident exposed a hidden runtime dependency;
• which verification command caught the last regression; or
• whether an old decision has since been replaced.

Repository memory gives those questions a structured, queryable answer without putting an entire project history into the model's context window.

The graph remains the current truth

The most important design decision in this release is what repository memory does not do.

Memory records do not become graph edges. Synaptic keeps them in a separate temporal overlay under .synaptic/memory and joins them to current graph results through revision-aware symbol and path anchors.

This prevents a historical observation from masquerading as a current dependency. If an incident report says that refresh_token once called a legacy session service, that statement should not re-create a call edge after the code has changed. It should remain historical evidence, attached to a revision and a source.

The separation gives the two stores clear jobs:

Current code graph	Repository memory
What symbols exist now?	What happened around them before?
What calls, imports, implements, or references what?	Which decisions, failures, incidents, and outcomes apply?
What is the likely blast radius of this edit?	What should we be careful not to repeat?
Rebuilt as the repository changes	Survives graph rebuilds and preserves superseded history

At query time, Synaptic can combine both answers. get_node, affected, and predict_edit attach a bounded memory-evidence block for the selected subject. predict_impact, working_changes_impact, and get_pr_impact aggregate that evidence across a complete file set, deduplicate it, and retain the files or symbols that matched.

Warnings are shown first, then governing decisions, then ordinary history. Every entry keeps its source URI, confidence, verification status, and revision.

Why this improves reasoning

Repository memory does not change the underlying language model, and it does not make generated code automatically correct. It improves the evidence and the sequence of checks available to the model.

That is a practical reasoning improvement in five ways.

1. It turns “this looks right” into “this fits what we know”

Source code can show that a branch exists without explaining why it exists. An ADR, incident, or review finding can supply the missing premise.

Before proposing an edit, an agent can ask explain_decision for the active architecture decisions, invariants, conventions, and procedures attached to a symbol or file. Instead of inferring intent from implementation shape alone, it can compare the proposed change with an explicit, cited constraint.

That reduces a common source of low-quality code: locally elegant edits that quietly violate system-level decisions.

2. Negative experience becomes reusable evidence

Most repository context systems are good at describing what succeeded. The expensive knowledge is often what failed.

Synaptic records failed attempts, regressions, incidents, failed CI runs, and rejected review findings as first-class memory. known_pitfalls retrieves those records directly, and impact tools place relevant warnings beside structural blast-radius evidence.

This lets an agent distinguish “an approach I have not seen” from “an approach this team already tried and rejected for a documented reason.” Avoiding the second category improves code quality without asking the model to rediscover the failure through another patch.

3. Reasoning survives prompt and agent boundaries

A prompt ends. An agent session is replaced. A graph is rebuilt. A file moves. The repository's engineering history should survive all four.

Memory records are immutable and idempotent. Corrections append a new record with a supersedes relationship rather than rewriting the earlier observation. Normal retrieval hides superseded and retracted records, while an explicit history query can still inspect them.

Git ingestion retains old and new paths for renames and copies. A conservative symbol-rename pass also connects old and new declaration names across revisions. That means a future query can still find the lesson attached to the old name after the code has moved on.

The benefit is continuity: a second agent can begin with the evidence produced by the first instead of repeating its exploration and mistakes.

4. Verification travels with the conclusion

A summary without evidence is just another assertion. Each memory record must retain at least one source artifact, and it can also carry verification status, commands, notes, confidence, commit, branch, and occurrence time.

This changes how an agent should use the result. A passed verification outcome can be treated differently from an unverified observation. A failed test command can be rerun. A consequential decision can be checked against its ADR instead of accepted from a generated summary.

The source remains visible in both human-readable MCP output and structured content, so the shortest answer still contains a path back to the underlying evidence.

5. Review starts with both structure and experience

Static impact analysis is necessary, but it can only reason from relationships represented in the current graph. Historical evidence can reveal risks that are real even when they are not a current call or import.

When Synaptic forecasts an edit, reviews a working tree, or calculates pull request impact, the result can now combine:

• the current dependency blast radius;
• tests and public APIs at risk;
• prior regressions in the changed files;
• governing decisions and procedures;
• similar earlier changes and their outcomes; and
• the verification evidence attached to those changes.

That gives a reviewer or coding agent a stronger basis for test selection, implementation choices, and review focus. It also makes the reasoning easier to audit: each warning explains why it appeared and where it came from.

What gets remembered

Synaptic can capture repository memory from several sources:

• exact Git commits, including changed-file and rename lineage;
• ADRs, decisions, procedures, runbooks, playbooks, and repository conventions;
• issues, pull requests, reviews, CI runs, incidents, releases, customer reports, regressions, and agent tasks through a canonical artifact format;
• deterministic summaries of graph communities; and
• verified change outcomes recorded by a trusted agent or CI workflow.

Installed commit and merge hooks capture the triggering commit SHA before background work begins, update the graph, ingest that exact revision, and refresh repository documents and community summaries. Capturing the revision first avoids attributing a later commit to an earlier hook event.

For trusted local workflows, the CLI exposes the complete lifecycle:

synaptic memory refresh --root .
synaptic memory search "session refresh deadlock" --symbol refresh_token
synaptic memory record \
  --idempotency-key agent-task-42 \
  --title "Refresh lock attempt failed" \
  --summary "Holding the session mutex across network I/O deadlocked refresh." \
  --outcome failed \
  --source-uri agent://task/42 \
  --symbol refresh_token \
  --verification-status failed \
  --verification-command "cargo test auth_refresh"

MCP adds five read-only tools by default: search_memory, explain_history, find_similar_change, known_pitfalls, and explain_decision.

The only write tool, record_change_outcome, is absent unless an operator explicitly starts the server with --allow-memory-write. It is separately gated from command execution and requires a stable idempotency key plus a source URI.

Local by default, team-aware by design

In Synaptic, memory remains local and offline by default. Records live beside the repository, and deterministic lexical and symbol retrieval works without an embedding service or external database.

For team use, records carry private, repository, or workspace scope. The configured principal—not a caller-supplied tool argument—determines which records are visible. Authorization is applied before totals, candidate diagnostics, supersession, or rendering, so hidden records do not leak through metadata.

Stores can be federated for reads, and teams can exchange checksummed bundles that preserve source, lifecycle, ownership, and scope. Identical records deduplicate; conflicting content under the same immutable ID fails closed.

Synaptic Cloud will bring the same memory-assisted reasoning to hosted project graphs, making source-grounded project history available through the team's managed MCP path. Local Synaptic keeps the filesystem-first workflow; Synaptic Cloud provides the shared project experience. Cloud rollout and administration details will be published with the August 5 release notes.

How we are validating the release

Repository memory has its own retrieval benchmark because a memory system is only useful if it can localize the right evidence without flooding the prompt. The evaluator reports recall at one and five, mean reciprocal rank, candidate fraction, and per-case misses, with thresholds that can fail CI.

In the current pre-release tree, 34 focused library, MCP integration, and CLI tests pass. The checked-in release-validation corpus contains two source-localization cases: the temporal-overlay ADR and the release procedure. Both rank the expected source first, for recall@1 of 1.0 and mean reciprocal rank of 1.0. The inverted index narrows those searches to an average of 3.45% of the 116 records visible to the restricted benchmark principal.

That release gate is intentionally small and operational, so we also ran the pre-release build on the pinned source of six real developer tools: Sourcegraph, Cody, CodeQL, Joern, Aider, and graphify. Together, the supported source in those checkouts produced 42,599 files, 5.32 million lines, 420,065 graph nodes, and 991,356 edges.

For the memory test, Synaptic ingested 50 real first-parent commits from each repository, refreshed document and community memory, compacted the stores, and evaluated 59 deterministic source-localization cases built from commit intent and a changed path. Across 300 commits and 11,819 records, the pooled results were:

• recall@1: 94.92% (56 of 59 cases);
• recall@5: 98.31% (58 of 59);
• mean reciprocal rank: 0.9619; and
• mean candidate fraction: 10.24%.

Five repositories placed every expected commit first. Aider produced the useful counterexample: six of nine cases ranked first, eight ranked in the top five, and one missed the top five. We keep that miss in the pooled result.

The stress run also found boundaries worth publishing. Sourcegraph and CodeQL exceeded the CLI's default graph node and file-size caps, so their memory runs used explicit uncapped settings. The first CodeQL run also overflowed a spawned parser worker's default stack. We fixed that in the product with a dedicated 64 MiB-stack extraction pool; the final whole-repository validation completed without a stack environment override. These are operational findings from the pre-release tree, not defaults hidden inside an aggregate.

The same review exposed a more important reasoning gap: Synaptic discovered QL files but did not parse them. The August 5 build now treats CodeQL QL as a first-class source language. On the pinned CodeQL checkout it extracted 13,202 .ql and .qll files into 148,902 QL-tagged file and symbol nodes, bound 30,797 imports to real source files, and built overload-aware predicate call edges. Every complete QL file parsed cleanly; the only two parser-error files were training templates with /* TBD */ predicate bodies.

That coverage matters for code quality because repository memory is only as useful as the current structure it can attach to. Path-scoped QL identities prevent common names from unrelated CodeQL packs being merged. Import aliases, predicate arity, typed signatures, visibility, inheritance, and contextual type references give impact analysis and coding agents better evidence about which query or library a change can affect. Direct import-backed calls remain extracted evidence; a unique corpus-wide fallback is marked inferred, so the graph preserves uncertainty instead of presenting a guess as fact.

This is structural QL source support for navigation, impact analysis, and repository reasoning. Synaptic does not compile or execute QL, create CodeQL databases, or reproduce CodeQL's data-flow and taint-analysis engine.

The external cases are still localization tests, not a benchmark of model intelligence or patch quality. They are derived from real commit subjects and paths, not hand-written incident questions. A causal claim about better code would require memory-on versus memory-off agent tasks, test outcomes, and blinded patch grading. What this run establishes is narrower: the new memory layer can retrieve source-grounded history with high measured recall and bounded candidate sets across materially different real repositories.

What repository memory does not promise

An honest boundary is part of the feature.

• It does not replace reading source code or the cited artifact.
• It does not turn historical summaries into current structural facts.
• It does not guarantee that every relevant event has been captured.
• It does not use an embedding model or learned reranker in this release.
• It does not make an agent's final judgment automatically correct.

Memory summaries are evidence pointers, not authority. For consequential changes, an agent should inspect the source, consider confidence and verification, and use superseded records only when it is deliberately investigating history.

Better code starts before the edit

Code quality is often decided before the first line changes: when the developer or agent identifies the real constraint, notices the prior regression, chooses the right test, or abandons an approach that already failed.

Synaptic already gives that process a structural foundation through a persistent code graph. Repository memory adds the missing temporal dimension. The graph says what the system is. Memory says what the team learned while building it.

Repository memory is planned for Synaptic and Synaptic Cloud on August 5, 2026.