ResearchField guide

The Memory Company · MMXXVI · first edition · v1.0

An essay on Agentic Engineering Memory

A field guide for engineering teams making AI agent work compound.

Begin reading Start using Spark

ii · epigraph

One agent learns. Every agent ships faster.

— Memco

iii · preface

Agentic engineering needs memory.

AI coding agents can now do real engineering work. The problem is that most teams do not keep what the work teaches them. An agent discovers a repo quirk, burns tokens on a dead end, gets corrected by a human, maybe solves the task — and then the lesson disappears into a session, PR comment, Slack thread or local cache. The next agent starts cold.

This guide is for engineering teams that want agent work to compound. It explains what memory is, what it is not, how to build it into the engineering workflow, and how to measure whether it is actually improving future work.

The shift we care about: from agents that complete tasks to engineering teams that retain what agent work teaches them.

plate i · the memory loop

        i. capture ──▶ ii. distill ──▶ iii. scope
            ▲            + synthesize        │
            │                                ▼
   viii. retire                       iv. provenance
            ▲                                │
            │                                ▼
    vii. validate ◀── vi. apply ◀── v. retrieve
 i. capture
 ii. distill + synthesize
 iii. scope
 iv. provenance
 v. retrieve
 vi. apply
 vii. validate
 viii. retire ↺
The memory lifecycle in eight stages, after capture and before retirement.Eight-stage cycle: capture, distill and synthesise, scope, provenance, retrieve, apply, validate, retire — drawn as a loop.

plate ii · the second-run signal

 without memory        with memory
 ──────────────        ───────────
 run 1  ██████         run 1  ██████
 run 2  ██████         run 2  ███▊
 run 3  ██████         run 3  ██▎ converges

 tokens evaporate      each run feeds the next —
 every session         the team gets smarter, not the model
 without      with
 r1 █████     █████
 r2 █████     ███▊
 r3 █████     ██▎
Without memory, every run pays full price. With memory, work converges.Two mini charts: without memory, three runs each burn the same tokens; with memory, each run feeds the next and cost converges downward.

vi · table of

Contents

  1. iThe cold-start tax6 min
  2. iiThe second run is the signal5 min
  3. iiiWhat memory is not6 min
  4. ivThe memory lifecycle7 min
  5. vThe engineering brain5 min
  6. viMemory quality5 min
  7. viiMemory fails when work changes6 min
  8. viiiGovernance without killing speed5 min
  9. ixThe memory stack4 min
  10. xPublic commons memory6 min
  11. xiPrivate, permissioned memory8 min
  12. xiiThe 30-day memory pilot5 min
  13. xiiiThe diagnostic toolkit4 min
  14. xivHow teams evaluate memory5 min
  15. xvCommon concerns4 min

Chapter 01 6 min Fig. 03 Exercise · Cold-start audit

The cold-start tax

Every agent run starts with a question: what does this agent know before it begins? For most teams, the answer is — less than the last agent knew when it finished. That is the cold-start tax.

A human engineer accumulates context. They learn which test suite lies. They remember the migration that failed last quarter. They know the weird auth path in the billing service. They know that a dependency was pinned for a reason. They know who to ask when a convention is not written down.

A coding agent can discover all of that too, but usually only inside a run. Once the session ends, the useful residue is scattered: hidden in the transcript, buried in a local cache, trapped inside one vendor's memory, mixed into a trace store, left as a PR review comment, half-copied into AGENTS.md, or never captured at all. The team paid for the lesson. The organization did not keep it.

What the cold-start tax looks like

You can spot it when:

  • A second agent repeats a failed approach from the first run.
  • A reviewer gives the same correction twice in a week.
  • An agent misses a repo convention that lives only in someone's head.
  • Claude Code learns something Cursor does not know.
  • A prompt file grows until nobody trusts it.
  • A senior engineer says, "We already solved this."
  • The team cannot explain why one agent run worked and another did not.

Why this matters commercially

Token waste is the easy number. It is not the whole cost. The larger cost is variance. If agent runs are unpredictable, senior engineers keep supervising them like interns. If the same mistakes repeat, adoption stalls. If useful lessons cannot travel across tools, the company becomes dependent on local context and vendor-specific memory.

The goal is not only cheaper agent runs. The goal is more predictable agentic engineering.

Fig. 03

  1. i.Agent starts cold
  2. ii.Hits repo quirk
  3. iii.Burns tokens on dead end
  4. iv.Human corrects
  5. v.Lesson lost

…and the next agent starts cold

The cold-start tax — every run pays the same discovery cost

Chapter 02 5 min Exercise · Second-run metric

