Source-linked AI summary

Stratum: Repository Memory for Coding Agents Beyond the Context Window

Yuvraj Sehgal, Mahsa Panahandeh, Naser Ezzati-Jivan

arXiv:2610.36153v1cs.SEcs.AI

TL;DR

Coding agents need persistent, experience-aware repository memory because knowledge must survive independent sessions, while static relationships leave many co-edited files disconnected. STRATUM stores structural, historical, and agent-written experiential knowledge beside the repository in a tiered memory hierarchy. With inherited notes (B), the reader succeeded in 21 of 24 trials at 4.5× lower median input-token cost than retrieval-only baseline (A), which succeeded in 6 of 24.

  • Problem

    Coding agents need persistent, experience-aware repository memory because knowledge must survive independent sessions, while static relationships leave many co-edited files disconnected.

    Source: §I · p. 1
  • Method

    STRATUM stores structural, historical, and agent-written experiential knowledge beside the repository in a tiered memory hierarchy.

    Source: §I · p. 1, A. Storage and Controller · p. 2
  • Results

    With inherited notes (B), the reader succeeded in 21 of 24 trials at 4.5× lower median input-token cost than retrieval-only baseline (A), which succeeded in 6 of 24.

    Source: B. E5: Does Inherited Memory Prevent… · p. 4
  • Takeaways & Limitations

    The authors conclude that long-lived agent memory should live outside the model, with repository knowledge organized to support selection across sessions.

    Source: §I · p. 1, §VIII · p. 5

    The E5 experiment did not control the quality of the writer's notes.

    Source: §VII · p. 4

Abstract

from arXiv · show

Context windows have grown a thousand-fold, yet coding agents still start every session with no memory of their past work. They re-read files, retry failed approaches, and forget root causes they established hours earlier. This is not a context-length problem but a memory-architecture problem. Our hypothesis: coding agents need persistent, experience-aware repository memory, so that knowledge survives from one session to the next. Three measurements on real repositories motivate the design. First, mid-size projects already exceed the largest production context windows, and storing knowledge inside the model's key-value (KV) cache costs $10^4$ to $10^5$ times more bytes than storing it as indexed text. Second, across 752 real bug-fix commits, the median fix edits two files, and these files plus their direct imports amount to less than 10% of the repository; the bottleneck is selection, not capacity. Third, even with transitive import reachability and test links, 47% of co-edited file pairs remain structurally disconnected; the knowledge needed for selection must be mined from history and experience. We sketch Stratum, a tiered memory that lives with the repository and serves it through page-safe tools: every response states what was returned, what remains, and what it cost. Retrieval over a store of one million nodes takes 1.7 ms at the median. In a multi-session experiment on eight real bugs, a fresh agent that inherited a prior session's memory, written by a different model, identified the root-cause file in 21 of 24 trials versus 6 of 24 for a retrieval-only baseline (Fisher $p<10^{-4}$), at 4.5x lower median token cost. With the notes of all eight investigations pooled in one store, success remained 8/8.

I. INTRODUCTION

The paper argues that coding agents need persistent, experience-aware repository memory because context capacity does not preserve knowledge across sessions. Three repository measurements motivate a memory layer that combines a tiered store with agent-controlled, page-safe retrieval.

I. INTRODUCTION

  • Django contains 6.2M tokens—six times the largest production context window—and one billion tokens cost about 300 TB as 70B-model fp16 KV state versus about 4 GB as indexed text.The KV representation is model-specific and must be rebuilt when the model changes.Source: §I · p. 1
  • Across 752 bug-fix commits, the median fix edits two files, whose one-hop import closure spans 2.7–9.9% of repository code.The closure is only a proxy for required context and omits configuration, runtime, and documentation dependencies.Source: §I · p. 1
  • Even after transitive imports and test links, 47.3% of co-edited file pairs remain disconnected; version history and agent experience supply additional selection knowledge.Co-edited pairs are 26× more likely than random pairs to share a direct import edge.Source: §I · p. 1
  • STRATUM joins a memory hierarchy with mining repository relationships, storing structural, historical, and experiential knowledge beside the repository and exposing page-safe tools with explicit pagination and budget state.The agent, rather than a lossy heuristic, decides what enters its context.Source: §I · pp. 1–2

