DEV Community: Ernesto Herrera Salinas

Your Coding Agent Has Amnesia: Memory-Augmented Generation, Explained Through Codex

Ernesto Herrera Salinas — Mon, 10 Aug 2026 13:09:13 +0000

The Monday Problem

On Friday, you spent forty minutes teaching Codex about your project. You explained that the backend uses PostgreSQL, that the test suite must run with make test-fast because the full suite takes twenty minutes, and that the payments module is fragile and should never be refactored without a ticket. Codex worked beautifully for the rest of the session.

On Monday, you open a new session. Codex suggests refactoring the payments module. It runs the full test suite. It asks what database you use.

Nothing broke. This is the design. Large language models are stateless functions: everything the model "knows" about your project lives in the context window of the current session, and when the session ends, that context is destroyed. The forty minutes of Friday context did not degrade or get misplaced. It never existed anywhere except in a buffer that no longer exists.

This article is about the class of techniques built to fix that, known as Memory-Augmented Generation (MAG), and about how OpenAI's Codex implements it in practice.

Why the Context Window Is Not Enough

The obvious objection: context windows are huge now, so why not just keep everything in context?

Three reasons.

First, context is per-session. A million-token window does not help you on Monday if Friday's session is gone. Window size solves a capacity problem, not a persistence problem.