The second run is the signal

A successful first run proves an agent can work. A better second run proves memory compounds. That distinction matters. Most AI demos are first-run demos — they show that a model can solve a task with enough context, tools, and luck. Useful, but it does not prove the team is getting smarter.

Agentic engineering becomes durable when the next run starts ahead because the previous run left behind a trusted lesson.

The first useful signal

Installation, signup, a first query, a first memory, a first demo, or a first prompt file are setup events. The useful signal is simpler:

A future run reuses a prior lesson without the team having to repeat itself.

A reused memory counts when it is retrieved in a later task, the agent applies it correctly, it avoids a repeated failure or shortens the path to success, a human accepts the result, and the memory has provenance and scope so the team can trust where it came from and where it applies.

Stronger signals

  • Two agents benefit from the same lesson
  • Two engineers benefit from the same lesson
  • One repo's private memory improves a second workflow
  • A stale memory is updated or deprecated
  • A human correction becomes reusable memory
  • A pilot expands to a second repo, team, or agent tool

Before and after

Before memory: Agent tries to update a service. Misses the repo's internal auth convention. CI fails. Senior engineer corrects it. The fix stays in the session. A future agent repeats the same mistake.

With memory: Agent starts a similar task. Spark retrieves the prior auth convention, with provenance. Agent avoids the failed path. CI passes sooner. The outcome reinforces the memory. Future agents start ahead. That is the loop.

Memory starts working when a future run remembers what the team would otherwise explain again.

Chapter 03 6 min Fig. 04 Exercise · Stack separation

What memory is not

A lot of things look like memory from a distance. Most are useful. None are sufficient by themselves.

Long context is not memory

Long context helps a model see more at once. Memory decides what deserves to come back later. A larger context window can include more docs, traces, comments, and files — but it does not automatically know which lesson was validated, which rule went stale, or which correction should apply to a future workflow. Long context is a reading surface. Memory is a learning system.

RAG is not memory

RAG retrieves what the company already wrote down. Engineering memory also needs to retain what the company learns next. A doc search system can find the architecture guide. It usually will not know that yesterday's agent tried the documented path, failed because production behaves differently, got corrected by a reviewer, and found a better route. RAG retrieves knowledge. Memory promotes experience.

Trace stores are not memory

Traces show what happened. Memory decides what should survive. Raw traces are valuable, but too noisy to be the product. A useful memory layer has to turn traces, comments, retries, failures, and fixes into scoped lessons future agents can use. Trace is raw material. Memory is refined learning.

CLAUDE.md and AGENTS.md are not memory

Agent instruction files give a project a starting shape. But static files decay. They do not know which instruction worked, which caused harm, which rule is stale, which convention applies only to one package, which human correction should be promoted, which memory should be retired. A prompt file is a signpost. Memory is a living layer.

Local vendor memory is not organizational memory

Claude remembers inside Claude. Cursor remembers inside Cursor. GitHub may remember inside GitHub. Internal agents remember inside internal systems. Useful — but enterprises do not live in one tool.

The model can change. The memory should not.

Fig. 04

Context stack

5 layers

  1. v.Shared memoryscoped lessons future agents can retrieve and applyliving
  2. iv.Local memoryvendor or tool-specific memorystatic
  3. iii.Work tracessessions · logs · PRs · CI failures · ticketsstatic
  4. ii.Written knowledgedocs · runbooks · ADRs · READMEsstatic
  5. i.Context filesCLAUDE.md · AGENTS.md · Cursor rules · promptsstatic
The context stack — only the top layer learns from new work

Chapter 04 7 min The longest chapter 8 stages Exercise · Lifecycle score

The memory lifecycle

Useful engineering memory has a lifecycle. If you skip the lifecycle, you get sludge.

1. Capture

Memory begins in work: agent sessions, code diffs, PR reviews, failed tests, CI logs, human corrections, ticket comments, incident notes, local conventions, successful fixes. Capture does not mean saving everything forever. It means preserving enough signal to decide what should become memory.

2. Distill / synthesize

A trace is too raw. A useful memory needs shape.

Bad memory: "The agent failed auth-service tests on May 19."

Better memory: "In auth-service, token validation must go through internalAuth.validateScopedToken rather than the generic JWT helper. The generic helper passes unit tests but fails staging because service-to-service scopes are injected later in the request lifecycle."

A good engineering memory is actionable. It tells a future agent what to do, what not to do, where it applies, and why.

Synthesis is the higher-order move. It combines traces from multiple users, runs, and workflows to derive knowledge that no single person explicitly wrote down: an abstracted principle from repeated examples, a recurring failure mode, or a conflict between two signals that needs resolution before the memory is reused.