II. MOTIVATING STUDY

The motivating study measures repository scale and code-maintenance structure across six active open-source repositories.

II. MOTIVATING STUDY

  • Three measurements were conducted on Django, Flask, Redis, requests, scikit-learn, and Vue core.The study counted tokens using the cl100k_base tokenizer.Source: §II · p. 2
  • Token counts used the cl100k_base tokenizer.Source: §II · p. 2
  • Scripts and raw results are available in the replication package.Source: §II · p. 2

A. E1: The Cost of Model-Resident Knowledge

The motivating study finds that repository knowledge is costly to keep in model state, while the code directly connected to a typical fix is a small fraction of the repository.

A. E1: The Cost of Model-Resident Knowledge

  • One billion tokens require about 4 GB as text but 119 TB, 298 TB, or 469 TB as fp16 KV state for 8B-, 70B-, or 405B-parameter models, respectively.This is a representation-cost bound, not a claim that repositories are stored as KV state; the authors conclude long-lived memory must live outside the model.Source: A. E1: The Cost of Model-Resident… · p. 2
  • The six repositories contain 17.6M tokens of tracked source, documentation, and configuration in 70 MB of text.Measured text density is 4.17 bytes per token.Source: A. E1: The Cost of Model-Resident… · p. 2

B. E2: The Working Set of a Real Bug Fix

  • A median bug fix edits two files, and the one-hop closure spans 2.7% of Django's Python code, 4.6% of scikit-learn's, and 9.9% of Flask's.The closure measures directly connected code, not additional needs such as configuration, fixtures, runtime knowledge, or rationale.Source: B. E2: The Working Set of a Real Bug Fix · p. 2

C. E3: What Static Structure Cannot See

The study finds that static code relationships leave many co-edited files disconnected, motivating STRATUM's use of historical and experiential memory alongside parsed structure.

C. E3: What Static Structure Cannot See

  • The analysis examined 3,695 co-changed file pairs from 852 commits, checking direct imports, transitive reachability, and test-to-source name links.Direct imports connected 23.5% of pairs; transitive reachability raised this to 52.0%.Source: C. E3: What Static Structure Cannot See · p. 2
  • Test-to-source name links raise the share only to 52.7%, leaving 47.3% of pairs disconnected under every static view tried; co-edited pairs are 26× more likely than random file pairs to share a direct import edge (23.5% versus 0.9%).Source: C. E3: What Static Structure Cannot See · p. 2

III. STRATUM: DESIGN

  • STRATUM combines parsed structural memory with historical co-change links and agent-written experiential knowledge, because structural memory alone recovers barely half the working set.The store lives beside the repository rather than inside the model or serving stack.Source: §III · p. 2

A. Storage and Controller

Stratum stores repository knowledge in a local graph and scores nodes for residency in the agent’s working set. The score combines graph proximity, co-change affinity, access frequency, and pin priority.

A. Storage and Controller

  • The cold tier stores files, tests, notes, decisions, failures, and root-cause findings as graph nodes, with typed edges for imports, tests, similarity, sources, and co-changes.Co-change edges are mined from git history; an HNSW index supports similarity search, and a file watcher refreshes changed content and co-change statistics.Source: A. Storage and Controller · p. 2
  • Each node’s score combines graph proximity to files under edit, co-change affinity, time-decayed access frequency, and explicit pin priority.The linear scoring form is presented as a research hypothesis, not a tuned policy.Source: A. Storage and Controller · p. 2
  • When free context drops below 15%, the controller evicts the largest and coldest nodes first and reports what it removed.Pinned nodes are never evicted; direct neighbors retain interface-level detail, while other warm nodes can degrade to one-line summaries before returning to SSD.Source: A. Storage and Controller · p. 2
  • Repository knowledge stays on the developer’s machine while the controller pages a scored working set across the MCP boundary under an explicit token budget.The model’s KV cache holds only the active turn.Source: Figure 1 · p. 3

