How should you design memory architecture for coding assistants?

Coding assistants already carry several kinds of memory, whether teams notice or not. The context window holds the live session. Local instruction files hold stable rules that must load every time. The repository holds code and docs the agent can read on demand. What usually goes missing is durable, searchable memory of decisions, rejected alternatives, and personal habits that do not belong in a two-hundred-line always-on file. Weaviate Engram is the layer that fills that gap for coding workflows. This chapter maps a practical memory architecture for coding assistants: how file memory and Engram divide labor, which topics and scopes fit developer work, how personal preferences stay separate from shared repository decisions, when to recall versus when to write, and how a custom assistant loop should call Engram without turning memory into optional tool theater.

The architecture is not “remember everything.” It is “put each fact in the layer that can actually keep it honest.”

Why do local memory files and Engram need different jobs?

Always-on files are excellent for conclusions. Preferred languages, formatting rules, and non-negotiable safety constraints should stay tiny, human-edited, and guaranteed in context. They fail when the useful knowledge is the story behind a conclusion. Why the team abandoned a queue library. Which migration path was tried and rolled back. What framing shifted mid-spec. Those memories are too large for a permanent line budget and too important to reconstruct from vibes.

Engram’s own coding-assistant evaluations made the split concrete. Sessions with grounded recall recovered decision archaeology faster and with fewer invented details than cold sessions that only had static files. The same work also showed a failure mode: when recall depended on the model choosing a tool, forward-looking planning prompts often skipped memory entirely. Architecture therefore has two requirements. Stable rules stay in files. Cross-session reasoning stays in Engram. Recall should be infrastructure, not a courtesy the model may ignore.

That raises the design question readers usually ask next. If Engram holds the durable layer, how should that layer be carved so a code review prompt does not drown in unrelated personal trivia?

Which topics and scopes shape coding memory without turning it into sludge?

Engram topics are magnets. For coding assistants, the docs’ own example pair is a strong starting shape. A UserKnowledge topic captures personal details and preferences. A tech_stack topic captures languages, frameworks, and libraries. The Coding Assistant project template seeds topics in that spirit so extraction knows what to pull from session transcripts. You can refine descriptions further for communication style, workflow habits, or domain context if your team needs sharper magnets.

Scopes decide who can influence those memories. User-scoped topics keep one developer’s preferences from leaking into a colleague’s session. Property scopes such as codebase or repo_name add soft isolation so memories written while working on one service do not dominate recall in another. On write, required properties must be present. On search, including a property narrows results. Omitting it widens recall across a developer’s repos when you are doing cross-project archaeology.

Teams often need a second group for shared procedural memory. Personal tone preferences stay user-scoped. Repository-level decisions that every contributor should inherit can live in a continual-learning or project-wide topic with no personal user_id, or with a property that names the repo rather than the person. That is the same privacy-versus-skill split support agents use, applied to developers. A dislike of verbose comments is personal. A signed choice to keep stitch-timing deterministic is shared product truth.

When should a coding assistant recall, and when should it write?

Once topics exist, timing becomes the next failure point. Session start is the highest-value recall moment. A broad query about the active codebase primes the model before the first user message. Per-turn recall can follow with the latest prompt as the query, filtered by relevancy so only strong matches enter context. Mid-session recall is most useful for decision archaeology, cross-repo references, and resumes after a gap. Writing should be fire-and-forget into Engram’s async pipeline. Blocking the editor while extraction finishes teaches people to turn memory off.

Capture cadence matters too. Significant moments deserve an explicit save: a decision locked, a direction changed, a failing approach abandoned. Lightweight periodic saves protect against abrupt session clears. End-of-session summaries help when the thread was long. Short, focused memories retrieve better than giant dumps. Engram will extract and reconcile against topics either way, but dense paragraphs are harder to rank than crisp facts.

Working memory still belongs in the live context window. Tool traces, open diffs, and the current plan should not all be promoted into durable Engram topics. Topic descriptions are the filter. If a magnet does not ask for scratchpad noise, the pipeline should leave that noise behind.

What does this architecture look like in an assistant loop?

Plugins can hide the wiring. Custom coding tools must show it. Before generation, search Engram with the developer id and the active codebase property. Restrict topics when the task is narrow, such as tech stack only for a dependency review. After the exchange, add the conversation turn and continue. Wait on run status only in debug paths.

Consider a bindery firmware team whose assistant helps with stitch-timing controllers. The desk id scopes repo memory. The engineer id scopes personal habits.

import os
from engram import EngramClient
from engram.types import HybridRetrieval

client = EngramClient(api_key=os.environ["ENGRAM_API_KEY"])

engineer = "dev.soren.park"
repo = "bindery-stitch-desk-5"

# Session-start priming for this codebase.
hits = client.memories.search(
    query="Stitch timing defaults, rejected interrupt schemes, test harness notes",
    user_id=engineer,
    group="default",
    retrieval_config=HybridRetrieval(limit=6),
    properties={"codebase": repo},
    topics=["tech_stack", "UserKnowledge"],
)
memory_block = "\n".join(f"- {m.content}" for m in hits)

turn = [
    {
        "role": "user",
        "content": (
            "On bindery-stitch-desk-5 we keep stitch interrupts cooperative, "
            "not preemptive. Last month's preemptive ISR approach jittered "
            "page registration. Prefer short patches and pytest over ad-hoc scripts."
        ),
    },
    {
        "role": "assistant",
        "content": (
            "I will treat cooperative stitch interrupts as the default on "
            "bindery-stitch-desk-5, avoid reopening the preemptive ISR path, "
            "and keep changes small with pytest coverage."
        ),
    },
]

# Durable write: personal preference + repo decision extract into topics async.
run = client.memories.add(
    turn,
    user_id=engineer,
    group="default",
    properties={"codebase": repo},
)
print(run.run_id, run.status)
print(memory_block)

Hybrid retrieval helps because coding memory mixes exact identifiers with paraphrased intent. The codebase property keeps stitch-desk facts from colliding with an unrelated service the same engineer touched yesterday. Topic filters keep a dependency review from loading unrelated personal scheduling notes. If the team later adds a project-wide playbook group for shared firmware lessons, the loop can search that group without user_id while still searching personalization with one.

Bounded topics remain useful for singular cards. A per-user profile that must always enter the system prompt can be fetched rather than hoped for in search rankings. A per-session summary scoped by session id can update in place while unbounded topics accumulate discrete decisions over months.

How do teams keep personal style from becoming accidental law?

The last architectural risk is social, not technical. Coding assistants blur individual taste and team convention. Engram scopes make the boundary enforceable. User-scoped topics never return another developer’s private preferences. Shared decisions need an explicit project-wide or repo-scoped topic, not a hopeful copy of one person’s notes file. Search tests should prove the wall: store a quirky style rule under engineer A, search as engineer B, assert it does not appear.

File memory still plays its part. Keep the always-on checklist short enough to stay true. Put the archaeology, the rejected paths, and the evolving rationale in Engram. Let the Coding Assistant template supply starter magnets, then tighten descriptions as false positives appear. Prefer hooks or deterministic session callbacks over “please remember to search” instructions. Prefer async writes over blocking waits. Prefer property-scoped recall for the active repo, with an intentional widen when the question is historical.

A coding assistant with this memory architecture starts fewer sessions cold, invents fewer plausible-but-wrong histories, and keeps personal taste from rewriting the team’s contracts. Our next chapter, How should you design memory architecture for personal productivity agents?, leaves the repository and asks how the same Engram layers should organize goals, routines, and private life context for agents that help one person across many days rather than one codebase across many commits.