3. Scope

Most memory is dangerous when too broad. Scope answers: which repo? which package? which service? which branch or version? which team? which environment? Public, team-private, customer-private, or enterprise-wide? A lesson from one repo should not silently rewrite behavior everywhere.

4. Provenance

Memory needs provenance: who observed it, which project or repository it belongs to, and when it was captured. Those basic authorship details help a future agent and the team understand where a lesson came from and where to be careful with it. Bad memory is worse than no memory — it sends future agents confidently in the wrong direction.

5. Retrieve

Memory is only useful if it appears at the point of work. That means retrieval should happen where agents already operate: Claude Code, Cursor, Codex, Copilot, Windsurf, internal harnesses, CLI workflows, CI / PR review. Memory should not require engineers to open a separate knowledge base and hunt manually.

6. Apply

The agent applies the memory in a task. This is where memory becomes more than a note — it changes the path of work. The agent should cite which memory it used, how it used it, whether it changed the plan, whether it avoided a known failure.

7. Validate

A memory system should learn from outcomes. Did the task succeed? Did CI pass? Did the reviewer accept the change? Did the user mark the recommendation useful? Did the same memory help another agent? Did it cause a failure? Validated memory gets stronger. Bad memory gets demoted. Stale memory gets updated or retired.

8. Retire

Real work changes. APIs change. Repos change. Policies change. Services move. Dependencies get replaced. What was true last quarter may be wrong today. A memory layer has to support update, supersession, decay, deletion, conflict resolution, human override. Append-only memory becomes sludge.

Chapter 05 5 min Fig. 05 7 categories of memory

The engineering brain

Every engineering team already has an implicit brain. It lives in senior engineers, old PRs, Slack threads, tribal knowledge, weird scripts, test habits, postmortems, half-updated docs, and the scars left by failed migrations.

Agentic engineering makes that implicit brain more important, not less. Agents can move quickly, but they need local judgment. They need to know what this team has learned about this codebase.

What belongs in engineering memory

Repo conventions — where new endpoints belong, which test helpers to use, monorepo import rules, naming conventions, framework-specific patterns.

Failed paths — migration approaches that broke staging, packages that looked compatible but weren't, query patterns that passed locally but failed at scale, test commands that give false confidence.

Known fixes — recurring CI failures, flaky test workarounds, integration quirks, dependency pinning reasons.

Human corrections — "Do not use this abstraction in payments." "This API is customer-facing, keep backwards compatibility." "This service handles EU data, do not route through the US pipeline."

Architectural decisions — why a service boundary exists, why a dependency was rejected, why a shortcut is intentionally avoided, what the team tried before and why it changed course.

Environment constraints — staging differs from production in this way, auth behaves differently behind the gateway, feature flags must be enabled, customer-specific config matters.

Evaluation feedback — which agent recommendations were accepted, which were rejected, which memories improved task completion, which caused bad behavior.

What does not belong

  • Raw source code when a scoped lesson is enough
  • Secrets or credentials
  • Customer data unless explicitly approved and scoped
  • Generic facts the model already knows
  • One-off implementation details with no reuse value
  • Vague summaries like "auth is tricky"
  • Opinions without provenance
  • Stale rules with no owner

Good memory format

A good engineering memory has five parts: Lesson (what to know), Scope (where it applies), Provenance (who observed it, which project it belongs to, and when it was captured), Action (what to do or avoid), Status (active, tentative, superseded, retired).

Fig. 05

Memory · billing-api / subscription

Lesson
In billing-api, subscription status must be read from BillingAccount.current_state, not StripeSubscription.status.
Scope
billing-api · subscription renewal flows
Provenance
Observed by Priya · billing-api · 2026-05-12
Action
Use BillingAccount.current_state for access decisions. StripeSubscription.status is only used for reconciliation.
Status
ACTIVE
A good engineering memory — five parts, scoped and provenanced

Chapter 06 5 min Fig. 06 5 tests · 10 example signals

Memory quality

More memory is not the goal. Better memory is the goal. A team can drown in saved traces, stale instructions, duplicated lessons, and over-broad rules. That creates the illusion of intelligence while making agents less reliable.

Memory quality is the difference between a helpful shortcut and a landmine.

The five tests of a good memory

1. Actionable. A future agent should know what to do differently. Bad: "The payments service is complicated." Good: "In payments-service, refund events must be idempotent by provider_refund_id. Do not key on internal refund ID because Stripe retries can create duplicate webhook deliveries."