B. Nine Page-Safe Tools

Stratum exposes the store through nine MCP tools for reading, writing, and controlling residency. Its page-safety contract makes returned content, remaining pages, and token budget explicit, while write-back lets later sessions inherit what an agent learned.

B. Nine Page-Safe Tools

  • Nine MCP tools cover five read operations, one write operation, and three controls for pinning, prefetching, and evicting resident nodes.Read tools list the tree, search, retrieve paged node details, walk typed edges, and report budget; remember persists a knowledge node.Source: B. Nine Page-Safe Tools · p. 3
  • Every tool response reports pagination state and remaining token budget, so the agent can see whether more content exists and decide when to stop.At task end, the agent can persist what it learned for a later session, potentially run by a different model.Source: B. Nine Page-Safe Tools · p. 3

IV. DESIGN RATIONALE

Stratum’s design rationale pairs portable repository memory with legible paging, learned historical and experiential links, semantic residency signals, and local hosting. The paper presents the scoring policy as an open research question rather than an established improvement over recency-based policies.

R1. Store text and structure, not tensors

  • R1 stores text and structure rather than model-specific KV tensors, making stored knowledge portable across model swaps while requiring embeddings to be recomputed for each encoder.The paper describes KV-cache work as complementary: it makes the current turn cheaper, while Stratum selects what enters that turn.Source: §IV · p. 3

R2. Make paging legible to the agent

  • R2 makes paging boundaries visible through explicit has_more and budget fields, so agents can reason about context as a resource.The rationale connects this design to F2’s finding that the directly connected working set is small enough to fit in one window.Source: §IV · p. 3

R3. Learn the edges; keep the failures

  • R3 mines co-change edges from version history because even transitive static structure misses half of what changes together, and lets agents link failure and root-cause notes to related code.The authors conjecture that records of what was tried and why it failed may be the store’s highest-value content.Source: §IV · p. 3

R4. Semantic signals for an OS-style policy

  • R4 uses graph distance, co-change affinity, and pin intent as semantic signals, but whether they beat least-recently-used (LRU) replacement remains an open question.The comparison is framed as a testable research question, not an assumed result.Source: §IV · p. 3

R5. Live with the code; compose with serving caches

  • R5 keeps the repository on the developer’s machine and sends only the scoped working set to a hosted model; local models avoid even that transfer.Pinned nodes can enter context as stable blocks keyed by content hash, which serving-side prefix caches can reuse [6]–[8].Source: §IV · p. 3

V. PRELIMINARY EVIDENCE

Preliminary evidence shows that a cold-tier store fits on consumer hardware and supports millisecond-scale retrieval. The supplied E5 table is scoped to median session-2 outcomes across eight real bugs, with notes written by a different model.

A. E4: Storage and Retrieval Feasibility

  • 1.70 ms median and 2.76 ms 99th-percentile latency across 200 end-to-end retrievals; two-hop walks took 0.95 ms at the median.End-to-end retrieval combined vector search with k=20, a one-hop graph walk, and loading the 20 result nodes.Source: A. E4: Storage and Retrieval Feasibility · p. 3
  • On a consumer laptop, the cold tier held 106 nodes with about 440M synthetic-content tokens, 5×106 edges, and 384-dimensional vectors in a 3.7 GB store built in under four minutes.The setup used 32 GB RAM, NVMe SSD, and CPU only.Source: A. E4: Storage and Retrieval Feasibility · p. 3
  • Retrieval quality on real embeddings, controller overhead, and index-freshness costs remain unmeasured.The authors limit the feasibility claim to commodity-hardware fit and basic operations being orders of magnitude faster than an LLM turn.Source: A. E4: Storage and Retrieval Feasibility · p. 3

E5: Session-2 Outcomes

  • The E5 table covers median session-2 outcomes across eight real bugs; its notes came from a different model, and C’s input tokens are reported per call.The caption gives the table’s scope but does not provide outcome values.Source: Table I · p. 4