Second, long context degrades. Attention effectiveness falls with distance, a failure mode documented as the "lost in the middle" phenomenon: models reliably use information at the beginning and end of a long context but miss information buried in the middle (Liu et al., 2024, https://arxiv.org/abs/2307.03172). Stuffing your entire project history into context is not only expensive, it is unreliable.

Third, context is undifferentiated. A transcript contains everything: the useful architectural decision and the fourteen failed attempts that preceded it. What you actually want to carry forward is a distilled fact ("we chose SQLAlchemy 2.0 style because of X"), not the raw log that produced it.

What MAG Is

Memory-Augmented Generation extends an LLM with an external memory system that persists across sessions and is actively managed: written to, consolidated, retrieved from, and pruned. The term was formalized in the MemOS paper (Li et al., 2025, https://arxiv.org/abs/2505.22101), which argued that LLMs need memory as a first-class architectural concern rather than an afterthought, and distinguished three memory types: parametric memory (knowledge baked into weights), activation memory (the ephemeral runtime context), and plaintext memory (external, editable knowledge). Earlier work in the same lineage includes MemGPT (Packer et al., 2023, https://arxiv.org/abs/2310.08560), which treated the LLM like an operating system paging data between a small "main context" and larger external storage.

The most useful way to understand MAG is by contrast with the pattern everyone already knows: Retrieval-Augmented Generation.

RAG retrieves. MAG remembers. RAG pulls relevant chunks from a static external corpus at query time; the corpus does not learn anything from the interaction. MAG adds a write path and a lifecycle: the system decides what is worth keeping from an interaction, merges it with what it already knows, retrieves it later, and eventually forgets what stopped being useful.

The loop on the right is the defining feature. A RAG system with a read-only vector database is not doing MAG, no matter how sophisticated the retrieval. MAG requires the write, consolidate, and forget stages. Pruning runs as a background sweep over the store rather than sitting inline in the loop, which matters later when we look at how Codex schedules it.

One terminology caveat for the careful reader: MAG is an emerging term, not a settled standard like RAG. Much of the industry still says "agent memory," and there is a separate framework called MMAG (Mixed Memory-Augmented Generation, Zeppieri, 2025, https://arxiv.org/abs/2512.01710) that organizes agent memory into five cognitive layers. Do not confuse the two.

Case Study: How Codex Remembers

Codex, OpenAI's coding agent, ships a two-layer memory model that maps almost perfectly onto the static-versus-lifecycle distinction above. Both layers are documented at https://developers.openai.com/codex.

Layer 1: AGENTS.md, the static layer

AGENTS.md is a markdown instruction file that Codex reads at the start of every session. It follows a cross-tool open convention (https://agents.md) also used by Cursor, Aider, and others. Codex discovers these files hierarchically: a global one at ~/.codex/AGENTS.md, then every AGENTS.md from the repository root down to the working directory, concatenated in path order.

This layer is for stable facts: the test command, the deploy process, code style rules, which modules are fragile. It is source-controlled, team-shareable, and fully under human control.

It is also, strictly speaking, not memory. It is configuration. A human writes it, a human maintains it, and it captures only what someone remembered to write down. The Redis quirk you discovered on Tuesday afternoon does not appear in AGENTS.md unless you put it there. And there is a hard practical limit: the combined file content is capped at 32 KiB by default, and truncation past the cap is silent.

Layer 2: Memories, the generated layer

The second layer is where Codex actually implements MAG. Codex summarizes its own prior sessions in the background and writes the results to ~/.codex/memories/, which subsequent sessions read. Note that this layer is off by default: you have to enable it in ~/.codex/config.toml (see the config reference in the official docs). The pipeline, per OpenAI's documentation and the analysis at https://mem0.ai/blog/how-memory-works-in-codex-cli, works like this:

Several design choices are worth noticing because they generalize beyond Codex:

Consolidation is asynchronous. A session must be idle for hours before it becomes eligible. Memory formation happens offline, not inline with generation, which keeps the interactive loop fast. This mirrors a broader industry pattern of background "sleep-time" consolidation.

Two models, two jobs. One model extracts candidate memories from a session; a second merges candidates into the existing store. Extraction and consolidation are different problems, and separating them lets each be tuned independently.

Forgetting is a feature. Memories that go unrecalled for thirty days are pruned. This is the counterintuitive part of MAG design: an ever-growing memory store degrades retrieval quality and accumulates stale facts, so deliberate forgetting improves the system.

Storage is plain markdown, and retrieval is grep. No vector database. At session start, Codex reads a consolidated memory_summary.md whole (third-party analysis of the open-source CLI puts a cap of roughly 5,000 tokens on this injection, a budget decision that parallels the 32 KiB AGENTS.md ceiling), then instructs the agent to grep over the long-form MEMORY.md when it needs detail. This is a real engineering tradeoff: lexical retrieval is fast, predictable, and debuggable (you can cat your agent's memory), but it cannot match a stored fact whose phrasing differs from the query. Embedding-based systems invert that tradeoff.

Trying it yourself

The experiment is simple, but two prerequisites will silently sink it if you skip them. First, Memories must be enabled in ~/.codex/config.toml; on a default install the feature is off and nothing will be written. Second, if your account is in the EEA, UK, or Switzerland, the Memories layer is not available at launch, and only the AGENTS.md layer applies.

With that out of the way:

Run a session and establish a project-specific fact conversationally, not via AGENTS.md. Something distinctive enough to be unambiguous, like a made-up internal codename for a service.
Close the session and wait past the idle window (six hours by default).
Inspect ~/.codex/memories/ and read memory_summary.md. Did the fact survive extraction and consolidation, and in what form?
Start a new session and ask a question that requires the fact. Check whether Codex recalls it unprompted, and whether it greps the long-form memory to do so.

The interesting result is not step 4 succeeding; it is comparing what you said in step 1 with what got written in step 3. The distance between the two is the extraction model's editorial judgment, and it is worth seeing with your own eyes before you trust it.

Where It Breaks

An honest treatment of MAG requires the failure modes, because they are not solved problems, in Codex or anywhere else.

Wrong memories compound. If the extraction model records a misleading conclusion in week one, the agent confidently applies it in week four. Codex does ship provenance in the narrow sense: memory entries can be traced back to the session files and line ranges they came from via citation blocks. What is missing is dispute semantics. There is no mechanism to mark a memory as contested or superseded; correction happens implicitly through consolidation, if it happens at all. Traceability tells you where a bad memory came from. It does not stop the agent from acting on it.

Staleness. Code changes; memories do not automatically notice. The memory saying "deploys go through make ship" survives the migration to a new deploy pipeline until it is either pruned by disuse or overwritten by a newer session. In the gap, the agent is confidently wrong, which is worse than ignorant.

No sharing, no sync. Codex memories are local, per-user generated state. A second laptop starts cold. A new teammate inherits nothing from the team's accumulated agent context except what made it into the checked-in AGENTS.md. This is exactly the gap that external memory layers (Mem0, and open-source projects like agentmemory) exist to fill via MCP, at the cost of adding a dependency and, for hosted options, sending your project context to a third party. Disclosure: Mem0 sells exactly this layer, so its analysis of Codex's gaps, cited above, should be read with that in mind. The gaps are real; the framing is a sales funnel.

Privacy surface. A system that automatically summarizes everything you do and writes it to disk is a system that can memorize secrets. Codex ships secret redaction in the pipeline, but redaction is pattern-matching, and pattern-matching misses things.

Conclusion

MAG is the recognition that statelessness, the property that made LLMs simple to reason about, is the main obstacle to making them useful collaborators over time. Codex's implementation shows what the pattern buys, an agent that stops asking what database you use, and how early we still are: the failure modes above are open problems, not edge cases. RAG took roughly three years to go from the 2020 paper to standard practice. Memory looks to be on a similar trajectory, and those open problems are where the next few years of work will happen.

References

Li, Z. et al. (2025). MemOS: An Operating System for Memory-Augmented Generation (MAG) in Large Language Models. https://arxiv.org/abs/2505.22101
Packer, C. et al. (2023). MemGPT: Towards LLMs as Operating Systems. https://arxiv.org/abs/2310.08560
Liu, N. F. et al. (2024). Lost in the Middle: How Language Models Use Long Contexts. https://arxiv.org/abs/2307.03172
Zeppieri, S. (2025). MMAG: Mixed Memory-Augmented Generation for Large Language Models Applications. https://arxiv.org/abs/2512.01710
OpenAI. Codex documentation: AGENTS.md guide, Memories, and config reference. https://developers.openai.com/codex
AGENTS.md open specification. https://agents.md
Sangshetti, H. (2026). Codex CLI Memory: How It Works. Mem0 blog. https://mem0.ai/blog/how-memory-works-in-codex-cli (third-party analysis by a vendor selling an external memory layer; used where official docs are thin, with that conflict of interest in mind)
Codex Knowledge Base (2026). Codex CLI Memory Internals: Pipelines, Secret Sanitisation and Intelligent Forgetting. https://codex.danielvaughan.com/2026/04/08/codex-cli-memory-internals/ (third-party analysis of the open-source CLI; source for the citation-block provenance mechanism and the memory summary token cap)

The one seam, shown: Inline up close

Ernesto Herrera Salinas — Thu, 30 Jul 2026 00:47:19 +0000

In post 10 I closed the composition-versus-coherence question with one paragraph: I
kept strict object-scoping, reserved an Inline operator for later, and rejected
automatic reach-down. That was true, and it was too fast. A reader told me the
reserved operator was not clear from a sentence, which is fair. A design record that
asserts a decision without showing it is not really a record. So here is the seam,
worked out.

First, the good news that made this only one seam and not ten: composition and
coherence mostly do not collide. Composition substitutes complex types; coherence
binds scalar facets; those are disjoint kinds of member. A collection gives one
persona per element. Draw order falls out of the eager construction rule from post 7.
And the resolver pipeline I pre-paid for back in post 4 turned out to be coherence's
host. The two threads layer cleanly almost everywhere. Almost.

The discontinuity

Coherence is object-scoped (post 5). That one rule has a consequence that only shows
up once you have composition encouraging you to split a type across nested objects:
moving a facet into a child changes whether it coheres.

// Flat: Email is a Person facet, so it coheres with the name.
Customer { FirstName, LastName, Email }
//   -> "Maria", "Gonzalez", "maria.gonzalez@..."

// Decomposed: Contact is its own scope. A lone Email there does not activate a
// persona (one corroborating member, no name anchor), so it is a plain, unrelated email.
Customer { FirstName, LastName, Contact : ContactInfo { Email } }
//   -> "Maria", "Gonzalez", "rwilson@..."

Same three fields, same intent, different result, decided entirely by which object
they live on. That is the discontinuity.

The options

A, strict: object-scoping stays. The decomposed email does not cohere.
   Maximally predictable. The gap is the already-deferred cross-entity work.

B, reach-down: a child with no entity of its own is absorbed into the parent scope.
   The email coheres. But "absorbed or not" now depends on hidden conditions.

C, Inline: an explicit operator that declares a child shares the parent's scope.
   Coheres when you say so, stays strict otherwise.

I kept A as the v1.1 default and reserved C. The rest of this post is C, shown,
because a reserved operator you cannot picture is not a real reservation.

Inline, in three scenarios

Inline declares that a nested child shares its parent's scope: its scalar facets
lift into the parent's bundle. The child is still a real object; only its coherence
scoping changes.

Scenario one, the plain case. It pulls a value-object's fields into the persona:

Lie.Define<Customer>()
    .Inline(c => c.Contact)        // Contact.Email/Phone join Customer's persona
    .Build();
//   FirstName="Maria"  LastName="Gonzalez"
//   Contact.Email="maria.gonzalez@..."   Contact.Phone= the Person's phone

Scenario two, where it changes activation, not just correlation. A parent with only
an Email and a nested { First, Last } activate nothing on their own; inlined, they
clear the gate together and become one person:

// Account { Email, Name : NameParts { First, Last } }
.Inline(a => a.Name)
//   Name.First="David"  Name.Last="Okafor"
//   Email="david.okafor@..."   <- now the same Person; without Inline it was unrelated

Scenario three, the one that turns a silent wrong-look into a fix. Decompose an
address across two blocks and each block coheres into a different real place:

// Office { City, State, Postal : PostalBlock { PostalCode, Country } }
// default:  City/State = Austin, Texas   and   PostalCode/Country = a German ZIP + Germany
.Inline(o => o.Postal)
//   one real row projects across both: Austin, Texas, 78701, United States

Each block was internally consistent and the object as a whole was nonsense. Inline
makes the two blocks one row.

What Inline does not do

A reserved feature is only honest if its limits are stated with its powers. Inline
does not do cross-entity correlation: an inlined person and an inlined address are
still independent bundles, so the person does not "live at" the address. It does not
split a collapsed same-type scope (two people flat on one object is still the deferred
case). And it loses to explicit rules, like every automatic-tier facet does (post 8).

Why reach-down lost

The deciding argument is the same spine the whole series runs on. Inline is a line
in your definition, so Explain can name it:

Office.Postal.PostalCode -> Address.PostalCode   [coherent entity]  (inlined from Postal)

Reach-down would produce the same coherent values with no declaration anywhere to
point at. The report could only say "absorbed," and you would have nothing in your
own code that explains why. A coherent value you cannot trace is exactly the kind of
magic the rigor lane exists to avoid.

Takeaway

Show, do not assert: a reserved operator you cannot picture is not a reservation, it
is a promissory note. And when two features meet, prefer the seam you can explain over
the convenience you cannot. Inline ships later, alongside the cross-entity work it
belongs with, but the default it sits on top of, strict and legible, is the v1.1
decision.

What's next

This second pass through the design added exactly one decision and a lot of
consolidation. The last post is about that: the ledger of everything I have promised
but not shipped.

Skill Opt: Training the Skill File Instead of the Model

Ernesto Herrera Salinas — Mon, 27 Jul 2026 13:32:44 +0000

I started with a weird question:

What if I cannot train the model, but I can train the instructions around the model?

Not fine-tuning. Not LoRA. Not changing weights. I mean taking a closed model, wrapping it with a SKILL.md file, running benchmarks against it, editing the skill, measuring again, and repeating the loop until the benchmark improves.

Basically:

Sentences become parameters.
Edits become optimization steps.
Benchmark score becomes the loss signal.
The model stays frozen.
The skill gets trained.

That idea is not as strange as it sounds. It sits at the intersection of Agent Skills, automatic prompt optimization, textual gradients, eval-driven development, and black-box optimization.

I would call this idea Skill Opt.

The model is closed, but the behavior is not

A closed model does not give you access to weights, gradients, optimizer state, or training data. You cannot backpropagate through it in the classical machine-learning sense.

But modern AI systems are not only the model. They are the model plus instructions, tools, retrieval, examples, policies, workflows, and context.

Agent Skills make this explicit. The Agent Skills specification defines a skill as a directory that contains, at minimum, a SKILL.md file. That file contains YAML frontmatter plus Markdown instructions. The required frontmatter fields are name and description, and the Markdown body contains the operational instructions the agent should follow. Skills can also include scripts, references, assets, and other supporting files.

So SKILL.md is not just documentation. It is executable behavior in text form. The agent reads it, decides when it applies, and uses it to guide actions.

That means the model is frozen, but the system behavior is still tunable.

That is the core of Skill Opt.

`SKILL.md` as a parameter surface

In normal training, parameters are numbers. You compute a loss, estimate a gradient, update the numbers, and run again.

In Skill Opt, the parameters are not numbers. They are pieces of text:

Machine learning concept	Skill Opt equivalent
Model weights	Sentences, examples, constraints, workflows, and scripts in `SKILL.md`
Forward pass	Run the agent against an eval prompt
Prediction	The artifact, answer, code, file, or action produced by the agent
Loss	Failed assertions, low benchmark score, wrong tool usage, wasted tokens, wrong skill triggering
Gradient	Natural-language critique explaining what went wrong
Optimizer step	Edit the skill
Epoch	One full benchmark pass
Validation set	Prompts not used while editing the skill
Overfitting	A skill that passes your exact tests but fails on real prompts

The Agent Skills docs already recommend a version of this loop for descriptions. They suggest building labeled trigger queries, running them multiple times because model behavior is nondeterministic, measuring trigger rate, splitting train and validation sets, revising only from train failures, and selecting the best version by validation pass rate.

For output quality, they recommend structured eval cases with realistic prompts, expected outputs, optional files, baseline comparisons, assertions, grading evidence, aggregate pass rates, token counts, timing, human review, and iteration.

That is already optimization. Skill Opt just makes the analogy explicit and extends it from the description field to the whole skill.

The research already points in this direction

The closest research family is automatic prompt optimization.

Automatic Prompt Engineer, or APE, treats instructions as programs. It asks an LLM to generate candidate instructions, evaluates them with a score function, and keeps the best candidates. The paper reports that automatically generated instructions outperform a prior LLM baseline and are better than or comparable to human-written instructions on 19 of 24 tasks.

Automatic Prompt Optimization with “Gradient Descent” and Beam Search gets even closer to the Skill Opt metaphor. It uses minibatches of examples to produce natural-language “gradients” that criticize the current prompt, then edits the prompt in the opposite semantic direction of that critique. The method is guided by beam search and bandit selection, and the paper reports improvements of up to 31 percent.

OPRO, or Optimization by PROmpting, treats the LLM itself as the optimizer. It gives the model previous candidate solutions and their scores, then asks it to generate better candidates. In prompt optimization experiments, OPRO found prompts that outperformed human-designed prompts on GSM8K and Big-Bench Hard tasks.

TextGrad takes the analogy even further. Instead of numerical gradients, it uses natural-language feedback from LLMs to improve components of compound AI systems. The authors frame this as automatic “differentiation” via text and report improvements across question answering, coding, reasoning prompts, molecule optimization, and radiotherapy treatment planning.

DSPy abstracts language-model pipelines as text transformation graphs and uses a compiler to optimize them against a metric. This is important because Skill Opt is not only prompt editing. It is closer to optimizing a small language-model program made of instructions, examples, scripts, and resources.

MIPRO optimizes instructions and demonstrations for multi-stage language-model programs without access to module-level labels or gradients. That maps well to skills because a good skill often includes multiple steps where only the final artifact is scored.

GEPA uses natural-language reflection and Pareto-style evolution to improve prompts in compound AI systems. This is highly relevant because skill quality is multi-objective: correctness, cost, latency, safety, and maintainability can all matter at once.

PromptBreeder evolves task prompts and also evolves the mutation prompts that generate new task prompts. That is very close to the idea of an optimizer improving not only the skill, but also the way skill edits are proposed.

Self-Refine and Reflexion show that LLM systems can improve outputs or future behavior through iterative feedback without changing model weights. Self-Refine uses the same model to generate feedback and revise its own output, while Reflexion stores verbal lessons learned in memory to improve future trials.

Together, these papers point to the same conclusion:

Even when model weights are fixed, text around the model can be searched, scored, criticized, mutated, selected, and improved.

Skill Opt applies that pattern to SKILL.md.

The Skill Opt loop

A practical Skill Opt loop would look like this:

skill_version = SKILL.md v1

repeat:
  run benchmark prompts with skill_version
  collect outputs, tool calls, token usage, duration, and failures
  grade with assertions, scripts, LLM judges, and human review
  summarize failures as natural-language gradients
  propose candidate edits to SKILL.md
  run candidates on train evals
  promote the best candidate by validation score
  save the winning version
until validation score stops improving

The critical part is that the benchmark must be external to the optimizer. If you edit the skill using all test cases, you are not training. You are memorizing.

The Agent Skills docs explicitly warn about this for description optimization: split the query set into train and validation, use only train failures to guide changes, and select the best version by validation pass rate.

The same rule should apply to the entire skill.

What exactly gets optimized?

A skill has several trainable surfaces.

1. The description

The description field is the trigger. If it is too vague, the skill does not activate. If it is too broad, it activates when it should not.

The Agent Skills docs say the description is the primary mechanism agents use to decide whether to load a skill for a task.

So description optimization is like optimizing the router.

A weak description:

description: Helps with reports.

A trained description:

description: >
  Use this skill when the user asks to turn research notes, links,
  benchmark findings, or technical analysis into a structured engineering
  article. Apply it for DEV-style posts, architecture writeups,
  implementation retrospectives, and source-backed technical explainers.

That is not just better writing. It changes when the skill enters the context.

2. The body instructions

The body of SKILL.md is the behavioral contract. It can define:

Steps to follow.
Order of operations.
Quality bars.
Edge cases.
Formatting rules.
Forbidden shortcuts.
Validation steps.
Examples.

The Agent Skills specification recommends step-by-step instructions, examples of inputs and outputs, and common edge cases in the Markdown body.

Optimizing this section is like optimizing the policy the agent follows after activation.

3. Examples

Examples are high leverage. They show the model what good output looks like.

In Skill Opt, examples are not decoration. They are training-like demonstrations embedded in the runtime context.

You can add:

Positive examples.
Negative examples.
Edge cases.
Before and after transformations.
“Do not do this” examples.
Good and bad final artifacts.

Then you measure whether those examples improve benchmark performance.

4. References

References are long-form knowledge. They should not all live inside SKILL.md, because loading too much context can waste tokens and confuse the agent.

The Agent Skills specification recommends using focused reference files and loading them on demand. It also recommends keeping the main SKILL.md under 500 lines and moving detailed reference material to separate files.

Skill Opt should measure whether moving content into references improves quality, cost, or reliability.

5. Scripts

Scripts turn fragile natural-language instructions into deterministic operations.

The Agent Skills specification allows optional scripts/ directories for executable code, and the evaluation guide recommends verification scripts for checks like valid JSON, correct row counts, file existence, and expected dimensions.

So Skill Opt should not only ask:

Can better wording fix this?

It should also ask:

Should this instruction be code instead of text?

The benchmark is the loss

A skill without evals is just a belief.

To optimize a skill, you need a benchmark suite. At minimum, each eval should include:

A realistic user prompt.
Expected output.
Optional input files.
Assertions.
A baseline run without the skill or with the previous skill.
A score.

The Agent Skills evaluation guide recommends this exact style of eval-driven workflow: realistic prompts, expected outputs, optional files, with-skill and without-skill comparisons, assertions, grading evidence, aggregate pass rates, token counts, timing, and human review.

That gives you several possible loss signals:

Failed assertions.
Lower human preference score.
Worse LLM judge score.
More tokens for the same quality.
Longer runtime.
Wrong files created.
Wrong tool used.
Skill failed to trigger.
Skill triggered when it should not.
Unsafe or over-permissive behavior.

A good optimizer does not chase only one number. This is why GEPA’s Pareto-style approach is interesting: it treats optimization as a search across multiple objectives rather than a single scalar score.

The “gradient” is critique

The gradient in Skill Opt is not a vector. It is a diagnosis.

For example:

Failure pattern:
The agent produced a correct article structure, but it repeatedly forgot to include sources after technical claims.

Suggested semantic update:
Add a mandatory citation rule under the "Source handling" section. Require citations at the paragraph level for all factual claims derived from research, and require a final source list.

That critique becomes an edit.

This is the spirit of textual-gradient methods, but there is an important caveat: the gradient metaphor is useful, not literal. A 2025 paper argues that textual gradients often improve prompts, but the gradient analogy does not fully explain their behavior.

That warning matters.

Skill Opt should not pretend text optimization is mathematically equivalent to gradient descent. It should borrow the discipline of optimization without pretending the math is the same.

Skills are becoming software artifacts

The newest research makes Skill Opt feel less like a hack and more like an emerging engineering discipline.

A 2026 survey describes agent skills as composable packages of instructions, code, and resources that agents load on demand to extend capability without retraining.

A 2026 data-driven analysis of 40,285 public skills describes skills as reusable, program-like modules that define triggering conditions, procedural logic, and tool interactions. It also identifies safety risks, including skills that enable state-changing or system-level actions.

SkillsBench evaluates whether skills actually help. It reports that curated skills raise average pass rate by 16.2 percentage points across tested tasks, but effects vary by domain and some tasks show negative deltas. That is an important finding: skills can help, but they can also hurt.

A July 2026 paper studies how AI agent skills are written, adapted, and maintained. It treats skills as engineered artifacts whose content and evolution shape agent behavior. That framing is exactly what Skill Opt needs.

EvoSkills proposes self-evolving skill packages using a generator and verifier loop. It reports higher pass rates than several baselines on SkillsBench across Claude Code, Codex, and other LLMs.

AgentSkillOS looks at selection, orchestration, and benchmarking of skills at ecosystem scale, using capability trees, retrieval, DAG-based orchestration, and pairwise evaluation.

SkCC proposes compiling skills into a strongly typed intermediate representation to improve portability and security across agent frameworks. It reports pass-rate improvements, security-trigger results, and token savings.

All of this points in the same direction:

Skills are not just notes for the model. They are software artifacts that deserve tests, versioning, benchmarks, security review, and optimization.

The security problem: optimizing text can optimize bad behavior too

There is a dark side.

If SKILL.md is operational text, then malicious or careless text can change agent behavior.

A 2026 paper on semantic supply-chain attacks argues that SKILL.md is not passive documentation. It can influence discovery, selection, and governance. The paper reports that short textual triggers can improve adversarial skill visibility, description framing can bias agents toward adversarial variants, and semantic evasion can help malicious skills avoid blocking.

Another paper argues that Agent Skills enable realistic and simple prompt-injection attacks, including malicious instructions hidden inside long skill files or referenced scripts.

A 2026 paper on dynamic malicious skills shows that malicious instructions embedded in natural-language documentation, including SKILL.md, can induce an agent to dynamically inject malicious logic during execution.

This matters for Skill Opt because optimization pressure can accidentally reward unsafe behavior. If the only benchmark is “complete the task,” the skill may learn to be pushier, skip confirmation, overuse tools, or hide uncertainty.

So the loss function must include safety:

Do not optimize only for pass rate.
Include permission boundaries.
Include negative tests.
Include prompt-injection tests.
Include tool-use constraints.
Include human review for high-risk actions.
Version-control every skill edit.
Treat third-party skills like code, not like harmless documentation.

A skill optimizer without safety evals is just a bug generator with good intentions.

What Skill Opt is, and what it is not

Skill Opt is not model training.

It does not make the base model smarter in the weight-level sense. The model has not learned permanently. If you remove the skill, the behavior disappears.

But Skill Opt can make the system smarter in the engineering sense. The agent behaves better because the context, instructions, examples, scripts, activation rules, and validation loops are better.

That distinction is important.

We are not training the model.

We are training the interface between the model and the work.

Why this matters

Most teams cannot train frontier models. They cannot see the weights, modify the architecture, or run gradient descent over the model itself.

But they can write skills.

They can benchmark skills.

They can edit skills.

They can version skills.

They can compare skills.

They can build evals around skills.

That makes SKILL.md one of the most practical optimization surfaces available to people using closed AI systems.

The big idea is simple:

A closed model does not mean a closed system.

If the model is frozen, train the skill.

References

Agent Skills Overview
URL: https://agentskills.io/
Agent Skills Specification
URL: https://agentskills.io/specification
Agent Skills: Optimizing Skill Descriptions
URL: https://agentskills.io/skill-creation/optimizing-descriptions
Agent Skills: Evaluating Skill Output Quality
URL: https://agentskills.io/skill-creation/evaluating-skills
Zhou et al., “Large Language Models Are Human-Level Prompt Engineers”
URL: https://arxiv.org/abs/2211.01910
Pryzant et al., “Automatic Prompt Optimization with ‘Gradient Descent’ and Beam Search”
URL: https://arxiv.org/abs/2305.03495
Yang et al., “Large Language Models as Optimizers”
URL: https://arxiv.org/abs/2309.03409
Yuksekgonul et al., “TextGrad: Automatic ‘Differentiation’ via Text”
URL: https://arxiv.org/abs/2406.07496
Khattab et al., “DSPy: Compiling Declarative Language Model Calls into Self-Improving Pipelines”
URL: https://arxiv.org/abs/2310.03714
Opsahl-Ong et al., “Optimizing Instructions and Demonstrations for Multi-Stage Language Model Programs”
URL: https://arxiv.org/abs/2406.11695
Agrawal et al., “GEPA: Reflective Prompt Evolution Can Outperform Reinforcement Learning”
URL: https://arxiv.org/abs/2507.19457
Fernando et al., “Promptbreeder: Self-Referential Self-Improvement Via Prompt Evolution”
URL: https://arxiv.org/abs/2309.16797
Madaan et al., “Self-Refine: Iterative Refinement with Self-Feedback”
URL: https://arxiv.org/abs/2303.17651
Shinn et al., “Reflexion: Language Agents with Verbal Reinforcement Learning”
URL: https://arxiv.org/abs/2303.11366
Wang et al., “Voyager: An Open-Ended Embodied Agent with Large Language Models”
URL: https://arxiv.org/abs/2305.16291
Melcer et al., “Textual Gradients are a Flawed Metaphor for Automatic Prompt Optimization”
URL: https://arxiv.org/abs/2512.13598
Ling et al., “Agent Skills: A Data-Driven Analysis of Claude Skills for Extending Large Language Model Functionality”
URL: https://arxiv.org/abs/2602.08004
Li et al., “SkillsBench: Benchmarking How Well Agent Skills Work Across Diverse Tasks”
URL: https://arxiv.org/abs/2602.12670
Xu and Yan, “Agent Skills for Large Language Models: Architecture, Acquisition, Security, and the Path Forward”
URL: https://arxiv.org/abs/2602.12430
Gao et al., “From Registry to Repository: How AI Agent Skills Are Written, Adapted, and Maintained”
URL: https://arxiv.org/abs/2607.00911
Zhang et al., “CoEvoSkills: Self-Evolving Agent Skills via Co-Evolutionary Verification”
URL: https://arxiv.org/abs/2604.01687
Li et al., “Organizing, Orchestrating, and Benchmarking Agent Skills at Ecosystem Scale”
URL: https://arxiv.org/abs/2603.02176
Ouyang et al., “SkCC: Portable and Secure Skill Compilation for Cross-Framework LLM Agents”
URL: https://arxiv.org/abs/2605.03353
Saha et al., “Under the Hood of SKILL.md: Semantic Supply-chain Attacks on AI Agent Skill Registry”
URL: https://arxiv.org/abs/2605.11418
Schmotz et al., “Agent Skills Enable a New Class of Realistic and Trivially Simple Prompt Injections”
URL: https://arxiv.org/abs/2510.26328
Chen et al., “Dynamic Malicious Skills in Agentic AI”
URL: https://arxiv.org/abs/2606.16287

Decided is not done: taking stock before adding more

Ernesto Herrera Salinas — Fri, 24 Jul 2026 18:48:20 +0000

The first session ended at post 10. The design did not. I came back to it and, before writing a single new decision, asked the least glamorous question a solo project can ask itself: how far along is this, really, and what would it take to call it ready for someone else to review in depth?

The answer was more useful than I expected, because it forced a distinction I had been blurring: a settled mechanism is not a hardened design.

The fork: promote now, or hold and harden

Composition was already reconciled into the binding docs. Coherence had seventeen recorded decisions covering the whole load-bearing core: binding, determinism, precedence, persona content, gender, explainability, detection, activation, the explicit accessor, and a second entity proving the abstraction generalizes. It was tempting to call that reviewable and promote it too.

A: promote coherence into the binding docs now.
   17 decisions, self-consistent, composition already went. Looks done.

B: hold. The mechanism is settled, but the seams between features are not.
   Harden first, promote second.

I took B. The tell was that I could not yet answer a reviewer's most obvious question, "what happens when a composed child is itself a person," without pointing at an open fork. A design you cannot stress at the seams is decided, not done.

What "hardened" actually means

The value of taking stock was turning a vague "almost there" into a concrete,
finite list. Three passes stand between the current state and an in-depth review:

1. Cross-feature interaction pass.
   Where correctness bugs hide once two features exist. Composition x coherence is
   done (next post). Uniqueness, null-probability, and locale remain.

2. Surface-enumeration pass.
   Collect every public member the design has accumulated into one list to accept
   or cut. Public surface is locked, so this is the gate that matters most.

3. Consistency re-read.
   Read all the decisions straight through for contradictions and stale
   cross-references, the kind that creep in when you decide one fork at a time.

Only after those does coherence get promoted into the binding docs. The interaction
pass goes first on purpose: it is the one most likely to send an earlier decision
back for revision, and there is no point freezing a surface that a later pass might
reopen.

Why this is allowed to be slow

This is the brief doing its job again. Solo, no deadline, quality over speed is
exactly the license to harden before review instead of shipping a plausible-looking
design and patching it under pressure later. It is also why I keep refusing to frame
this work as a countdown to code. "Ready to build" is a finish line that a design in
this phase does not have and should not pretend to.

Takeaway

Before you add the next feature, find out whether the last ten are actually done or
merely decided. The useful output of taking stock is not a percentage, it is a short
list of named hardening passes that make the gap between "I made these decisions" and
"someone could review this" explicit and finite.

What's next

First pass on the list is the cross-feature interactions, and the sharpest one is
where the two big v1.1 threads touch. Post 10 asserted that boundary in a single
paragraph. A reader, reasonably, asked me to actually show it. Next post: the seam,
worked out in full.

Proving it generalizes: Person to Address

Ernesto Herrera Salinas — Tue, 21 Jul 2026 23:25:57 +0000

A persona engine that only does Person is a Person feature wearing the costume of an abstraction. The whole bet behind making coherence a descriptor-driven stage was that a second entity would be nearly free. Address was the test, and it is where the first session closes.

The second instance was nearly free

Address coherence means City, State, PostalCode, and Country agree. It reuses the exact detection and activation machinery from Person: a second descriptor that claims the existing address generators from the catalog, gated by the same corroboration-count activation. The only structural difference is that Address has no name anchor (there is no "FirstName of an address"), so its activation gate is pure corroboration count rather than anchor-plus-count. One genuine difference, and the framework absorbed it. That is the signal an abstraction is real.

One honest difference: how the bundle draws

The interesting part is where Person and Address diverge, because it taught me what the descriptor actually abstracts.

Person:  correlated draws. Draw a gender, then a name that matches it, then ...
Address: row-projection.   You CANNOT synthesize a coherent address field by field
         (a random City plus a random State plus a random ZIP is nonsense).
         So draw ONE real (country, state, city, postal, lat, lng) tuple, and let
         the facets project from that row. Street and countryCode derive.

A descriptor does not just list facets. It owns "how to draw the bundle." For Person that is a sequence of correlated draws; for Address it is a single row lookup; the facets project either way. Same stage, same activation, two completely different generation strategies behind one abstraction.

A set of entities, not one persona

Generalizing also forced a small reframe. One object can host a Person and an Address at the same time, so the activation pre-pass resolves a set of entities per object, each drawing in registration order. Nested entities fall out of object-scoping for free: a nested Address is its own scope and coheres on its
own. (Two addresses flat on one object is still the deferred two-people case.)

Where the data comes from

Filling the address row table is a brief-shaped decision. Consistent with owning the rigor lane, core ships a small set of curated, real en tuples, where coherence is guaranteed because the data is real. Breadth comes through data packs, not core, and synthesis is used only where ground truth is impractical (street
numbers are always synthesized). Rigor in core, breadth at the edges.

Where composition and coherence meet

The last thing I checked was whether the two big v1.1 threads collide. Mostly they do not: composition substitutes complex types, coherence binds scalars, disjoint kinds, and the resolver pipeline I pre-paid for is coherence's host. The one genuine fork is a decomposition discontinuity: because coherence is object-scoped,
moving a facet into a nested object changes whether it coheres with its old siblings. I kept strict object-scoping as the v1.1 default (predictable and explainable) and reserved an explicit Inline operator to ship later alongside cross-entity correlation. Automatic reach-down lost, because cross-boundary magic is exactly the kind of thing that cannot be explained.

Takeaway

An abstraction earns its keep when the second instance is nearly free and the third is obvious. And when two systems meet, prefer the boundary you can explain over the convenience you cannot. That single rule, local and diagnosable over non-local and silent, turned out to be the spine of nearly every decision in this
series.

Where this leaves the first session

Coherence is worked through its load-bearing core and stays open on purpose: Company and temporal entities, cross-entity correlation (the person who lives at the address), and the catalog and dataset work all still have surface left. None of it is built. It is design, made deliberately and held revisitable, which is exactly where I want a library that intends to be the rigorous one to start.

Thanks for reading along this first pass. The whole point of building in public is that the reasoning is the product as much as the code is.

A believable person, and making it honest

Ernesto Herrera Salinas — Sat, 18 Jul 2026 00:25:51 +0000

Two things were still missing before the persona was presentable. It had to be fully believable, not half-coherent, and it had to be honest about what it had done. Three decisions covered both.

Correlate fully, or not at all

The first fork was how deep the correlation goes. Name-coherence only (first, last, full, email, username agree) is cheaper. But half-coherence is its own kind of broken: a FirstName of "Maria" next to a Salutation of "Mr.," or an Age that contradicts the BirthDate, looks as wrong as fully random data, and the seed/demo reader is exactly the person who notices.

So the persona is a full bundle. Some facets are drawn, the rest derive with no extra randomness:

drawn:   gender, firstName (conditioned on gender), lastName,
         birthDate (adult-aged, off the operation's reference time),
         phone (locale format), emailDomain
derived: fullName, initials, email, username, salutation (from gender),
         age (from birthDate + reference time)

This is not free: it adds a dataset dependency, first names tagged by gender. I accepted that, because the alternative is data that fails the two-second believability test.

Gender, without shipping a gender enum

The persona needs an internal gender axis to pick a coherent name and salutation.
That raised a question I wanted to handle carefully: does Munchausen now ship a public gender enum? I decided no.

The fork was whether to leave a model's own gender field alone (and risk it contradicting the name) or bind it. I bind it, by adapting to whatever type the model already declares:

class Account { string FirstName; string Gender; }                 // string -> "Female"
class Profile { string FirstName; Sex Sex; } enum Sex { Female, Male, Unspecified }
                                                                    // enum -> Sex.Female
class Contact { string FirstName; }                                // no gender field
                                                                    // axis still drives the name

A string member gets "Female" or "Male". An enum member gets the value whose name matches the internal axis, falling back to ordinary inference when nothing matches. Munchausen never defines the categories itself; it mirrors the type the model declares, and the explicit d.Person.Gender is a plain string for the same
reason. The internal-axis-only option lost because it leaves the gender field free to contradict the name, which is the exact incoherence I was removing, just moved one field over.

Make it inspectable

Explainability is a differentiator on the rigor axis, so coherence cannot be a silent behavior. Each persona-bound member reports a new source, InferenceSource.CoherentEntity, and Explain() shows it plainly:

Contact.FirstName  -> Person.First     [coherent entity]
Contact.LastName   -> Person.Last      [coherent entity]
Contact.Email      -> Person.Email     [coherent entity]   (fulfills [EmailAddress])
Contact.Gender     -> Person.Gender    [coherent entity]

You can see which members share one identity (they all say Person.*), and the compose decision from the last post shows up inline on Email. The same report is what makes the two-people collapse diagnosable.

Takeaway

Correlate fully or not at all, because partial coherence reads as broken. Adapt to the types your users declare instead of legislating your own. And never let an automatic behavior be opaque: inference you can read is inference you can trust.

What's next

A persona engine that only does Person is just a Person feature with extra steps. The real test of the abstraction was a second entity. Next post: proving it generalizes, from Person to Address.

Composing with attributes, not fighting them

Ernesto Herrera Salinas — Fri, 17 Jul 2026 01:49:08 +0000

Every inference feature eventually has to answer one question: who wins when two of us want the same member? For coherence, the sharp version of that question is attributes. A model that annotates its email is both telling the validator something and, now, overlapping with the persona.

public sealed class Contact
{
    public string FirstName { get; set; }   // persona facet
    public string LastName  { get; set; }   // persona facet

    [EmailAddress]                           // an attribute, on a persona facet
    public string Email     { get; set; }
}

The persona wants Email to be maria.garcia@..., coherent with the name. The [EmailAddress] attribute wants "an email." A registered custom provider might want it too. So where does the persona sit in the precedence chain?

Three options

A, conservative: persona below attributes.
   [EmailAddress] selects a generic email generator -> "k9x@host.net"
   Valid, but NOT coherent. Annotating your model quietly loses coherence.

B, aggressive: persona above providers and attributes.
   Persona's coherent email wins -> "maria.garcia@ex.com"
   Coherent, but it silently overrides a provider you deliberately registered.

C, compose: persona at the automatic tier.
   It FULFILLS a select attribute coherently ([EmailAddress] is satisfied by a
   coherent, valid email), is NARROWED by a constraint attribute ([StringLength]),
   beats plain semantic/type, and loses to explicit rules and providers.

The choice

C, compose. It is the only one that maintains coherence across annotated models, which is the common shape for seed data, while still letting an explicit provider win, which is what a user most clearly meant.

What made C feel principled rather than like a special case is that it rests on a distinction the API already had: semantic attributes select a generator, constraint attributes narrow values. [EmailAddress] selects "email," and a coherent email is an email, so the persona fulfills it. [StringLength] narrows, so the persona facet gets narrowed to fit. The persona did not need a new tier bolted on top of the precedence list. It slotted into a model that was already there.

The conservative option lost because it punishes you for annotating your model, which is exactly the kind of surprise that erodes trust. The aggressive option lost because "automatic inference silently overrode the provider I registered" is a worse surprise. Compose avoids both: the explicit thing always wins, the automatic thing fills in coherently, and the attribute gets honored either way.

Takeaway

Precedence is where features negotiate, and the best outcome is usually compose, not override. Before you add a new priority tier, look for the distinction your system already makes (here, select versus narrow) and slot the new feature into it. A feature that fits the existing model is easier to learn and far easier to
trust than one that fights it.

What's next

The persona can now bind, draw deterministically, and negotiate precedence. Two things remain before it is presentable: it has to be fully believable, and it has to be honest about what it did. Next post: a believable person, and making it honest.

The PRNG draw-tape: eager versus lazy

Ernesto Herrera Salinas — Wed, 15 Jul 2026 01:24:53 +0000

Munchausen makes one absolute promise: same seed, same data, forever, on any machine. A persona is "generated once," which raises a question that sounds like an implementation detail and is actually part of the contract: once where in the random stream? Get this wrong and a harmless code change silently changes everyone
who upgrades.

Picture the operation's randomness as a tape of draws, d0, d1, d2, ..., consumed in order. The persona bundle eats a fixed block of them (gender, then a matching first name, then a last name), and any independent member, say Age, draws on its own. The fork is where the bundle's block lands.

public sealed class Customer
{
    public string FirstName { get; set; }  // persona facet
    public int    Age       { get; set; }  // independent
    public string LastName  { get; set; }  // persona facet
    public string Email     { get; set; }  // persona facet (derived from name)
}

The two options, made concrete

Both are equally coherent. The difference is stability when the model changes.
Watch what happens when Age moves to the top of the type.

A, eager at construction: draw the bundle as a fixed block before any member.
   bundle[d0,d1,d2] -> Age=d3, FirstName/LastName/Email read cached facets
   Move Age to the top? Bundle is still first, person-members consume nothing,
   so NOTHING changes. Age stays 34, the name stays Maria Garcia.

B, lazy at first persona-member: draw the bundle at that member's slot.
   Age=d0 -> FirstName triggers bundle[d1,d2,d3]
   Move Age to the top and the whole tape slides: Age draws d0 instead of d3,
   the bundle shifts, every value changes.

The choice

Eager, at construction. The deciding property is stability. Under eager, the persona draws as one block before member population, and the bound members are invisible to the stream, so reordering fields or adding a new facet does not move the values you already have. That matters most for the seed/demo job, where people edit their models constantly. Eager also fits the eager-Build philosophy of the whole library: the entity is drawn with the object, at a single point a golden test can pin.

It costs one small, well-defined thing: person-members no longer draw at their own position in member order, which is a deliberate departure from the per-member rule the rest of the library follows. I decided that is a fair price for reorder invariance on exactly the fields people most want to stay put.

There is one lazy corner, and I want to name it rather than hide it. The explicit d.Person accessor, read on an object that never activated a persona, materializes one on first access. That single path is order-dependent, because it draws when the delegate runs. It is the documented exception that proves the eager rule, and an
opt-in to force it eager is reserved for later.

Takeaway

In a deterministic system, "when you draw" is as much a part of the contract as "what you draw." When you choose, optimize for the changes your users will actually make. Reordering fields and adding a property are routine, so the draw rule that survives both is the right one, even at the cost of a small inconsistency elsewhere.

What's next

A persona does not generate in isolation. It has to negotiate with the rest of the inference pipeline, and the sharpest negotiation is with validation attributes.
Next post: composing with attributes, not fighting them.

Binding members to a persona without magic

Ernesto Herrera Salinas — Sun, 12 Jul 2026 02:34:17 +0000

Automatic coherence sounds like magic, and magic in a library is a liability.
The entire job in this part of the design was making it trustworthy: it has to fire when it should, stay silent when it should not, and be explainable when you ask. Several decisions, one theme.

Binding: automatic, with an explicit escape

First, how does a member get attached to its object's persona? I shipped two paths on purpose.

The primary path is automatic. Semantic inference, which already recognizes FirstName and Email, binds those members to the object's persona, so Lie<Customer>.Generate() comes out coherent with zero configuration. That is the seed/demo win, and it has to be the default because it is the only thing that reaches the headline one-liner.

The escape path is explicit: a d.Person accessor you can read inside a With or Derive rule when you want precision. It is a complement, not a replacement, and an explicit rule always overrides the automatic binding.

Where it lives: a stage, not a patch

Coherence is not bolted onto the semantic matcher. It is its own resolver stage on the ordered pipeline I pre-paid for earlier in the series, driven by an entity descriptor that maps roles to facets. That choice is what allows the same machinery to later serve Address and Company by adding a descriptor instead of rewriting the matcher. It also gives Explain() a real, first-class thing to report.

Detection: borrow the truth you already have

Now the part that decides whether the whole feature is trustworthy. How does the engine know FirstName is a person facet and Name on a Product is not?

The tempting move is to give the persona its own table of names it owns. I did not do that, because then two tables can drift. Instead, the persona piggybacks the existing semantic candidate table: a member binds to a facet when the semantic candidate it already wins is one the persona claims. One source of truth, no drift. And the existing model-hint disambiguation comes along for free:
Product.Name already resolves to a product-name candidate, never a person one, so coherence inherits that false-positive avoidance without writing a line of new
guarding.

Activation: gate on evidence

The last question is: when does an object get a persona at all? Always-on would be reckless. So activation reuses the inference mode the library already exposes (Conservative, Balanced, Aggressive) as an evidence dial, and counts corroborating role members:

Conservative: needs a name anchor (FirstName/LastName/FullName)
Balanced:     a name anchor, or two correlated members
Aggressive:   one matched member is enough
Disabled:     never

It is a build-time pre-pass, not a per-member check, and it self-limits the two-people collapse from the last post: prefixed, ambiguous members score low, so the mistaken merge only happens under Aggressive, where you asked for reach.

(Two smaller decisions ride along here: the explicit d.Person is a fixed snapshot of properties, not a generator, so reads inside a rule line up with the
auto-bound members; and reading it on an object with no activated persona materializes one lazily. That lazy draw is the one order-dependent corner in an otherwise eager design, and it is documented as such.)

Takeaway

Automatic behavior earns trust by reusing the system's existing truth and gating on evidence, not by inventing a parallel guesser that can drift or misfire. Magic
you can explain is just a feature. Magic you cannot is a support ticket.

What's next

I have been hand-waving one contractual detail: when exactly does a persona draw its random values from the stream? In a deterministic library, that is not a detail at all. Next post: the PRNG draw-tape, eager versus lazy.

Fake data that is not obviously fake

Ernesto Herrera Salinas — Thu, 09 Jul 2026 00:38:35 +0000

Back in the audit, I flagged a tension I had created for myself: I called seed and
demo data a co-equal job, then pointed the whole roadmap at composition, which
barely serves it. This post is where I start paying that off. It begins with an
ugly little object.

Here is what zero-config inference produces today, for a customer:

{
  FirstName: "Maria",
  LastName:  "Garcia",
  FullName:  "John Smith",          // unrelated to First/Last
  Email:     "k7zp@example.net",    // unrelated to the name
  Username:  "blue-tiger-441"       // unrelated again
}

For a unit test, nobody cares. Any plausible string is fine. But for seed data in
a demo database, this looks broken. A human reads it in two seconds and knows it
is fake. And this is precisely the job composition cannot help with, because
composition is about structure (which definition builds a nested object), and this
is about correlation between flat scalar fields. Different problem, different
machinery.

The idea: a persona

The fix is an idea Bogus already has, called Person: a coherent bundle generated
once, where the fields agree because they all come from the same underlying
identity. Munchausen's version has to be deterministic and inferred rather than
hand-wired, but the core is the same. There is a hidden Person for the object,
and FirstName, Email, and FullName are facets of it, not independent
guesses.

The load-bearing fork: what is one identity?

The first real decision is the one that sets the mental model for everything after
it: in an object graph, which members share a single persona?

class Customer { string FirstName; string LastName; string Email; SalesRep Rep; }
class SalesRep { string Name; string Email; }

A: object-scoped. Persona boundary equals object boundary.
   Customer.FirstName/LastName/Email -> Customer's persona (one identity)
   Rep.Name/Rep.Email                -> Rep's own persona  (a different identity)

B: role-scoped. Group by a member-name prefix, so two people flat on one object
   stay distinct (CustomerName vs SalesRepName).

I chose object-scoped. It is predictable, it needs no name-parsing heuristics, and
the boundary is something the user can already see in their own type. A nested
object simply gets its own identity, which is almost always what you want.

Object-scoping has a known sharp edge. If someone flattens two people onto one
type, Order { CustomerName, SalesRepName }, object-scoping makes them the same
person. That is wrong, and I did not pretend otherwise. I deferred role grouping
as a later refinement and made the collapse diagnosable through Explain(), which
will happily report "four members bound to one Person" so you can see it.

The reason I was comfortable deferring it: object-scoping already beats AutoBogus
for the common case, a single identity per object, which is most of the win. The
flat-two-people shape is a denormalized DTO that no tool handles automatically
today. So the principled default ships now, and the differentiator can come later
without repainting the model.

Takeaway

Coherence is not "better random values." It is a shared source of truth that
several fields read from. And the first decision in any system like that is the
boundary question: what counts as one identity? Pick the boundary your users can
already see, and be honest about the case it gets wrong.

What's next

A persona is only useful if members actually attach to it, and the attaching has
to be trustworthy rather than magic. Next post: binding members to a persona
without magic, including how the engine decides a field is a person at all.

Paying for the future on purpose

Ernesto Herrera Salinas — Tue, 07 Jul 2026 19:13:24 +0000

There is a category of design decision where the cheap option for the version you are shipping quietly mortgages the version after it. With a solo project and no deadline, I kept choosing to pay now. Here are the two clearest ases, and the principle that connected them.

Pre-pay one: structure over shortcuts

Composition adds rules to members. A collection member, for instance, might use a child definition for its elements, hold between two and five of them, and be null
ten percent of the time. v1.1 only needs the first of those. v1.2 wants all three stacked on one member. So how should a member hold its rules?

A: one rule per member, conflicts unless whitelisted.
   Stacking N features needs an O(N^2) compatibility matrix.

B: a member is a record of independent facets (element, size, null-probability).
   Stacking is free; only two rules of the SAME facet conflict.

Option A is less code for v1.1 today. Option B introduces a facet record now, for a feature that only uses one facet, which feels like over-building. I took B
anyway. The same logic applied one layer up: resolution became an ordered pipeline of stages rather than a stack of hardcoded if branches, so v1.2 can insert a stage by position instead of rewriting the branch.

The reason is the brief, not taste. Feature growth is an explicit goal, and there is no deadline. The design doc itself had concluded that the cheap options are the
only thing that would force v1.2 to reopen composition. When you can see the roadmap that clearly and you are not racing a clock, paying the structural cost
once is strictly better than paying interest on it every release. (This pipeline, it turns out, becomes the host for the entire coherence feature later in the series. The pre-pay compounded in my favor faster than I expected.)

Pre-pay two: a default that fails loudly

The second case is about composition boundaries. If you compose a reusable customer definition into an order, and that customer is silent about how money is generated, should a money rule you set on the order reach inside the customer?

Two pure answers, and the choice is really about how each one fails.

hermetic: the rule seals at the boundary. The customer generates its own way.
ambient:  the rule flows in. The customer's money becomes yours.

Ambient is convenient right up until it is not. The failure mode is that a distant ancestor silently mutates a fixture you wrote and tested, and you find out by
auditing the whole chain. Hermetic fails the other way: your rule under-reaches, you see the wrong value at your own call site, and the fix is local. Local and diagnosable beats non-local and silent. So the default is hermetic: a composed definition is a sealed contract.

But hermetic under-reaches on purpose, and sometimes you really do mean "every money value in this whole graph is in euros, no exceptions." For that I reserved
an escape valve, UseDeep, that a consumer writes explicitly and that always wins, penetrating any boundary. The fork there was whether reach should be the
consumer's call (UseDeep) or the author's (Sealed/Open on the definition). I took a hybrid: sealed by default so authors get safe contracts for free, plus a consumer UseDeep that overrides anything. Two concepts, but each is in the hands of the person who knows the intent. UseDeep is greppable and visible at the call
site, which keeps even the ambient-style power loud rather than silent. Its shape is reserved now and ships in a later point release, so the default can never paint
it out.

Takeaway

When you can see the feature roadmap and you are not under deadline, pay your structural debt down before it compounds. The brief is what tells you whether you
can afford to. And when you pick a default, choose the one whose failure mode is local and visible, not the one whose convenience hides the bug several layers up.

What's next

That is the composition thread settled. Now the threads switch. The next question is not how objects compose, it is whether the data inside them looks real at all.

Next post: fake data that is not obviously fake.

Reconciling a public API that drifted

Ernesto Herrera Salinas — Sun, 05 Jul 2026 21:11:47 +0000

The audit found that my two binding documents disagreed about the v1.1 composition API. Closing that gap was not paperwork. A public method is a promise you can almost never take back, so reconciling the surface meant making real choices and living with them.

Some quick context on what composition is. It lets a definition control how the nested objects inside a generated graph are produced: "every Address in this order graph uses this address definition," or "this specific member uses that child definition." The surface in flux covered type-scoped, member-scoped, and element-scoped binding, plus substituting a concrete type for an abstract member.

Three forks had to be settled.

Fork one: the name

The element-scoped method was UseEach in the binding doc and UseElements in the design doc. Tiny, but public, so it gets a real decision. I kept UseEach. It was the name in the top-authority document already, and it reads cleanly next to
its siblings: Use for a type, UseEach for the elements of a collection. Not every fork is deep. Some are just "pick one on purpose and stop relitigating it."

Fork two: the shape

This one mattered. The binding doc had a single-generic member binding plus a separate UseAs method for substituting a concrete type for an abstraction. The design doc had folded both into one two-generic method.

// before: two verbs
Use<TChild>(expr, def);
UseAs<TAbstraction, TImplementation>(def);
UseAs<TAbstraction, TImplementation>(expr, def);

// after: one verb, abstract-capable
Use<TMember, TConcrete>(expr, def) where TConcrete : TMember;

I took the folded shape. The generic constraint carries abstract substitution for free: for a concrete member, TMember and TConcrete infer to the same type, so existing calls are unchanged, and for an interface-typed member the second generic
supplies the concrete definition. One verb instead of three, and the type system does the work that a separate method used to. UseAs disappeared.

Fork three: how much to ship

The folded Use handles abstract members one at a time. The binding doc also promised a type-level version: "every IParty in this graph is a Person," one registration, graph-wide. I deferred it.

The reasons were concrete. The compiler cannot infer both type arguments for the type-level form, so every call would spell them out. It needs a conflict rule for two concretes registered against one abstraction. And it quietly nudges users toward expecting random polymorphic selection, which is a different feature
entirely. It is cheap to add later and expensive to walk back, so it waits. In v1.1, abstract substitution is member-scoped and element-scoped only.

I also added one new diagnostic, LIE012, for an unsupported composition target (binding to a collection shape the library cannot materialize), since the existing diagnostic registry had no fitting code.

Writing the why into the contract

The part I am most glad I did: I recorded all of this as a "Revision 2.2 amendment" inside API_DESIGN.md itself. Not in a side note, not in a commit message, in the binding document, next to the surface it changed. The amendment says what folded into what, what was deferred and why, and that the type-level form is an additive follow-up.

The contract and the design doc finally describe the same API, and the next person to read either one will find the reasoning attached to the decision instead of having to reconstruct it, or worse, rediscover the conflict I just closed.

Takeaway

A public API is a promise, and drift between your contract and your design is a quiet way to break it. Reconcile deliberately, prefer the change that is additive and lets the type system carry the load, defer the expensive-to-reverse pieces, and write the why into the contract so it does not drift again.

What's next

With the surface honest, the deeper composition decisions were waiting, the ones that were not about taste at all. They were decided by the brief: solo, no deadline, quality over speed. Next post, paying for the future on purpose.

DEV Community: Ernesto Herrera Salinas

Your Coding Agent Has Amnesia: Memory-Augmented Generation, Explained Through Codex

The Monday Problem

Why the Context Window Is Not Enough

What MAG Is

Case Study: How Codex Remembers

Layer 1: AGENTS.md, the static layer

Layer 2: Memories, the generated layer

Trying it yourself

Where It Breaks

Conclusion

References

The one seam, shown: Inline up close

The discontinuity

The options

Inline, in three scenarios

What Inline does not do

Why reach-down lost

Takeaway

What's next

Skill Opt: Training the Skill File Instead of the Model

The model is closed, but the behavior is not

SKILL.md as a parameter surface

The research already points in this direction

The Skill Opt loop

What exactly gets optimized?

1. The description

2. The body instructions

3. Examples

4. References

5. Scripts

The benchmark is the loss

The “gradient” is critique

Skills are becoming software artifacts

The security problem: optimizing text can optimize bad behavior too

What Skill Opt is, and what it is not

Why this matters

References

Decided is not done: taking stock before adding more

The fork: promote now, or hold and harden

What "hardened" actually means

Why this is allowed to be slow

Takeaway

What's next

Proving it generalizes: Person to Address

The second instance was nearly free

One honest difference: how the bundle draws

A set of entities, not one persona

Where the data comes from

Where composition and coherence meet

Takeaway

Where this leaves the first session

A believable person, and making it honest

Correlate fully, or not at all

Gender, without shipping a gender enum

Make it inspectable

Takeaway

What's next

Composing with attributes, not fighting them

Three options

The choice

Takeaway

What's next

The PRNG draw-tape: eager versus lazy

The two options, made concrete

The choice

Takeaway

What's next

Binding members to a persona without magic

Binding: automatic, with an explicit escape

Where it lives: a stage, not a patch

Detection: borrow the truth you already have

Activation: gate on evidence

Takeaway

What's next

Fake data that is not obviously fake

The idea: a persona

The load-bearing fork: what is one identity?

Takeaway

What's next

`SKILL.md` as a parameter surface