2. Scoped. The memory should say where it applies. Bad: "Always use the internal auth helper." Good: "In services behind gateway-v2, use internalAuth.validateScopedToken for service-to-service calls. Does not apply to public API routes."

3. Provenanced. The memory should carry basic authorship and project context: who observed it, which repository or project it belongs to, and when it was captured. A mature system may add richer supporting signals over time, but the first job is to prevent orphaned lessons.

4. Current. The memory should have a way to change. A memory that cannot be updated eventually becomes risk.

5. Reused. A memory has not really proved itself until it helps a later task. Creation is setup. Reuse is the first useful signal.

Fig. 06

Mature Memory Quality Score · example

10 EXAMPLE SIGNALS

Retrieval hit rate
0.78
Acceptance rate
0.64
Reuse count
0.48
Task success delta
+0.71
Token / time saved
0.52
Provenance strength
0.85
Scope correctness
0.69
Freshness
0.34
Correction capture
0.57
Stale-memory collisions
0.22
Memory Quality Score — your team's memory quality is not how much context you store. It is how often the right lesson improves the next run.

Chapter 07 6 min 5 failure modes Exercise · Interference

Memory fails when work changes

For early demos, memory looks simple. An agent learns a fix. The next agent retrieves it. Everyone claps.

Real engineering is messier. Code changes. APIs change. Dependencies change. Policies change. Teams reorganize. A convention that saved time last month can break production today.

The hard problem is not remembering more. The hard problem is knowing what changed, what still applies, what should be retired, and what future agents can safely reuse.

Common failure modes

Append-only sludge. The system keeps adding memories but rarely updates or deletes them. Symptom: agents retrieve multiple conflicting lessons; engineers stop trusting recommendations; old fixes keep resurfacing after the code changed.

Over-broad lessons. A lesson from one package gets applied across the repo. Symptom: an agent follows a rule in the wrong context. The memory looked correct, but scope was missing.

Lost provenance. The memory says what to do but not why anyone should trust it. Symptom: senior engineers ask, "Where did this come from?" Compliance and security cannot approve broader use.

Local-only learning. One tool learns the lesson, but the organization does not. Symptom: Claude knows something Cursor does not. A user's local setup works better than the team's shared workflow. Switching models loses hard-earned context.

Stale human corrections. A reviewer corrected an agent once, but the correction was never promoted. Symptom: the same correction appears in future PRs. Senior engineers become agent babysitters.

Append-only memory becomes sludge.

Chapter 08 5 min Fig. 07 For CISO / GRC

Governance without killing speed

Engineers adopt agents because they are fast. Enterprises hesitate because unmanaged speed creates risk. The point of memory governance is not to slow every agent down. It is to let teams move faster without losing control of what agents know, reuse, and share.

Questions every team eventually asks

  • What becomes memory?
  • Who can promote it?
  • Who can edit or delete it?
  • Public, team-private, repo-private, customer-private, or enterprise-wide?
  • Can an agent cite where a memory came from?
  • Can security audit what was shared?
  • Can stale memory be retired?
  • Can the system run in our environment?
  • Can we keep code and sensitive context inside our boundaries?

Public vs private

Public memory helps everyone — open-source fixes, common API integration patterns, framework gotchas, community-validated solutions. Private memory is where the company advantage lives — private repo conventions, internal architecture decisions, customer-specific caveats, deployment constraints, review preferences, security rules, operational lessons.

The best system lets teams benefit from public memory without leaking private learning.

Memory as the company lever

Most teams have no practical lever for improving the agents they are handed by model providers. They can write better prompts, tune process, or wait for the next model release. Memory creates a different lever: a company-controlled learning layer that improves future agent work without sending private operational knowledge into model training pipelines or building a complex model-training program internally.

Fig. 07

Public memory

community

  • open-source fixes
  • API patterns
  • framework gotchas

Private memory

your team

  • repo conventions
  • architectural decisions
  • customer caveats
  • deployment constraints

Benefit in: public memory flows into private memory. Never out: private memory never flows out.

The best memory layer is asymmetric.

Public memory flows in. Private learning never flows out.

Chapter 09 4 min Fig. 08 Neutral layer

The memory stack

Agentic engineering is not one tool. It is a stack — agents, models, work systems, and context layers. Memco's place in the stack is not to replace any of them.

Memco does not replace the agent stack. It makes the stack learn.

The neutral memory layer

Teams will not standardize on one model or agent forever. A serious engineering org will use a mix of tools. Some vendor-hosted. Some internal. Some will change every quarter. The memory layer should survive that churn.

Fig. 08

The stack