B. E5: Does Inherited Memory Prevent Repeated Work?

The E5 probe tests whether one model’s persisted investigation notes help a different model diagnose the same real bug after a context reset. In this small evaluation, inherited notes improved root-cause-file identification over repository retrieval alone.

B. E5: Does Inherited Memory Prevent Repeated Work?

  • Eight bug-fix tasks from requests and Flask used behaviorally described symptoms, pre-fix repository trees, and root-cause-file identification as the success criterion.A Claude Sonnet writer persisted root-cause and failure notes; after a context reset, a Claude Haiku reader diagnosed the same symptom.Source: B. E5: Does Inherited Memory Prevent… · p. 4
  • 21 of 24 inherited-note trials succeeded versus 6 of 24 retrieval-only trials, at 4.5× lower median input-token cost (Fisher p = 1.3×10−5).The retrieval-only reader typically exhausted its 16-round tool budget.Source: B. E5: Does Inherited Memory Prevent… · p. 4
  • With all 26 investigation notes pooled, success was 8 of 8, including an IPv6 task that had failed in two of three inherited-note trials.The writer solved all eight tasks, with a median 83K tokens paid once.Source: B. E5: Does Inherited Memory Prevent… · p. 4
  • Full-context trials also succeeded in 14 of 16 cases, but each call cost 164K tokens versus 43K for a memory session, and the approach cannot fit Django.The one task full-context failed twice was solved by memory in all three trials.Source: B. E5: Does Inherited Memory Prevent… · p. 4
  • A different model’s notes changed what the reader did with a cold context, exercising cross-model memory transfer that window growth alone does not provide.The probe is small and tests re-diagnosis rather than transfer to a new task.Source: B. E5: Does Inherited Memory Prevent… · p. 4

VI. RELATED WORK

STRATUM is distinguished from prior systems by combining repository-specific structure, durable experience, and visible retrieval budgets. The paper proposes larger-scale tests of memory’s effects while noting limitations in its current analyses and experiment.

VI. RELATED WORK

  • Prior KV-cache work manages model-specific state within a serving context; STRATUM sits above that layer and composes with it.The reviewed areas include quantization, token selection, paged serving memory, offloading, cross-request reuse, and cache retrieval [3], [6]–.Source: §VI · p. 4
  • Unlike conversation paging or code-only retrieval, STRATUM combines a typed code graph, co-change mining, durable failure and root-cause nodes, and page-safe visibility into truncation and cost.Its co-change edges turn a classic mining-software-repositories technique into live edges traversed during tasks.Source: §VI · p. 4

VII. FUTURE PLANS

  • The future research plan asks whether persistent memory improves multi-session success, whether historical and experiential edges improve file retrieval, and whether semantic eviction and negative knowledge help.Planned tests also examine transfer across models and frameworks, memory hygiene, summary faithfulness, and team-shared stores.Source: §VII · p. 4
  • Current evidence is limited by Python-only analyses, potentially stale import graphs, keyword-based commit sampling, synthetic E4 content, and an E5 lexical baseline without note-quality control or summary carry-over.The one-hop closure is only a proxy for required context; RQ2 is planned to validate it against files developers actually consulted.Source: §VII · p. 4

VIII. CONCLUSION

The conclusion frames agent memory as a question of what belongs in context, not simply how large the context window is. STRATUM sketches repository-side memory, and E5 provides small-scale evidence of transfer across a model boundary.

VIII. CONCLUSION

  • The context window is a cache, while the harder problem is deciding what it should contain.The conclusion characterizes the needed knowledge as small, partly invisible to static analysis, and affordable as text beside code.Source: §VIII · p. 5
  • STRATUM sketches a repository-memory layer, and E5 shows it working across a model boundary.The paper identifies evidence at scale as the next step.Source: §VIII · p. 5
  • The conclusion characterizes needed agent knowledge as small, half-invisible to static analysis, and affordable only as text beside the code.Source: §VIII · p. 5
Loading 2610.36153v1…