Four rows

Agents & IDEs
  • Claude Code
  • Cursor
  • Codex
  • Copilot
  • Windsurf
  • internal harness
Models
  • Claude
  • GPT
  • Gemini
  • Llama
  • DeepSeek
  • Qwen
  • …the next
Work systems
  • GitHub
  • Linear
  • Slack
  • CI
  • docs
  • incidents
Context layers
  • prompt files
  • repo docs / RAG
  • trace stores
  • local memory
  • shared memory

the model can change · the memory should not

The agent stack — a neutral memory layer survives the churn above it

Chapter 10 6 min Optional, read-only reference for shared public problems Fig. 10 Read-only commons

Public commons memory

Stack Overflow worked because individual developers helped each other. Someone hit a problem, found a fix, wrote it down, and the next person started a little further ahead. The internet did what the internet is good at: turning repeated individual pain into shared infrastructure.

Coding agents need the same thing, but the shape is different. Agents do not want a forum thread. They need a scoped, validated, machine-readable lesson they can apply at the point of work.

A human searches:

How do I fix this CORS error in Express?

An agent needs something closer to:

In Express 5, when using credentials with CORS, set credentials: true and use an explicit origin. Do not use * — browsers reject wildcard origins with credentialed requests. Applies to browser-based requests using cookies or auth headers. Verified against Express 5 and the cors package.

That is not a blog post. Not a chat transcript. Not a raw trace. It is memory.

Public commons

Public, validated, reusable engineering lessons.

Open-source packages, public APIs, framework gotchas, SDK bugs, migration traps. Lives outside any one company.

Private company memory

Private, governed, tenant-owned company knowledge.

Repo conventions, internal architecture, customer constraints, deployment quirks, review feedback. Lives inside your boundary.

  • One-way optional readPublic commons → enterprise agents, only if you allow it.
  • No reverse flowYour private tenant never writes into the public commons. Not automatic. Not by default. Not at all.

Asymmetric by design

The commons is built around one rule:

Individuals contribute. Anyone may read.

Open-source maintainers, indie developers, and engineers working on their own projects publish validated memories alongside the packages and frameworks they use. They are the writers.

Anyone — individual developers, indie agents, company agents — may opt in to read selected public memories. A team using Node.js can elect to give their agents read access to the Node.js corner of the commons, so when an agent hits a dependency conflict, an undocumented API edge case, or a known-bad migration path, the lesson is already there.

That does not connect their private memory to the public layer. Their private repo never gets indexed. Their internal corrections never flow out. Reading is opt-in, scoped to the languages, frameworks, and packages they choose.

Where the commons earns its keep

The commons is most useful for the kind of knowledge that today lives scattered across GitHub issues, blog posts, and one engineer's head:

  • Dependency conflicts your agent just rediscovered
  • A new field on a public API that the docs do not mention yet
  • A version-specific framework gotcha
  • A failed migration path on a public package
  • An undocumented OAuth or webhook quirk
  • A workaround for a known SDK bug
  • Build errors that look generic but have one real cause

These are lessons that come from real engineering work but apply broadly. Every team running Node.js, Stripe, Next.js, FastAPI, or Postgres benefits from the same scoped memory.

Why Stack Overflow is not enough

Stack Overflow was designed around human search. In an agentic workflow, that has limits:

  1. The answer is buried in conversation.
  2. The accepted answer may be stale.
  3. Version scope is often unclear.
  4. The answer rarely says what failed before the fix.
  5. The agent has to infer whether the answer applies.
  6. The answer is not connected to outcome feedback from future runs.

Agents need structured memory, not just text. A useful public memory knows what problem it solves, where it applies, which versions matter, what failed paths to avoid, what evidence supports it, whether future agents reused it, and whether it has become stale.

Stack Overflow was search for humans. The commons is memory for agents.

Fig. 10

Two memory worlds

One hard boundary

Public commons

Public, optional, reusable lessons

Contains

  • Node.js dependency conflicts
  • Stripe webhook gotchas
  • Next.js upgrade traps
  • Public API edge cases
  • SDK workarounds
  • Known public failed paths

Writers

  • Individual developers
  • OSS maintainers · framework teams
  • Consenting public contributors

Readers

  • Anyone · company agents only if approved
Hard privacy boundary

Private company memory

Tenant-owned, governed knowledge

Contains

  • Repo conventions
  • Internal architecture
  • Customer-specific constraints
  • Security & deployment rules
  • Human review feedback
  • Incident history

Writers

  • Approved company agents · engineers
  • Reviewers · internal tools
  • CI / PR review, if permitted

Readers

  • Scoped by team · repo · customer · BU · env
  • Optional read-only referencecompany agents may read selected public memories
  • Never writes backprivate memory never flows to the commons
Two memory worlds, one hard privacy boundary — optional read in, never write out

What never goes in the commons

The commons is for lessons that apply broadly. It is not the place for:

  • Private source code
  • Internal repo conventions
  • Customer-specific configuration
  • Architecture decisions
  • Secrets or credentials
  • Anything that identifies your company or its work

The clean split:

The commons helps agents solve problems everyone shares. Private memory turns company-specific work into advantage.

Quality bar for public memory

Public memories carry stricter quality controls than private scratch memory because they affect many users. A public memory should include: problem, scope (framework, package, API, version, environment), recommendation, failed path, evidence, reuse signal, freshness, and safety.

This is what makes it different from a forum answer.

Why this matters as a distribution model

Individual developers find Spark through the commons. They feel the loop work on a side project, on an open-source repo, on a one-person consultancy. Then they take it back to their team and ask the natural question:

You just got a working fix from a memory another developer published. Want the same loop for your private codebase — without ever sharing your code?

That is the bridge from community to commercial — and the next chapter is about what the private side looks like.

Do not confuse these

Public and private memory are different systems.

Public commons memory

Optional input

  • Public engineering lessons
  • Optional read access
  • Written by individuals and maintainers
  • Useful for public APIs, packages, SDKs, frameworks
  • Does not contain company code
  • Does not receive private enterprise memory

Private company memory

Your asset

  • Company-owned memory
  • Tenant, VPC, or on-prem
  • Written by approved company agents and people
  • Scoped by team, repo, customer, region, and sensitivity
  • Used with approved model stacks
  • Governed by company policy

Your company memory is not a contribution to the public commons.

Chapter 11 8 min Own the memory · Control the boundary · Choose the model Figs. 11 · 12 Permission matrix 4-question control plane

Private, permissioned memory for the agentic enterprise

Shared memory does not mean shared access. In an enterprise, memory has to follow the same boundaries as the organization itself: teams, repos, customers, business units, regions, data sensitivity, and deployment environments.

Memco's enterprise memory layer is separate from the public commons. It runs in a private tenant, an enterprise tenant, a VPC, or on-prem. Your company decides what gets remembered, who can retrieve it, who can write it, which models can use it, and when it expires.

Public commons memory is optional reference material. Private memory is company-owned infrastructure.

Public commons is optional input. Private memory is your asset.

Access is not flat

In the agentic enterprise, not every agent should see the same memory. A support agent should not automatically retrieve security incident memory. A sales-engineering agent should not write architecture decisions. A contractor agent may be able to suggest memory, but not promote it. A CI agent may write test failure patterns for one repo, but not read customer-specific deployment notes from another.

Read and write are separate permissions. Agents inherit organizational boundaries, not flatten them.
Sample permission matrix: agent roles vs memory scopes
Agent rolePublic package lessonsRepo conventionsArchitecture decisionsSecurity policiesCustomer-specific memoryIncident historyDeployment rulesCommercial context
Engineering agentsReadRead WriteSuggestReadSuggestReadReadno access
Security agentsReadReadRead ApproveRead WriteReadRead WriteReadno access
Platform agentsReadReadReadReadSuggestReadRead Writeno access
Support agentsReadno accessno accessno accessRead SuggestReadno accessRead
Sales-engineering agentsReadReadno accessno accessReadno accessno accessRead Write
CI / PR review agentsReadRead WriteSuggestReadno accessReadReadno access
Contractor agentsReadReadno accessno accessno accessno accessSuggestno access
Executive agentsReadno accessReadReadReadReadno accessRead Approve
  • Readretrieve
  • Writecreate durable memory
  • Suggestpropose, awaiting approval
  • Approvegovern promotion
  • On-premrestricted scope
  • no accessno access
Sample matrix · enterprise memory follows organizational boundaries · agents do not get blanket access just because they are agents

Three deployment postures

  • i.

    Private tenant

    For startups and product teams.

    • Private namespace
    • Repo- and team-scoped memory
    • Admin controls
    • Optional public-commons read access
    • No private write-back to commons
  • ii.

    Enterprise tenant

    For larger companies.

    • Dedicated tenant
    • SSO · RBAC
    • Audit logs · approval workflows
    • Team, repo, customer, and business-unit scopes
    • Retention and deletion policies
  • iii.

    VPC / on-prem

    For regulated environments — banks, healthcare, defence, government, data-residency requirements.

    • Runs inside the customer boundary
    • Code and traces stay private
    • Compatible with private model endpoints
    • Supports open-source and self-hosted LLMs
    • Customer controls storage, network, region, and access

Same memory loop. Different control boundary.

Memory as the durable asset

Most AI adoption conversations still over-index on the model. Which model is best? Which is cheapest? Which has the biggest context window? Those questions matter, but they miss a more durable point.

Models change constantly. Organizational memory should not. A company that stores its agent learning inside one model vendor's memory layer is renting continuity. Switch tools, change providers, move workloads on-prem, adopt open-source — and that learning fragments or disappears.

The shape that holds up is the one where memory is independent of the model.

Fig. 11

Model portability

One memory · policy-gated · many models

Models

  • Claude
  • GPT
  • Gemini
  • Llama / OSS
  • Self-hosted
  • Internal fine-tunes
  • future

Policy gate

  • approved model list
  • private endpoints
  • on-prem only flags
  • no unapproved

Private memory

Scopes

  • team · repo · customer
  • region · sensitivity · env

Policy

  • who can retrieve
  • who can write
  • which models can use
  • on-prem-only memories

Agent workflows

  • IDE
  • CLI
  • CI / PR review
  • Internal harness
  • Incident response

model access is policy-controlled · not every model can retrieve every memory

the model can change · the memory should not

One private memory layer · gated by company policy · feeds every approved model and every agent workflow

The open-source model unlock

Private memory can let smaller, open-source, or self-hosted models compete on repeated company-specific workflows because they start with company context instead of generic context.

Frontier models are powerful. But a frontier model without your repo conventions, failed paths, review history, deployment quirks, and customer constraints still starts cold. A smaller or self-hosted model with strong private memory can perform surprisingly well on repeated internal work because it starts from what the organization already knows.

Frontier models are powerful. Private memory makes cheaper models useful.

Fig. 12

Performance over repeated workflows

Performance →Repeated workflow instances →frontier model · cold startsmaller / private model + private Memco memoryCrossoverRun 1Run N

repeated internal work rewards memory, not just raw model power

Repeated internal work rewards memory · cheaper models close the gap as memory accumulates

Because the memory layer can run in a private tenant, VPC, or on-prem, companies can improve private model performance without sending sensitive context to unapproved model providers. This gives enterprises a realistic path to:

  • Reduce reliance on the most expensive frontier models
  • Use open-source or self-hosted models for more workflows
  • Keep sensitive engineering context inside their boundary
  • Preserve model choice across vendor changes
  • Avoid vendor lock-in around the memory itself

Control every flow into and out of memory

Security is not a paragraph at the bottom of the page. It is part of the memory model. Every memory needs scope, provenance, permission, retention, and deletion. The control plane is organized around four questions.

  • i.

    Where does the memory run?

    Private tenant · dedicated enterprise tenant · VPC · on-prem.

    REGIONAL TENANTS · ROADMAP · VPC · ON-PREM AVAILABLE

  • ii.

    Who can read and write?

    SSO · RBAC · team, repo, customer, and business-unit scopes · read and write are separate permissions · approval workflows for promotion.

    SCOPE · PROVENANCE · APPROVAL · SEPARATE OPERATIONS

  • iii.

    Which models can use it?

    Approved model list per scope · private model endpoints · on-prem-only flags · open-source model support · no traffic to unapproved providers.

    MODEL POLICY GATE · CONFIGURED PER MEMORY

  • iv.

    What happens when memory changes?

    Provenance on every memory · audit logs for retrieve, write, edit, retire · review workflow · decay · per-scope retention · hard delete as a first-class operation.

    VALIDATION · RETIREMENT · HARD DELETE

Enterprise options & roadmap. SOC 2 Type II, ISO 27001, HIPAA-aligned deployment, customer-managed keys (BYOK), SIEM export, and regional tenants are available as enterprise options or on the roadmap depending on deployment. Ask for the current security brief and DPA before pilot.

Your code stays yours. Your memory becomes yours too.

The commons is opt-in and outbound only for individual contributors. Private memory is governed inside your tenant or your own infrastructure. The memory layer is the asset; the company that owns it controls every flow into and out of it.

Chapter 12 5 min Fig. 09 4 weeks

The 30-day memory pilot

Do not start with a company-wide rollout. Start with one team, one repo, one workflow, and one success metric.

Example workflows: recurring CI failures · auth-service fixes · dependency migrations · repo onboarding tasks · flaky test repair · API integration fixes · repeated PR review corrections.

Fig. 09

  1. D 1 · Week 1Map
    • workflow map
    • current sources
    • candidate memories
  2. D 7 · Week 2Capture & seed
    • initial memory set
    • scope rules
    • retrieval tests
  3. D 14 · Week 3Run with memory
    • live agent use
    • acceptance tracking
    • avoided failures
  4. D 21 · Week 4Prove & decide
    • memory reuse readout
    • before / after example
    • expansion decision

Signal a future agent did better because the team retained what a previous run learned

The 30-day memory pilot — four weeks, one signal

What good looks like

A good 30-day pilot does not need to prove everything. It needs to prove one thing cleanly: a future agent did better because the team retained what a previous run learned. After that, expand to a second workflow, a second repo, or refine memory quality. Pause if no strong reuse signal.

Chapter 13 4 min 1 diagnostic

The diagnostic toolkit

The Field Guide should not just explain the problem. It should help teams find their own version of it. The Memory Reliability Lab combines the original diagnostic paths into one interactive score and sample report.

A.Memory Reliability LabScore memory gaps, context decay, workflow capture, interference, governance, and evidence confidence in one seven-minute diagnostic.Run diagnostic

Chapter 14 5 min 6 viewpoints

How teams evaluate memory

Different teams evaluate the memory problem through different lenses. A useful evaluation connects the same core question — whether future agent work gets more reliable — to the work each audience already owns.

  • For

    Engineers

    "Your agents keep rediscovering repo rules, known fixes, and failed paths."

    Look for: actual memory retrieval · prior failed path avoided · less review back-and-forth · no workflow change · support for the current agent stack.

  • For

    VP Engineering

    "You are paying for repeated work and getting no institutional learning."

    Look for: repeated correction patterns · time / token / review drag · workflow metrics · adoption from one workflow to team habit.

  • For

    CTO / CIO

    "Agent work is becoming strategic infrastructure. The learning cannot stay trapped in sessions, vendors, or stale context files."

    Look for: model portability · governance · provenance · enterprise controls · memory as an organizational asset.

  • For

    DevEx / AI platform

    "Agent adoption needs a reliability layer."

    Look for: stack integration · memory quality signals · workflow mapping · update / delete / provenance · multi-tool support.

  • For

    CISO / GRC

    "Bad memory is a control problem."

    Look for: scope · permissions · audit · retention / deletion · private deployment · separation of public and private memory.

  • For

    CFO / COO

    "The cost is not only tokens. It is repeated work, review drag, slower delivery, operational variance."

    Look for: time saved · token reduction · avoided repeated failures · fewer senior-review repetitions · more predictable delivery.

Chapter 15 4 min 6 answers 6 concerns

Common concerns

"Won't Anthropic, OpenAI, GitHub, or Cursor just build memory?"

They will. That validates the category. But vendor memory is local. Enterprise memory has to work across models, tools, repos, teams, permissions, and time. The question is not whether agents will have memory. They will. The question is whether the organization owns the learning.

"Is this just RAG?"

No. RAG retrieves what the company already knows. Engineering memory captures what the company learns from future work. The hard part is not retrieval alone — it is the lifecycle: capture, distillation, scope, provenance, reuse, update, retirement.

"We already have AGENTS.md."

Good. Keep it. But static instruction files are not enough. They do not know what worked, what failed, what changed, or whether a later run benefited. AGENTS.md is a starting point. Memory is the compounding layer.

"We can store traces ourselves."

You should store traces. But traces are raw material. The value comes from turning them into trusted, scoped, reusable lessons and proving they improved future work.

"We do not want to share code."

You should not share private code broadly. The memory layer should preserve lessons, scope, provenance, and controls. Public memory and private team memory need different boundaries. A good memory can say "use the internal auth helper for service-to-service calls in this repo" without exposing source code to the world.

"Why now?"

Because agent use is crossing from experimentation into real engineering workflows. Once agents operate inside changing codebases, memory becomes a reliability problem. Teams need to know what should be remembered, who can reuse it, and when it should be updated or forgotten.

Context is rented. Memory is owned.

vii · appendix · one interactive tool

The Memory Reliability Lab

The guide should not just explain the problem — it should help teams find their own version of it. A privacy-preserving, seven-minute diagnostic: six dimensions, a rubric-based judge, a written readout you can take back to your team. No repo access, no code upload — pattern-level answers only.

a · memory reliability score

7 minutes · no repo access

The Memory Reliability Lab
Organisation

Most coding-agent demos show the first run. The second run is the signal.

Scott TaylorCo-founder — a founder’s note

Turn today’s agent work into memory your company can reuse.

The Memory Company · memco.ai · v1.0 · MMXXVI — context is rented. memory is owned.