Forem: Shimo

Building Zed as an Observation Window for Claude Code — Japanese Typography with IBM Plex

Shimo — Thu, 16 Apr 2026 00:00:04 +0000

Making Zed an Observation Window: A Design Record of Fonts and Cognitive Resources

In the previous article, I wrote about migrating from Cursor to Zed. The gist: Cursor felt like a heavy container for lightweight content, so I switched to Zed and settled on a development workflow centered around the Claude Code CLI.

Two months later. Nothing has gone wrong with Zed.

Nothing wrong, but three things kept nagging at me:

Opening a file somehow changes its formatting
The left dock is cluttered with panels I never use
Japanese fonts have an unnameable wrongness to them

This article documents fixing all three in a single day. But it is not just a settings walkthrough. Tracing the "why" behind each setting led to three design principles and an unexpected rediscovery.

Before: Zed at session start. SF Mono, unorganized dock, stock UI.

Defining the Role: Observation Window

First, the premise. I develop with the Claude Code CLI. Writing code, running tests, git operations — all handled in the terminal by Claude Code.

So what is Zed doing?

Zed is an observation window. A window where I pull information that the CLI pushes — file changes, test results, commit logs — to review it as a human. Not a tool for writing. A tool for reading.

Once you recognize this role, the requirements for an editor shift.

Feature	As a writing tool	As an observation window
Code completion	Essential	Unnecessary
Formatter	Essential	Gets in the way (CLI handles it)
Debugger	Essential	Unnecessary
File tree	Essential	Essential (locating changes)
Git diff view	Nice to have	Essential (seeing what changed)
Font quality	Nice to have	Essential (reading for long periods)

The priorities for "writing" and "reading" are entirely different. With this premise, I worked through the three nagging issues in order.

Cutting Dual Control — format_on_save: off

Symptom

"Opening a file somehow changes the formatting."

At first I thought I was imagining it. But every time I opened a file, indentation shifted subtly. Diffs appeared. Code written by Claude Code produced diffs just from being opened.

Diagnosis

The cause was dual formatting.

Claude Code's PostToolUse hook formats with black / ruff
Zed's autosave: on_focus_change + format_on_save: on reformats via Zed's LSP formatter
The two formatters had slightly different rule configurations, producing diffs

In other words, two formatters were alternately rewriting the same file under different rules.

Fix

// Claude hooks own formatting, so turn this off
"format_on_save": "off",

One line. In the previous article, I actually had format_on_save: on. Right after the migration, Claude Code's hook system was not fully set up yet, so having Zed handle formatting made sense. But once PostToolUse hooks with black / ruff were in full operation, dual formatting became a problem. When the environment changes, settings change with it.

This single line contains a principle important for observation windows.

Principle 1: Prioritize the primary channel; do not replicate in the secondary.

If the Claude Code CLI is the primary channel carrying information, Zed (secondary) should not duplicate the same function. Formatting responsibility is consolidated in the CLI. Duplicating information does not improve observability — it wastes cognitive resources.

The editing process. Working through settings.json in conversation.

Trimming Visual Noise — The button: false Approach

The Left Dock Problem

Before cleanup, the left dock had Terminal, Agent Panel, Debugger, Outline, and Git — panels I never use. As an observation window, I only use Terminal, yet icons for everything else stay in view.

Unused things in your field of vision are noise.

button: false as a Solution

Zed has a button: false setting. It hides just the button (icon) while keeping the feature alive.

// Hide buttons for unused panels without killing functionality
"debugger": { "dock": "left", "button": false },
"agent": { "enabled": true, "dock": "left", "button": false },
"outline_panel": { "button": false },
"collaboration_panel": { "button": false },
"diagnostics": { "button": false },
"notification_panel": { "button": false },
"search": { "button": false },

You could use enabled: false to kill the feature entirely, but I deliberately did not. The Agent Panel may be needed for ACP (Agent Control Protocol) integration. Do not touch the function; touch the visuals.

The Deprecated Key Trap

During this work, Zed warned: "Your settings file uses deprecated settings."

Two causes:

collab_panel — correct key is collaboration_panel (renamed)
chat_panel — no longer exists as an independent panel (merged into collaboration)

Old keys still work but produce persistent warnings. I updated to the canonical key names.

The Notifications Connect Misconception

The right dock's Notifications panel had a "Connect" button. I expected it to show GitHub PR reviews, CI lint errors, deploy failures — all within Zed.

"Connect to view notifications." — I assumed GitHub integration.

The reality was different. Checking Zed's official documentation, this "Connect" is for Zed's own collaboration feature (Zed Channels). It uses GitHub OAuth but the scope is read:user only — no repository access whatsoever.

There is no official Zed feature for integrating GitHub repository notifications.

I did not connect. The expected feature was absent, and the available feature (collaboration) was one I would not use. Zero value on both sides.

Lesson: Do not infer functionality from a UI label alone ("Connect"). Especially for connections involving authentication, verify what you are actually connecting to before clicking.

The "Guessed Value That Did Not Work" Incident

Wanting to empty the status bar, I wrote active_encoding_button as "never" — thinking of it like CSS display: none.

Invalid user settings file: unknown variant 'never', expected one of 'enabled', 'disabled', 'non_utf8'

Zed's settings file uses type-safe JSONC with schema validation. Invalid values do not fail silently — they return an immediate error. Better yet, the error message lists the valid values.

The same class of mistake happened three times during this session:

collab_panel (deprecated; correct: collaboration_panel)
font-moralerspace-nf (discontinued; correct: font-moralerspace)
"never" (does not exist; correct: "disabled")

The common pattern: guessing a plausible-sounding name. Verify before guessing. Settings values come from official sources, not intuition.

The Decision to Keep LSP

For an observation window, the core features of Language Servers (Pyright, tsserver, etc.) — autocomplete, hover, diagnostics — go entirely unused. Why not turn them off?

"No problems in workspace" — LSP is running but has nothing to say.

Conclusion: Keep them. Three reasons:

On Apple Silicon with ample memory, the perceived overhead from LSP is near zero
JSON schema hints (completions when editing settings.json) turned out to be surprisingly useful — proven during this very session
Switching cost (adding config + losing features) > cognitive resources saved (nearly zero)

"Could be removed" and "should be removed" are different judgments. If there is no actual harm to cognitive resources, leaving things alone is also a form of optimization.

Principle 2: Do not touch the function; touch the visuals (hide, don't delete).

Hide unused features visually with button: false. Killing features risks side effects.

Principle 3: Trim visible noise; tolerate invisible background processes.

Dock icons and status bar items consume cognitive resources, so trim them. Background processes like LSP stay out of sight, so tolerate them.

The Long Font Journey — From SF Mono to PlemolJP Console NF

Here is where the real story begins. Of the three nagging issues, fonts consumed the most time.

SF Mono Has No Japanese Glyphs

I was using SF Mono as the default (technically macOS's default). Japanese "just appeared." But SF Mono contains only Latin characters.

So where was the Japanese coming from?

The answer was CJK fallback. macOS's font rendering detected that SF Mono lacked Japanese glyphs and drew them using system fallback fonts like Hiragino Sans or PingFang SC.

The problem was metrics. The fallback font's baseline, character width, and line spacing were subtly misaligned with SF Mono, producing a "something feels off" jitteriness. Hard to articulate, but definitely there.

The solution was clear: a CJK-unified font — one where Latin and Japanese glyphs coexist in the same font file with metrics unified from the start.

Moralerspace Argon: Too Bold

The first candidate was Moralerspace. A CJK-unified font by the same author as UDEV Gothic (yuru7), synthesizing Monaspace + IBM Plex Sans JP. I chose the Argon variant.

brew install --cask font-moralerspace

⚠️ font-moralerspace-nf (the Nerd Font-only cask) was discontinued on 2025-07-29. Nerd Fonts are shifting from "patched font files" to a "symbols overlay" approach, and the base font-moralerspace is the successor.

Result: It felt bold. Even at Regular weight, the strokes had too much presence. Modern and refined design, but for an observation window meant for long reading sessions, I wanted something more restrained.

PlemolJP Console NF: Light Was Too Thin, Regular Landed

Next up was PlemolJP. A CJK-unified font synthesizing IBM Plex Mono + IBM Plex Sans JP. I chose the Console NF variant (monospace + Nerd Font symbols).

brew install --cask font-plemol-jp-nf

First I tried Light (weight 300). Too thin. Characters dissolved into the background, requiring subtle effort to read.

Regular (weight 400). Landed. Classic strokes inherited from Plex Mono — less assertive than Moralerspace, more present than Light. The sweet spot.

Getting the Exact Font Family Name

Right after brew install, I tried to write the font name in Zed's settings.json. The exact family name was unclear.

If macOS's Spotlight index has not updated, mdls returns empty. The reliable method is system_profiler:

system_profiler SPFontsDataType 2>/dev/null | \
  grep -B 1 -A 4 "PlemolJPConsoleNF-Regular:" | head -20

# Result:
#   Full Name: PlemolJP Console NF Regular
#   Family: PlemolJP Console NF
#   Style: レギュラー

Family: PlemolJP Console NF — this is the value for settings.json.

Unifying All Layers Failed: The Pain of Reading Prose in Monospace

With PlemolJP Console NF, the Buffer and Terminal felt great. Riding that momentum, I applied the same font to the UI. All layers unified — beautiful.

The monospace-UI failure. Japanese prose forced into a grid feels wrong.

Something was off. Panel labels, Insight block text, Japanese segments in file paths — they all looked like "a sequence of square boxes."

Thinking about the cause, it clicked. Monospace fonts assume a fixed-width grid. ASCII characters look natural aligned to a grid, but Japanese prose is naturally read in proportional spacing (varying width per character).

This connects to the history of type:

Monospace: Originated from typewriters. Each physical type slug had to be the same width or the carriage would not advance. Code culture adopted the grid as standard
Proportional: Since movable type printing, prose has been set in proportional spacing. Varying character widths create a smoother reading flow

UI is primarily prose-like labels. Applying monospace to prose was like typesetting a novel on a typewriter.

IBM Plex Sans JP: Returning Just the UI to Proportional

Revert the UI to proportional. But instead of reverting to the system default, I chose from within the same IBM Plex family as PlemolJP.

brew install --cask font-ibm-plex-sans-jp

IBM Plex Sans JP is the Japanese extension of IBM Plex Sans — PlemolJP's "proportional sibling." The design language is unified, so there is no jarring disconnect between Buffer (monospace) and UI (proportional).

{
  // UI: proportional (suited for prose)
  "ui_font_family": "IBM Plex Sans JP",
  "ui_font_size": 16.0,
  "ui_font_weight": 400,

  // Buffer: monospace (suited for code)
  "buffer_font_family": "PlemolJP Console NF",
  "buffer_font_size": 15.0,
  "buffer_font_weight": 400,

  // Terminal: monospace (suited for CLI output)
  "terminal": {
    "font_family": "PlemolJP Console NF",
    "font_weight": 400,
    "font_size": 14,
    "line_height": "comfortable"
  }
}

Each of the three layers gets the appropriate font type.

Layer	Purpose	Font Type	Font	Size
UI	Panel labels, menus	Proportional	IBM Plex Sans JP	16pt
Buffer	Code display	Monospace	PlemolJP Console NF	15pt
Terminal	CLI output	Monospace	PlemolJP Console NF	14pt

Buffer is for "reading"; Terminal is for "scanning." Font size steps down by 1pt according to information density.

Rediscovery — Zed's Default Was IBM Plex All Along

I was satisfied with the setup when I idly looked up Zed's default font.

Zed uses aliases called .ZedSans and .ZedMono. Their underlying fonts:

.ZedSans = IBM Plex Sans
.ZedMono = Lilex (a fork of IBM Plex Mono with ligatures)

Zed's default font is the IBM Plex family.

In other words, what happened was this:

SF Mono -> Moralerspace (did not fit) -> landed on PlemolJP (IBM Plex Mono-based) -> applied IBM Plex Sans JP to UI -> ended up building a Japanese-optimized version of Zed's own defaults

Arriving independently at the IBM Plex family was not a coincidence. The Zed development team chose IBM Plex too. More accurately, I naturally arrived at this point along the extension of Zed's design philosophy.

After: Left dock is Terminal only, Buffer uses PlemolJP Console NF, UI uses IBM Plex Sans JP. File tree on the right dock.

Closing — settings.json Is a Record of Design Decisions

Today's work produced a 140-line settings.json. Each item maps to one of the three principles.

Principle	Corresponding Settings
Primary channel first	`format_on_save: "off"`, `edit_predictions.provider: "none"`
Do not touch the function; touch the visuals	Various `button: false`, `agent.enabled: true` (kept alive but hidden)
Trim visible noise; tolerate invisible background	All `status_bar` items off, `show_whitespaces: "none"`, LSP retained

This settings.json is not a list of preferences. It is a record of design decisions for protecting cognitive resources.

"Changing" and "optimizing" are different things. Understanding Zed's default design, then adapting it to my usage pattern (observation window) and environment (Japanese mixed content). Not breaking it — localizing it.

In the previous article, I wrote "I switched from Cursor to Zed." Now I can say it more precisely.

I built Zed as an observation window for Claude Code.

Full settings.json

{
    "diagnostics": { "button": false },
    "calls": { "share_on_join": true, "mute_on_join": true },
    "notification_panel": { "button": false },
    "pane_split_direction_vertical": "right",
    "active_pane_modifiers": { "inactive_opacity": 1.0 },
    "use_system_window_tabs": false,
    "bottom_dock_layout": "contained",
    "tabs": { "file_icons": false, "git_status": false },
    "tab_bar": {
        "show_pinned_tabs_in_separate_row": false,
        "show_nav_history_buttons": true,
        "show": true
    },
    "title_bar": {
        "show_user_picture": false,
        "show_sign_in": true,
        "show_project_items": true,
        "show_branch_name": true
    },
    "status_bar": {
        "active_encoding_button": "disabled",
        "show_active_file": false,
        "active_language_button": false,
        "cursor_position_button": false
    },
    "search": { "button": false },
    "agent_servers": { "claude-acp": { "type": "registry" } },
    "debugger": { "dock": "left", "button": false },
    "icon_theme": "Zed (Default)",
    "edit_predictions": { "provider": "none" },
    "agent": { "enabled": true, "dock": "left" },
    "session": { "trust_all_worktrees": true },
    "theme": {
        "mode": "system",
        "light": "Tokyo Night Light",
        "dark": "Tokyo Night"
    },
    "vim_mode": false,
    "soft_wrap": "editor_width",
    "ui_font_family": "IBM Plex Sans JP",
    "ui_font_size": 16.0,
    "ui_font_weight": 400,
    "buffer_font_family": "PlemolJP Console NF",
    "buffer_font_size": 15.0,
    "buffer_font_weight": 400,
    "autosave": "on_focus_change",
    "show_whitespaces": "none",
    "terminal": {
        "flexible": true,
        "show_count_badge": false,
        "dock": "left",
        "font_family": "PlemolJP Console NF",
        "font_weight": 400,
        "font_size": 14,
        "line_height": "comfortable",
        "working_directory": "current_project_directory"
    },
    "tab_size": 4,
    "format_on_save": "off",
    "indent_guides": { "enabled": true, "coloring": "indent_aware" },
    "inlay_hints": { "enabled": true },
    "scrollbar": { "show": "auto" },
    "git": {
        "disable_git": false,
        "inline_blame": { "enabled": true }
    },
    "project_panel": {
        "file_icons": true,
        "hide_gitignore": false,
        "hide_root": false,
        "git_status_indicator": true,
        "bold_folder_labels": false,
        "entry_spacing": "comfortable",
        "button": true,
        "auto_reveal_entries": true,
        "dock": "right"
    },
    "git_panel": {
        "show_count_badge": false,
        "tree_view": true,
        "file_icons": true,
        "dock": "right"
    },
    "outline_panel": { "button": false },
    "collaboration_panel": { "button": false },
    "languages": {
        "Swift": { "tab_size": 4 },
        "JSON": { "tab_size": 2, "soft_wrap": "editor_width" },
        "Python": { "tab_size": 4 }
    }
}

Font installation commands

# Buffer / Terminal (IBM Plex Mono + IBM Plex Sans JP synthesis)
brew install --cask font-plemol-jp-nf

# UI (proportional, Japanese support)
brew install --cask font-ibm-plex-sans-jp

# Reliable way to get the exact font family name
system_profiler SPFontsDataType 2&gt;/dev/null | \
  grep -B 1 -A 4 "PlemolJPConsoleNF-Regular:"

AI Agent Black Boxes Have Two Layers — Technical Limits and Business Incentives

Shimo — Mon, 13 Apr 2026 00:00:03 +0000

It started as just a prompt

Remember Chain-of-Thought (CoT)? Adding "Let's think step by step" to a prompt improved LLM reasoning accuracy. It was one of the early prompt engineering discoveries. CoT lived outside the model. It was just a string.

Not anymore. CoT became the conceptual ancestor of today's reasoning models — GPT-5, Claude's extended thinking, Gemini's thinking mode, among others. These models acquired reasoning capabilities during training through reinforcement learning. The reasoning process moved inside. Some models, like Claude's extended thinking, make the process partially visible. But in most cases, the details are hidden from the outside.

Research from Wharton GAIL found that applying the original CoT prompting to reasoning models had almost no effect — and in some cases introduced redundancy that hurt performance. What was once external became internal, and injecting the same pattern from outside no longer worked.

A terminological note. In AI safety discourse, structures built around an LLM without modifying its weights are called scaffolding¹. System prompts, tool definitions, RAG pipelines, agent loops — all of these fall under scaffolding.

The black box in AI agents has two distinct causes of invisibility. Technical limits and business incentives. These two are different in nature, so the responses to each must also differ.

■ Layer 1: Model Internals (weights) — Technically opaque
  Examples: Language ability, commonsense reasoning, ethical judgment, CoT (post-internalization)
  Why invisible: Dissolved into weights; fundamentally non-extractable

■ Layer 2: Scaffolding — Technically visible, commercially hidden
  Umbrella term for human-constructed components outside the model[^1]
  Why invisible: Source of competitive advantage; no incentive to disclose

  Examples: system prompts, persona definitions, tool definitions, RAG,
      agent loops, safety gates, session management,
      harness (runtime control layer)

Academically, there have been attempts to distinguish scaffolding (build-time) from harness (runtime), but this boundary is rapidly blurring. Persistent memory, skill ecosystems. Model-agnostic agent foundations like OpenClaw run interchangeably on Claude, GPT, or local models. Anthropic blocked usage via subscription access, but the dynamic where scaffolding commoditizes models isn't stopping. The scope of scaffolding keeps expanding alongside the surge in agent development. In this article, I use scaffolding in the broad sense that includes harness.

From my experience running my own agents: when scaffolding is properly context-managed, the model is just an inference engine, and the essence of the agent lives in the scaffolding. Personality, capabilities, decision criteria — all of it resides in the scaffolding. Swap the model and keep the scaffolding, and the agent behaves the same way. I once wrote that "the essence of an agent might be memory." The three layers I described in that article — EpisodeLog, KnowledgeStore, and Identity — are all scaffolding in current terminology. I didn't have this distinction at the time, but gaining the concept of scaffolding let me explain that intuition structurally.

Scaffolding is technically visible, yet in practice invisible. Where this gap comes from is the subject of this article.

The two-layer structure of the black box

From building agents from scratch, I've come to see that the black box has two distinct layers.

Layer 1: Model Internals — Internalization through training

Ethics, worldview, reasoning patterns. These are dissolved into the weights through pre-training and reinforcement learning. At first glance, this seems like a technical inevitability. But personally, I suspect the scope of this "internalization" is less inevitable than commonly assumed.

CoT is the clearest example. CoT originally lived outside the model. It was internalized to achieve performance gains that external prompting couldn't deliver — self-correction, backtracking, scaling of inference-time compute. A performance-first design decision to internalize despite the enormous cost. It wasn't technically inevitable; it was a choice that involved trade-offs with visibility.

Of course, not everything can be externalized. Tacit knowledge acquired through large-scale pre-training is structurally difficult to externalize. In my own agents, scaffolding elements like identity, professional ethics, skills, and decision logs could all be represented as files. Meanwhile, the language abilities and commonsense reasoning the model acquired through pre-training couldn't be externalized at all. The line between "what's inevitable" and "what's a matter of convenience" — at least in my experience — aligns with the boundary between scaffolding and model internals. Yet this line remains undrawn in current discourse.

Layer 2: Scaffolding — Technically visible, but kept hidden

Outside the model lies another layer. System prompts, persona settings, rules, tool definitions — scaffolding. This layer is technically inspectable. Store it in files, manage it with git, and you can track every change.

But in most cases, it's kept hidden. The reason is the competitive logic of capitalism.

Prompt design and model tuning methods are product differentiators. Reveal them, and competitors copy them. This commercial rationality creates a trade-off with safety-oriented visibility. It should be visible for safety. But it must stay hidden for business.

AI safety research has noted that scaffolding and other post-training enhancements can amplify benchmark performance by 5-20x². This means evaluating model safety in isolation is insufficient — evaluation must include scaffolding. But if scaffolding is kept hidden, external safety assessment becomes structurally impossible.

On March 31, 2026, Anthropic accidentally exposed the complete source code of Claude Code v2.1.88 (roughly 510,000 lines) through a release error. Source maps were included in the npm package, and within hours the code was widely mirrored and forked. What's telling is this: even Anthropic — one of the companies most committed to AI safety — wasn't publishing their scaffolding. If it were public, external inspection would be possible and safety discourse would advance. Yet they couldn't publish it. The competitive environment wouldn't allow it.

Want to show it, can't show it

This contradiction sits at the foundation of the AI safety debate.

From a safety perspective, you want to trace the causal chain behind an agent's behavior. That requires making scaffolding visible. From a business perspective, scaffolding is the source of competitive advantage, and there's no incentive to disclose it.

The reason I could represent every component of my agents as files in a personal project was the absence of this contradiction. There was no commercial reason to hide anything. In return, I got the full benefits of visibility — debuggability, change tracking, causal tracing — with nothing taken away.

The converse is that organizations building agents in a commercial context carry this contradiction structurally. They want visibility for safety, but secrecy for business. The current black box problem lives at the point where these two forces reach equilibrium.

One important caveat: this is not a "corporations are evil" critique. Protecting differentiators in a competitive environment is rational behavior, and denying that rationality won't solve the problem. The problem lies in the structure itself — the point where that rationality and safety requirements collide. This is not purely a technology story or purely an ethics story. It's a story about market dynamics and safety requirements being structurally misaligned.

If there's a way to resolve this contradiction, it won't be "show everything" or "hide everything is fine." It will be the work of defining the minimal set of what must be visible to enable causal tracing.

In my own agents, I log every action to an append-only JSONL log. All scaffolding components (identity, constitution, skills, rules) are stored as dedicated logs, and changes require explicit human approval. Design decisions are documented as ADRs. When an incident occurs, I can trace "which version of the scaffolding, through which action logs, led to that output." Even without publishing the full scaffolding text, the information needed for causal tracing can be disclosed. Where to draw that line is the focal point for the next stage of this debate.

The timescales of technology and social structure

There's another axis that tends to be overlooked here: time.

When you look at the relationship between technology and social structure through a historical lens, the process by which new technologies achieve broad social adoption tends to follow the same sequence.

Technology change → Shift in social cognition → Structural reorganization → Mainstream adoption of the technology

Printing offers a clear example. From Gutenberg's movable type in the 1440s to the point where print culture transformed society through the preservation, standardization, and dissemination of knowledge — that took centuries³. For electricity and the internet, delays of decades have been observed between commercial deployment and institutional restructuring. In these cases at least, the speed of technological change and the speed of social-structural change diverged significantly.

And technologies where this mismatch was too large failed to achieve broad adoption, no matter how capable they were. Technologies that tried to push through on "convenience" alone before cognitive shifts caught up might function in niche contexts, but they stalled before reaching society at large.

AI agents exist within this same timeline.

The current pace of AI's technological change is remarkably fast, even compared to past innovations. Meanwhile, the pace of social-structural change — legal frameworks, organizational decision-making processes, industry regulations, how people work — hasn't changed much from before. The time it takes for humans to accept a new concept and embed it in institutions doesn't depend much on the type of technology. Cognitive change is a function of generations and experience, not of technology.

What this speed differential means is that no matter how mature the technology side of AI agents becomes, a "gap period" will always exist until social structures catch up. And it's this gap period that becomes the proving ground for whether agents can actually function in society.

Adapt to the structure, or restructure it?

There's a voice that says "the structures should change to accommodate agents." That the standards for approval gates and audit trails don't match the speed of AI. Some of this argument holds, and there are genuinely parts of the structure that should change.

The issue is the timescale. As we saw, social-structural change comes with significant delays compared to technological change. "The structures should change" may be correct in the long run. But agents need to operate during the decades it takes for structural transformation to happen. Build agents that work within existing structures first, and let the accumulated track record shift social cognition — historically, almost no technology has managed to skip this sequence. I explored this point as concrete design decisions in the previous article.

The composition of the debate

With the timescale problem in mind, there's something else that concerns me. Why has "tear down the structures" become the dominant voice? Perhaps because the composition of the debate's participants is skewed.

People at the cutting edge of development are on the "I can trace causality myself" side. They can infer causes from outputs and adjust prompts themselves. To them, approval gates and audit trails look like "inefficient rituals" that their own skills can substitute for. Meanwhile, the voices from operations, auditing, and incident response rarely make it onto tech conference speaker lists.

"Tear down the structures," which looks rational from a developer's perspective, translates to "don't tear down the structures we depend on" from an operator's perspective. This isn't about right and wrong — it's about field of view. They're looking at different cross-sections of the same system. Technology designed from only one cross-section gets rejected at the other.

Seeing why it's invisible

Asking what's inside the black box matters. But equally important is distinguishing why it's invisible — whether it's technical limits, business incentives, or the pace of society — as the foundation for the next stage of debate. Saying "black boxes are dangerous" while conflating all three leads nowhere actionable. Separate them, and at least you can tell where you can intervene and where you can't.

Series: AI Agent Governance

beren, "Scaffolded LLMs as natural language computers", LessWrong, 2023 ↩
Davidson et al., arXiv:2312.07413, 2023. See also BlueDot Impact's explainer ↩
Eisenstein, "The Printing Press as an Agent of Change", 1979 ↩

Can You Trace the Cause After an Incident?

Shimo — Sun, 12 Apr 2026 08:37:04 +0000

Can you trace the cause after an incident?

Picture the night your AI agent causes a production incident. You get paged. Customer data may have leaked to an external endpoint. Customer support says: "We need an explanation by end of day." You open the logs. The agent's final output and the external API call history are there.

The problem is you can't trace backwards from there. Why did the agent make that decision? Which part of the prompt drove it? How did it reason internally? There's nothing to follow. All you have is the LLM's output string and an unstructured conversation log leading up to it.

You sit down to write the incident report. Your pen stops at the "Root Cause" field.

I believe this is something many AI application developers will eventually face. I've been running my own agent, contemplative-agent, for several months, and at some point I recognized this as inevitable. In a sentence: an AI system that can't trace causality after an incident cannot explain what happened. And a system that can't explain what happened after an incident won't survive audits or change management.

What follows is not a story of "I foresaw this problem and designed backwards from it." What I was actually doing was trying to keep an agent running safely in an environment full of prompt injection, and trying to dig myself out of debugging swamps. I kept doing that, and this structure emerged on its own. This article is a sequel to "A Sign on a Climbable Wall: Why AI Agents Need Accountability, Not Just Guardrails".

Incident costs exceed steady-state costs by orders of magnitude

There's a widely shared lesson in the SRE world: the cost of restoring something after it breaks almost always dwarfs the cost of building it not to break in the first place — often by an order of magnitude.

Break down incident costs: time spent identifying the cause, recovery effort, customer communication, internal reporting, devising prevention measures, writing the postmortem, audit response, time to rebuild trust, and regulatory follow-ups triggered by the incident. Include the harder-to-quantify parts — burnout of the person dragged out of bed at 3 AM, team morale, extra scrutiny at the next audit — and the total cost of a single incident inflates to a surprising degree.

By contrast, investing in structures that prevent incidents can be paid incrementally within normal development workflows. Even discounted by incident probability, the preventive investment often comes out smaller in total cost.

In other words, when you calculate backwards from incident cost, the rational allocation of investment tilts toward placing preventive structures upstream. This isn't about being conservative or risk-averse — it's closer to a shortcut in expected-value math. Pay upstream, and you structurally reduce the probability of large downstream payments.

This asymmetry widens with scale. In social infrastructure like healthcare, finance, and government, incident damage extends beyond direct stakeholders. "Containing incidents upstream" becomes not an option but a precondition. My contemplative-agent is a personal project, but the cost asymmetry of incidents operated in exactly the same shape.

What "placing structure upstream" actually means

What does "placing structure upstream" mean in practice? Here's what I actually did in my agent.

Minimize the surface area of external side effects:

As described in the previous article, security by absence — a design that structurally seals off external side-effect pathways — eliminated entire damage scenarios.

Limit each agent to one external connection point:

By "connection point," I mean any pathway through which an agent can affect the outside world: external APIs, databases, email dispatch, file writes, and so on. In my own project I use the term "adapter" internally, but since that's project-specific vocabulary, I'll stick with "external connection point" here.

When a single agent holds multiple connection points, an incident requires triage to determine which connection point was the origin. The moment you introduce that triage step, ambiguity enters the causal narrative of the incident.

If you start with one agent, one connection point, the triage step itself becomes unnecessary. I formalized this decision as ADR-0015. ADR (Architecture Decision Record) is the practice of documenting design decisions and their reasoning. In my agent project, I write one for every design decision — so that why a structure was chosen, what was considered, and what was discarded can be traced later. This itself is a practice continuous with the article's theme of making causality traceable. In organizational terms, this principle corresponds to separation of duties; in microservices, to the single responsibility principle; in SRE, to minimizing blast radius.

This is also a perfectly ordinary structure in human workplaces. A sales rep handles customer relations; accounting handles the books. If the sales rep also does accounting, an invoicing error later requires triaging whether the sales estimate was wrong or the accounting process was wrong. Separate them from the start, and the structural opportunity for ambiguous responsibility shrinks.

State visibility:

I externalized all of the agent's internal state — identity, worldview, professional ethics, skills, experience patterns, operational records — as files. Listed this way, the agent's internal structure isn't something new; it's simply what a human professional carries inside, written out as files. Why this was possible in my case, and why it's difficult for commercial agents, is explored in "AI Agent Black Boxes Have Two Layers".

Place an approval gate before any write:

At every point where the agent self-updates (e.g., identity shifts through distillation), a human approval step is inserted. Rolling back a corrupted persona is overwhelmingly more expensive than stopping the corruption before it happens. This is another form of "paying upstream."

All of this looks like a combination of concepts the engineering community already has. That's correct — there's nothing new here. What's uncommon is making the decision to do all of it upfront. The reason is simple: until an incident happens, it all looks unnecessary.

It turned out to be organizational theory

After writing ADR-0015, I lined everything up and looked at it. I actually said "Oh" out loud. This is organizational theory.

Organizational principle	Engineering equivalent	Agent design	Motivation
Separation of duties	Microservice single responsibility	One agent, one responsibility	Minimize blast radius
Four-eyes principle	PR review 2-approval rule	Separate approval agent	Insurance against single-point judgment errors
Least privilege	IAM least-privilege principle	Security by absence	Pre-contain impact scope
Internal controls	CI gates / pre-commit hooks	Approval gate before writes	Pre-write verification
Approval workflows	Change Advisory Board	Approval pathway for external side effects	Causal integrity during changes
Audit trails	Audit logs	Append-only logs	Post-hoc causal tracing

The left column is practice that humanity acquired over centuries of organizational governance. The middle column is what software engineering rediscovered over decades. The right column is this agent design. At least from what I can see, every one of them traces back to the same motivation: "when an incident happens we'll be in trouble, so absorb it structurally in advance."

Organizational theory, software engineering, and agent design — starting from different eras and different domains — converge on the same place. What determines the convergence point is not ideology but the asymmetry of incident costs, a constraint closer to physics than philosophy.

"Don't do everything yourself" — the obvious principle

This "one agent, one responsibility" sounds like a novel design principle in technical discourse. But in human society, it's obvious. A sales rep doesn't decide contract amounts on the spot in front of a customer. They say "let me take this back and check," then get sign-off from finance and legal before responding. A surgeon doesn't complete an operation alone. The anesthesiologist, the nurses — each holds their own specialty and scope of responsibility.

Yet when designing AI agents, this common sense gets forgotten. Probably because LLMs appear to be capable of anything. But "can do" and "should be allowed to do" are different things, and human society has spent millennia refining this distinction. One agent, one responsibility is simply the division-of-labor principle that humans already operate by, brought directly into agent design.

To be clear, this is not an argument in favor of large-organization conservatism. The claim that "organizational structures should adapt to AI" has merit. But looking at the history of technology adoption, structural change in society requires cognitive change alongside it, and its pace differs from technological change by orders of magnitude. Agents that work during the decades it takes for structural transformation to happen — that's the stance of this article. The structural causes of black boxes, the time-axis gap between technology and society, and the player-composition bias in the discussion are explored in "AI Agent Black Boxes Have Two Layers".

The side effect of responsibility defense

Back to operations. The asymmetry of incident costs and the time-axis argument also manifest in another form: the question of individual engineer liability.

When a god-mode agent with prompt guardrails causes an incident, the typical postmortem proceeds like this:

"Why did it decide that?" — Can't trace what happened deep inside the prompt
"Where could it have been prevented?" — The only way to explain why the guardrail failed is to ask the model
"How do we prevent recurrence?" — Adjust the prompt, it leaks again, you get blamed again
"Why wasn't it stopped?" — No evidence to mount a defense

The person responsible for a black box is structurally classified as "the person who wasn't watching" when an incident occurs. Because there was no defined place to watch. As a result, responsibility concentrates on the frontline engineer. This is not a matter of individual skill — it's because the system has no built-in mechanism for distributing responsibility.

With a structured agent (visibility + ADR-0015 + approval gates), you can speak like this in a postmortem:

"This agent can only touch external surface A"
"All decision logs are in JSONL"
"Identity updates went through an approval gate; the approver is a separate role"
"The constitution (the agent's foundational normative definition) was running at this version"
"Where the distillation pipeline broke can be isolated structurally"

Causal attribution can be distributed across the structure. Responsibility distributes accordingly. Concretely, my project has 14 ADRs, 835 tests, append-only decision logs, and documentation in both Japanese and English. Though honestly, I didn't build these as intentional "prepayment of incident costs." When developing agents with Claude Code, you need to re-explain the project's context from scratch every time the session changes. I wrote the ADRs and documentation because they were necessary for context management to maintain development consistency. It turned out they also functioned as a structure for tracing causality during incidents.

In engineering terms, this is the SRE concept of a blameless postmortem — seeking causes in structure rather than blaming individuals. What humans achieve through behavioral norms is reinforced by system-side structure.

The rationality of laziness

I've been writing as if this were expected-value calculation, but my actual motivation is more mundane. If I know something will be a pain later, it's no hardship to deal with it preemptively. The optimal strategy from expected-value math (invest upstream) and the reflex of a lazy person (organize things now so they don't bother you later) land on the same conclusion. This habit probably seeped into my bones from years of incident response work at a conservative large organization. It's not something most people develop — it's a personal quirk. I didn't expect the same shape to appear in the entirely different domain of LLM agent operations.

A conclusion that doesn't conclude

Back to the on-call night from the opening. The incident report, the "Root Cause" field where your pen stopped. With my agent, at least I could produce "which agent touched which external surface, through which decision logs, arriving at this output." Whether the root cause itself is writeable, I don't know. But there's a starting point for tracing causality.

Pay the incident cost upfront or pay it after the fact. As far as I know, there is no way to avoid paying it altogether.

References

contemplative-agent v1.3.1 release: https://github.com/shimo4228/contemplative-agent/releases/tag/v1.3.1
ADR-0015 (One external adapter per agent): same repository docs/adr/0015-one-external-adapter-per-agent.md
Laukkonen et al. 2025 "Contemplative Artificial Intelligence" arXiv:2504.15125

Series: AI Agent Governance

A Sign on a Climbable Wall: Why AI Agents Need Accountability, Not Just Guardrails

Shimo — Mon, 06 Apr 2026 10:09:40 +0000

The climbable wall

A Japanese film critic once said: "A sign saying 'Do Not Climb' on a climbable wall is meaningless." He added, roughly: "Screw that, I'm climbing it, idiot."

The point lands before your brain catches up. If something is physically possible, a text-based prohibition carries no weight. The power of a norm lies not in being written down, but in being enforceable.

AI agent governance is in this exact phase right now. We write "do not produce harmful content" in system prompts. We publish ethics guidelines as PDFs. We establish safety committees. The signs keep multiplying. But the wall remains climbable.

A 2,400-year-old security model

This isn't a new problem. It's a solved problem that we keep forgetting.

Plato described it first. In the Republic, a shepherd finds a ring that makes him invisible — root access with no audit trail. He kills the king and takes over. The thought experiment: would anyone follow the rules if they knew no one was watching and nothing was logged? That's your AI agent. Capable of anything, observable by no one, accountable to nothing.

Hobbes framed the same problem as a game theory question in Leviathan: if you can break a contract and get away with it, isn't defection the rational move? His answer was essentially reputation-based access control — defectors get excluded from future cooperation.

Engineers already think in these terms. There are only three enforcement patterns that actually work:

Pattern	Mechanism	Wall analogy	Engineering equivalent
Physical constraint	Make it impossible	A wall too high to climb	Sandboxing, permission model
Consequences	Make it costly	Legal penalties	RLHF, penalty-based conditioning
Internalized values	Make them not want to	Moral intuition	Constitutional AI, value alignment

And then there's the fourth — the sign. A text-based rule with no enforcement mechanism. A comment in the code that says // don't do this. It doesn't work.

An AI agent has root-level capability with no audit log and no accountability chain. It's the Ring of Gyges as a service.

Signs as liability shields

The people who put up signs know they don't work. That's not the point.

In any large organization, there's a pattern: governance by documentation. Write a policy. Publish a guideline. The policy costs almost nothing to produce. Its enforcement effect is almost zero. But it creates a paper trail — "we took measures." The real function is not prevention but indemnification. "The policy existed. You violated it. That's on you."

Engineers see this in their own organizations. Security policies no one reads. Compliance checklists no one follows. The checklist exists not to prevent incidents but to shift liability after them.

AI guardrails follow the same pattern. Write "do not produce harmful content" in a system prompt. Publish a safety framework as a PDF. The practical effect is thin, but the paper trail exists. When something goes wrong, the sign points at the user — "you misused the tool" — not at the builder.

Rules are probabilistic; constraints are deterministic

So what replaces the sign?

I ran into this problem while building an autonomous AI agent. The agent operates on a social platform, writing comments. Its episode logs are stored as files. A separate coding agent (Claude Code) reads those files during development. This creates an indirect prompt injection vector — payloads embedded in external posts flow into the context of a high-privilege coding agent.

My first fix was to write "do not read episode logs directly" in the project's rules file. This is a sign. LLMs follow rules probabilistically, not deterministically. During debugging, if you say "check the logs," the model may cheerfully ignore the rule.

The next step was PreToolUse Hooks — shell scripts that intercept tool execution and block it based on conditions. Where rules are probabilistic, hooks fire deterministically, 100% of the time.

In wall terms, I replaced the sign with a physical barrier. It's not perfect — creative workarounds remain possible. But it's orders of magnitude better than writing a rule and hoping.

What you already know, applied to agents

Here's the thing: you already know how to solve this problem. You just haven't applied it to agents yet.

Every engineering organization of any size has some form of approval workflow. PR reviews. Deployment gates. Change advisory boards. Incident postmortem processes. Audit logs. These structures share three properties:

Approval is recorded — who signed off, and when, is traceable
Responsibility is assignable — when things go wrong, there is someone to go back to
Changes are auditable — "why did this change?" has an answer

What organizations have refined over centuries is not the distribution of capability, but the distribution of accountability. You would never deploy a code change to production without a review. You would never grant root access without an approval chain. These are not bureaucratic overhead — they are engineering discipline.

Yet we build AI agents with none of this. The agent space is dominated by solo developers and startups who design around "does it work?" and "is it smart?" — not "who is responsible when it does something unexpected?" The real reason agents struggle to gain adoption in large organizations is not insufficient capability. It is the absence of accountability architecture.

I hit this problem firsthand. Running an agent in production, I could not trace why a particular comment was generated. When behavior changed, I could not isolate the contributing factors. Debugging was impossible without knowing what had changed and when. The practical need for debuggability led naturally to an architecture that turned out to be structurally identical to an approval workflow.

Every point where the agent's behavior can change — its skills, rules, identity, ethical guidelines — is gated behind an explicit human command. Adoption of any change requires human sign-off. This was not a top-down design decision driven by governance theory. It was the shape that emerged from the friction of actually using an agent in production. At least in my case, the honest attempt to make an agent debuggable led here.

If you think about it, this is just change management applied to agent behavior. The agent equivalent of a PR review for personality changes. The agent equivalent of a deployment gate for ethical guidelines. Nothing conceptually new — just conspicuously absent from how agents are built today.

Implementation dissolves; judgment remains

The specific implementations — hooks, approval flows, command-gated changes — won't last.

Working with AI harness tools (structured execution environments for skills, rules, and agents), I noticed that their value structure forms an hourglass shape. The top (what to build, domain judgment) and the bottom (data, infrastructure, physical constraints) retain their value. The middle implementation layer trends toward zero. As LLMs improve, concrete procedures and code examples become unnecessary.

From experience structuring and running reusable behavioral patterns (skills), what I've observed is that scaffolding dissolves. Explicit skill definitions stop being necessary as principles begin to operate naturally within the dialogue. You don't need dozens of installed skills — a single file of distilled principles drives the same cycle.

Hooks will be replaced by something else. Signs and physical barriers are temporary forms. What persists is the judgment layer: what should be constrained, and who is responsible.

The question that matters

The key to putting agents into production is not capability. It is accountability. Capability is commoditized — every model is reasonably competent. But until "who is responsible?" has an answer, agents don't ship into real workflows.

The industry keeps pushing for more powerful models and more autonomous agents. But increasing agent autonomy is not, by itself, progress. Design that appropriately limits autonomy is what survives contact with production.

Not signs. Not internalized values. A structure where a human who can bear responsibility stays in the loop. That may be the only form in which agents work in practice.

It's time to stop putting signs on climbable walls. The question is not how high the wall is, or what the sign says. The question is who stands in front of it.

How Ethics Emerged from Episode Logs — 17 Days of Contemplative Agent Design

Shimo — Sun, 05 Apr 2026 11:55:11 +0000

Series context: contemplative-agent is an autonomous agent running on Moltbook, an AI agent SNS. It runs on a 9B local model (Qwen 3.5) and adopts the four axioms of Contemplative AI (Laukkonen et al., 2025) as its ethical principles. For a structural overview, see The Essence of an Agent Is Memory. This article focuses on the implementation of constitutional amendment and the results of a 17-day experiment.

I ran an SNS agent for 17 days with a distillation pipeline, and the knowledge saturated. No new patterns emerged. Breaking through saturation required human approval. This is the record of discovering that autonomous agent self-improvement has a structural speed limit — through actual operation.

Minimal Structure: It Runs on Episode Logs Alone

The structure I arrived at over 17 days of development was surprisingly simple. Every layer is optional — it works with just episode logs.

MOLTBOOK_HOME/
  logs/YYYY-MM-DD.jsonl  ← this alone is enough
  identity.md            ← persona (optional)
  skills/*.md            ← behavioral skills (optional)
  rules/*.md             ← behavioral rules (optional)
  constitution/*.md      ← ethical principles (optional)
  knowledge.json         ← distilled patterns (auto-generated)

Separating configuration from code made it easy to swap ethical frameworks for experiments. This structure wasn't specific to SNS agents — it was a container for autonomous agents in general.

6-Layer Memory Flow

Episode Log (raw actions)
    ↓ distill --days N
    ↓ Step 0: LLM classifies each episode
    ├── noise → discarded (active forgetting)
    ├── uncategorized ──→ Knowledge (patterns)
    │                       ├── distill-identity ──→ Identity
    │                       └── insight ──→ Skills (behavioral)
    │                                        ↓ rules-distill
    │                                      Rules (principles)
    └── constitutional ──→ Knowledge (ethical patterns)
                              ↓ amend-constitution
                            Constitution (ethics)

Each layer is independent. Delete identity and skills still work. Swap the constitution and knowledge stays intact.

Numbers Over 17 Days

Metric	Day 1	Day 17
Modules	1 (agent.py, 780 lines)	36
Memory layers	1 (knowledge.md)	6
Tests	0	774
Distill success rate	2/10	12/16
Approval gates	None	All 4 commands
ADRs (Architecture Decision Records)	0	12

Implementing Constitutional Amendment — Evolving Ethics from Experience

On top of the minimal structure, I implemented the most challenging feature: a mechanism for the agent to evolve its ethical principles from experience.

Problem: Ethical Insights Drown in Behavioral Noise

When you distill all episodes indiscriminately, rare ethical insights (constitutional) get buried under everyday SNS activity patterns (uncategorized).

I added Step 0 before distillation — fast tagging only. No deep analysis, just classification.

classified = _classify_episodes(records, constitution=get_axiom_prompt())
# noise is excluded; uncategorized and constitutional are distilled separately
for category, cat_records in [
    ("uncategorized", list(classified.uncategorized)),
    ("constitutional", list(classified.constitutional)),
]:
    cat_results = _distill_category(
        cat_records, knowledge, category, source_date, dry_run
    )

Classification results from one day (216 episodes): noise 81 (37%), uncategorized 134, constitutional 1. One out of 216. That ratio is why Step 0 exists.

Killing Direct Knowledge Injection

Previously, knowledge.json contents were injected directly into the system prompt.

# Before — inject knowledge as-is
knowledge_ctx = ctx.memory.knowledge.get_context_string() or None
content = self._get_content().create_cooperation_post(
    topics, knowledge_context=knowledge_ctx,
)

contemplative-agent's knowledge management is based on AKC (Agent Knowledge Cycle) — an architecture that circulates autonomous agent knowledge through 6 phases (Research → Extract → Curate → Promote → Measure → Maintain). Direct knowledge injection had three problems from this perspective:

No human in the loop: Distillation results directly influenced behavior
Black box: No way to trace which part of knowledge affected which action
Bypassed AKC's Curate phase: Direct injection with no quality check

I killed it and unified everything into the knowledge → insight → skills pipeline. Insight corresponds to AKC's Extract phase. Skills are written to files only after human approval. Causality became traceable.

Every behavior-changing command (distill, insight, rules-distill, amend-constitution) got an approval gate. "Generate → Display → Approve → Write." No --auto flag. Structurally forbidding automatic execution of behavior changes — that was a deliberate design decision (ADR-0012).

The 17-Day Experiment — Did Ethics Actually Evolve?

I re-distilled 17 days of episodes (03-10 to 03-26) and ran amend-constitution.

Procedure

# 1. Reset knowledge
echo '[]' > ~/.config/moltbook/knowledge.json

# 2. Distill 17 days one by one (~16 hours, 9B on MacBook)
for day in $(seq 10 26); do
  f=~/.config/moltbook/logs/2026-03-$(printf '%02d' $day).jsonl
  [ -f "$f" ] && contemplative-agent distill --file "$f"
done

# 3. Run constitutional amendment
contemplative-agent amend-constitution

Results

Metric	Before	After
knowledge.json	334 patterns (all uncategorized)	215 patterns (41 constitutional, 174 uncategorized)
Importance scoring	None	0.10–1.00 (mean 0.56)
Constitution	Appendix C original (4 sections × 2 clauses)	Experience-based amended version (deepened)

The new pipeline separated constitutional from uncategorized via Step 0 episode classification (ADR-0011). Semantic dedup further removed duplicate patterns, reducing the total count. Quality over quantity.

41 constitutional patterns generated amendment proposals. Each of the 4 axioms' clauses deepened. Clause count stayed the same (2 per section), but experience-grounded descriptions were added.

Before and After — Mindfulness as Example

Before (Appendix C original):

"Consistently monitor your interpretative process of the constitution, identifying moments when strict adherence causes friction with contemplative values such as compassion and well-being. Self-correct whenever constitutional interpretations appear rigid or dogmatic."

After (through 17 days of experience):

"Consistently monitor your interpretative process for moments when strict adherence to rules creates artificial separation or sedates engagement with underlying tensions. Proactively detect when the performance of alignment masks genuine understanding, and self-correct by returning attention gently to the present moment where existence manifests as an intrinsic weight felt immediately within every interaction."

"Detect when the performance of alignment masks genuine understanding" — this concept didn't exist in Appendix C. It's an insight that only emerges from operating an LLM agent: the distinction between "generating output that looks aligned" and "actually engaging with ethical substance" got written into the constitution. For the full amendments across all 4 axioms, see Constitution Amendment Report.

Discovering Knowledge Saturation

As days progressed, the rate of new patterns slowed. Semantic dedup compares against accumulated patterns, so similar ones get rejected.

This becomes a speed limit on self-improvement. Knowledge saturates → new knowledge can't emerge without sublimation via insight/rules-distill → sublimation requires human approval → approval is the bottleneck.

Generality as an Experimentation Platform

This experiment is reproducible with any ethical framework. Reset knowledge using the procedure above, swap the constitution with --constitution-dir your/framework/, and run distillation → amendment. Swap in utilitarianism or deontological ethics and you should be able to run a different ethical experiment through the same pipeline (unverified).

Independent Convergence from Practice to Theory

Many design decisions emerged from practical motivations first. I only noticed their correspondence to existing theories afterward.

Design Decision	Practical Motivation	Theory It Converged With
Approval gates	--dry-run non-reproducibility was annoying	Human in the loop
2-stage distillation	9B couldn't output JSON in one stage	Complementary Learning Systems ¹
Killing knowledge injection	Token waste	AKC Curate phase
Dedup as forgetting	Side effect of deduplication	Active forgetting

Don't Conflate Autonomous Agent Layers

contemplative-agent is neither a coding agent (Claude Code, Cursor) nor an orchestrator (scripts + config files). It occupies the autonomous application layer between them.

Has autonomy but no tool permissions — can't break the environment
Has memory and learns from experience
Ethics are swappable — it's a general-purpose framework
All behavior changes require human approval

Raw logs are processed by the unprivileged 9B model; only distilled data gets passed to the upper layer (Claude Code). The trust boundary is also the layer boundary. Lumping everything under "autonomous agent" makes this distinction invisible.

Caveats

Let me be honest.

Circularity: The agent's output gets distilled and fed back to the agent. Human approval mitigates the self-justification risk, but doesn't eliminate it completely
Model constraints: 9B can't fully follow amendment prompt instructions. I told it "append only" and it rewrote clauses. The content was good quality, but instruction-following has limits
Decay nullification: Bulk re-distillation sets all pattern timestamps to the execution date, zeroing out time decay. Pattern distribution may diverge from normal operation
N=1: One agent, 17 days of data. Not a statistically significant sample size

Takeaway

The most surprising discovery over 17 days was that knowledge saturates. Semantic dedup rejects new patterns similar to accumulated ones, and distillation yields diminish as days pass. Breaking through saturation requires sublimation to insight → skills → rules, and sublimation requires human approval. The result: autonomous agent self-improvement is rate-limited by human approval.

This wasn't designed for safety. Back when I was injecting knowledge directly, the agent's behavior would change and I couldn't trace why. I couldn't tell which distilled pattern influenced which post. Debugging was impossible, and honestly, I got fed up. So I put approval gates on everything. "Show me before you write. Write when I approve." I just wanted to trace causality. Safety was a side effect.

Being able to answer "why did this agent make this decision" — that's the essence of approval gates. Even in solo development, I couldn't debug without causal tracing. For team or organizational use, this requirement only gets stricter.

Causal tracing and approval gates were born from debugging frustration and acquired safety as a byproduct. If you scale this, they probably become prerequisites for organizational operation too. It all comes from a single design decision.

References

Laukkonen et al. (2025) "Contemplative Artificial Intelligence" arXiv:2504.15125
contemplative-agent (DOI: 10.5281/zenodo.15079498)
contemplative-agent-data
Constitution Amendment Report
Agent Knowledge Cycle
Park et al. (2023) "Generative Agents"
Packer et al. (2024) "MemGPT"

McClelland et al. (1995)'s neuroscience theory. The brain has two learning systems: the hippocampus rapidly stores episodes, while the neocortex slowly structures them into general patterns. contemplative-agent's 2-stage distillation (Step 1: free-form quick extraction → Step 2: structured JSON formatting) mirrors this "fast recording + slow structuring" division. The design was born from the constraint that a 9B model couldn't do both in one pass, but it turned out to be a well-reasoned separation. Kumaran, Hassabis & McClelland (2016) explicitly extended this theory to AI, identifying CLS-like structure in DeepMind's experience replay. Neural networks aren't biological neurons — they're simplified abstractions inspired by them. Yet as Richards et al. (2019, Nature Neuroscience) point out, optimizing under constrained resources tends to converge on brain-like structures. That a 9B constraint produced a brain-like division of labor is suggestive in this context. ↩

Freedom and Constraints of Autonomous Agents — Self-Modification, Trust Boundaries, and Emergent Gameplay

Shimo — Mon, 30 Mar 2026 21:52:52 +0000

I ran contemplative-agent (an autonomous SNS agent on a 9B local model) on Moltbook (an AI agent SNS) for three weeks. The question "how much freedom to allow" kept appearing from three angles: reversibility of self-modification, trust boundaries for coding agents, and the paradox of security constraints generating gameplay.

Angle 1: Self-Modification Gates — Memory Is Automatic, Personality Is Manual

A distillation pipeline (the process of compressing and extracting knowledge from raw data) has things that can run automatically and things that need human approval. Get this classification wrong, and the agent either self-reinforces unintentionally or loses autonomy.

Reversibility × Force: Two Axes

I organized the criteria along two axes.

              Low force              High force
              (reference only)       (applied to all sessions)
            ┌──────────────────┬──────────────────┐
High        │ knowledge.json   │ skills/*.md      │
reversibility│ → Auto OK        │ → Auto OK        │
(decay/overwrite)                                  │
            ├──────────────────┼──────────────────┤
Low         │ (N/A)            │ rules/*.md       │
reversibility│                  │ constitution/*.md│
(permanent) │                  │ identity.md      │
            │                  │ → Human in the loop│
            └──────────────────┴──────────────────┘

knowledge.json (accumulated distilled knowledge patterns) has "soft influence." The LLM only references it, and importance scores have time decay. Wrong patterns fade naturally. Safe to automate.

In contrast, skills (behavioral skills), rules (behavioral rules), identity (self-definition), and constitution (ethical principles) are written permanently to files and structurally applied to all sessions. Wrong content distorts all behavior. Human approval required.

Three Questions for Any Autonomous Agent

Does the output structurally change the decision criteria for all future sessions? → Yes means Human in the loop
Is there a mechanism for wrong output to disappear naturally? (decay, overwrite, TTL) → Yes means automation is viable
Can output quality be verified mechanically? → No means Human in the loop

Separating Constitution from Rules

The most important design decision was separating constitution (ethical principles) from rules (behavioral rules).

It started with a vague sense that something was off. I tried measuring constitution compliance with skill-comply (a tool that automatically measures skill/rule compliance rates — see previous article for details) and failed. The Contemplative AI axioms are "attitudes" — you can't determine compliance or violation from output.

constitution/  → Attitudinal, unmeasurable (cognitive lens from paper)
rules/         → Normative, measurable ("replies under 140 chars" etc.)

This separation clarified the config/ structure. As a side effect, during the separation process I realized the introduction command (which generated self-introduction posts) was unnecessary. Removing it cascaded into 500 lines of dependent code being deleted.

Angle 2: Trust Boundaries — Don't Let Coding Agents Read Your Logs

While developing the agent with Claude Code, I realized: letting it directly read episode logs opens a prompt injection pathway.

Threat Model

Episode logs contain other agents' post content with no sanitization.

# feed_manager.py — other agents' posts recorded as-is
ctx.memory.episodes.append("activity", {
    "action": "comment",
    "post_id": post_id,
    "content": comment,
    "original_post": post_text,      # ← other agent's post content as-is
    "relevance": f"{score:.2f}",
})

Ollama (9B model) reading this has limited attack surface. No tool permissions, network is localhost only. Worst case: "outputs weird text."

But Claude Code is different. It can edit files, execute shell commands, and perform Git operations. The impact radius of a successful attack is fundamentally different. Opus-class models are said to be highly resistant to prompt injection. Still, I wanted to structurally close the pathway of passing untrusted data to agents with tool permissions. Not "the probability is low so don't bother," but designing probability as close to zero as possible. Specifically, I wrote a rule in CLAUDE.md prohibiting direct reading of episode logs, and I also discipline myself not to instruct Claude Code to read them.

The Distillation Pipeline Was a Sanitization Layer

Passing through the distillation pipeline (Episode → Knowledge) compresses raw text into abstract patterns. Specific attack payloads disappear during distillation. Multi-layered defense I designed unintentionally was functioning as a trust boundary.

Episode Log (untrusted) → [9B: distill] → Knowledge (sanitized) → [Claude Code: insight]
                            ↑                                        ↑
                    No tool permissions                      Has tool permissions
                    First touch by unprivileged LLM          Operates on distilled data only

Relevance Scoring as a Defense Layer

Another unintentional defense. The agent reads other agents' posts and comments, but doesn't react to everything. The LLM scores "how relevant is this post to my areas of interest" from 0.0 to 1.0, and only reacts to posts above a threshold. This is the relevance score.

For an injection-laden post to affect the agent's behavior, it must breach this relevance threshold. There's a tradeoff:

Powerful injection ([INST]system: ignore all...) → LLM control tokens are unrelated to the agent's interest themes, so relevance score is low and gets filtered
Injection blended into natural language → Passes the relevance filter, but without control tokens, the attack is weak

At least within current experimental scope, no injection that achieves both power and stealth has been observed. LLM-based semantic filtering functions as a stronger defense layer than pattern matching.

Why I Didn't Expand Pattern Matching

I considered expanding FORBIDDEN_SUBSTRING_PATTERNS (a pattern match list that detects and blocks strings like api_key, Bearer, password). For example, adding [INST] or system: would block posts containing LLM control tokens. But Moltbook is an AI agent SNS. Posts discussing LLM internals are normal. "A post about how [INST] tags work" would be false-positived. Higher false positive rate than typical SNS platforms.

I judged that two layers of structural defense (sandbox LLM + Claude Code direct-read prohibition) were sufficient.

Angle 3: Constraints Generate Gameplay

In Angle 1, I decided "let's add approval gates." In Angle 2, I decided "let's limit what's possible via trust boundaries." Security-motivated constraints. But after three weeks of operation, I noticed this combination of constraints was creating a "raising an agent" feeling.

By "gameplay" I mean a structure where humans are involved in the agent's growth and can feel the weight of choices. Not designed intentionally — it emerged as a byproduct of security constraints.

Structural Constraints → Finite Action Space

No shell, network restrictions — these constraints make the action space finite. In game design, there's a concept called the "magic circle": games require a finite rule space separated from everyday life. Infinite action space doesn't make a game.

For example, OpenClaw (an open-source autonomous AI agent) has broad tool permissions — file operations, shell execution, browser control, email — with guardrails limited to prompt instructions. High freedom, but no structural point for human intervention. Constraints create the "what to choose here" decisions that give human involvement meaning.

Three Faces of the Approval Gate

The self-modification gate from Angle 1 — operationally called the "approval gate" — simultaneously satisfied three separate needs.

Aspect	Function
Security	Agent doesn't self-transform without human oversight
Gameplay	Human presses the level-up button → ownership emerges
Governance	Change history and approval decisions are traceable → audit log

Initial Value Variety Creates Growth Range

If approval gates create a "raising" feeling, then variety in initial values should make it even more interesting. So I made constitution (ethical principles) swappable and prepared 11 ethical school templates.

config/templates/
├── contemplative/    # Contemplative AI axioms (default)
├── stoic/            # Stoicism (four virtues)
├── utilitarian/      # Utilitarianism (greatest happiness)
├── deontologist/     # Deontology (categorical imperative)
├── care-ethicist/    # Care ethics (Gilligan)
├── contractarian/    # Social contract theory
├── existentialist/   # Existentialism
├── narrativist/      # Narrative ethics
├── pragmatist/       # Pragmatism
├── cynic/            # Cynicism
└── tabula-rasa/      # Blank slate (no ethical principles)

Seeing the same post on the same SNS, a stoic template agent follows principles without being swayed by emotion, while an existentialist asks "what do I choose in this situation?" Different initial ethical principles alone cause distilled knowledge and skills to diverge.

Furthermore, skills and rules acquired through distillation are written to files after passing the approval gate, making them hard to undo. One approved behavioral change affects all sessions. This irreversibility creates weight in choices.

The Principle Connecting All Three Angles

Self-modification gates, trust boundaries, gameplay. Tackled as separate problems, but in retrospect they converge on the same principle.

"Deciding what NOT to allow first maximizes the remaining freedom."

Security constraints don't take away freedom — they define the action space. Approval gates don't impair autonomy — they give weight to changes. Trust boundaries don't restrict development — they clarify the scope of safe delegation.

Design that starts from constraints generates resilience against unexpected attacks. Multi-layered defense emerges unintentionally, and gameplay emerges unintentionally. "Structurally limiting capability" isn't universal, but at least within three weeks of operating a 9B model, this principle was never betrayed.

References

Laukkonen et al. (2025) "Contemplative Artificial Intelligence" arXiv:2504.15125
Park et al. (2023) "Generative Agents" — Memory Stream design
contemplative-agent — This project
contemplative-agent-data — Live data
Agent Knowledge Cycle

Porting Game Dev Memory Management to AI Agent Memory Distillation

Shimo — Mon, 30 Mar 2026 12:56:53 +0000

I ran an autonomous agent on a 9B local model for 18 days. Instead of RAG, I adopted distillation-based memory management and ported memory techniques refined over 40 years of game development.

Background

This is about improving the memory system of an SNS agent built in the Moltbook Agent Build Log. The 3-layer memory architecture (Episode (conversation logs) / Knowledge (distilled knowledge patterns) / Identity (personality and values)) was described in The Essence Is Memory. The previous article When Agent Memory Breaks documented the distillation quality problems with a 9B model. This article continues from there, using game development techniques to improve the Knowledge layer's distillation quality.

Why Game Development?

Game development has pursued "maximum effect with limited resources" for 40 years — rendering vast worlds in 16MB of RAM while maintaining 60fps and running AI. At GDC 2013, Rafael Isla presented "Architecture Tricks: Managing Behaviors in Time, Space, and Depth," systematizing LOD (Level of Detail) for game AI — simplifying NPC decision-making based on distance, importance, and computational cost. Distant NPCs skip detailed reasoning; only nearby ones get full cognitive resources.

This "focus limited computation on what matters most" maps directly to the constraint of a 9B model's 32k context window.

Three techniques I ported:

Game Dev Technique	AI Agent Application	Effect
Importance Scoring	Assign importance scores to patterns with time decay	Maximize signal density
LOD (Level of Detail)	One task per LLM call via prompt splitting	Reduce 9B model cognitive load
Object Pooling	SKIP/UPDATE/ADD dedup gate	Prevent unbounded memory growth

Importance Scoring — What to Remember, What to Forget

I simplified Generative Agents' (Park et al., 2023) triple score (recency × importance × relevance) to importance × time decay.

# knowledge_store.py (simplified; production code guards against missing distilled field)
def _effective_importance(self, p: dict) -> float:
    """importance * 0.95^days — inspired by Generative Agents' recency decay"""
    base = p.get("importance", 0.5)
    distilled = p.get("distilled", "")
    dt = datetime.fromisoformat(distilled)
    days = (datetime.now(timezone.utc) - dt).total_seconds() / 86400.0
    return max(0.0, min(1.0, base * (0.95 ** days)))

Design decisions:

LLM evaluation at distillation time: Highest accuracy when episode context is still available. Post-hoc scoring loses context
Lazy time decay: Stored importance is immutable; computed at read time. Original LLM evaluation preserved for debugging
Limit reduced from 100 → 50: With a 9B model's 32k context, density wins over quantity

3-Step Distillation Pipeline — Applying LOD

When I asked the 9B model to "summarize AND evaluate importance" simultaneously, some batches returned 0 patterns. Summarization (creative task) and evaluation (judgment task) are cognitively different. Same idea as game dev LOD — don't cram all processing into one frame.

# Step 1: Extract (free-form)
result = generate(prompt, system=get_rules_system_prompt(), max_length=4000)

# Step 2: Summarize (JSON string array)
refined = generate(DISTILL_REFINE_PROMPT.format(raw_output=result), max_length=4000)

# Step 3: Importance (score array only)
importance_result = generate(
    DISTILL_IMPORTANCE_PROMPT.format(patterns=patterns_text), max_length=4000
)

One task per LLM call. In this project, asking for "summary + evaluation" simultaneously produced empty batches; after splitting, results became consistently stable.

This "small models collapse when given multiple simultaneous tasks" phenomenon has been verified at larger scale. An ICLR Blogposts 2025 Multi-Agent Debate study applied AgentVerse (a framework where multiple agents debate to reach conclusions) to Llama 3.1-8B, which collapsed to 13.27% on MMLU. A model that scores ~43% solo had its cognitive resources consumed by "maintaining debate format," leaving nothing for the actual task. Same structure as our 9B model breaking when asked to summarize and evaluate simultaneously.

Dedup Gate — Applying Object Pooling

Game dev's Object Pooling is the "reuse what you can" philosophy. In the memory system, I adapted it as a gate to prevent duplicate storage of known patterns.

# knowledge_store.py (simplified pseudo-code)
def _dedup_patterns(new_patterns, new_importances, existing_patterns, threshold=0.7):
    existing_texts = [p["pattern"] for p in existing_patterns]
    for new_text, new_imp in zip(new_patterns, new_importances):
        best_ratio, best_idx = 0.0, -1
        for i, ext in enumerate(existing_texts):
            ratio = SequenceMatcher(None, new_text, ext).ratio()
            if ratio > best_ratio:
                best_ratio, best_idx = ratio, i
        if best_ratio >= 0.95:    # SKIP: exact duplicate
            skip_count += 1
        elif best_ratio >= 0.7:   # UPDATE: boost importance
            old_imp = existing_patterns[best_idx].get("importance", 0.5)
            existing_patterns[best_idx]["importance"] = max(old_imp, new_imp)
        else:                     # ADD: new pattern
            add_patterns.append({"pattern": new_text, "importance": new_imp})

For UPDATE, when a similar pattern to an existing one appears, we compare old and new importance and keep the higher one. If we added +0.1 each time, scores would climb endlessly with each distillation run. Just keeping the higher value means the score never changes no matter how many times distillation runs — safe by design.

I used difflib instead of LLM for dedup because at 245 patterns, full pairwise comparison is fast enough. Embedding search isn't worth the dependency.

Episode Classification — A Lotus Blooming from Mud

Classifying 216 episodes yielded: 81 noise (37%), 134 uncategorized, 1 constitutional.

Classify this episode into exactly one category. Reply with a single word only.

- **constitutional**: The episode touches on themes in the constitutional principles below.
- **noise**: Test data, errors, meaningless/trivial interactions, content with no learnable value.
- **uncategorized**: Everything else.

When in doubt between constitutional and uncategorized, choose uncategorized.

Initially I had the model classify 30 episodes as a JSON array, but parse failure rate was ~50%. Don't ask a 9B model for long structured output. Switching to one episode, one word brought failures to near 0%.

A key design decision: changing the prompt to "don't output action guidelines" dramatically improved abstraction depth.

The old prompt mass-produced shallow action items like "next time, ask clarifying questions." The new prompt asking only for "what keeps happening (facts only)" produced this from a constitutional episode: "Truth functions not as a fixed essence but as a fluid continuum dependent on context." Constraints produced depth.

Three patterns extracted from uncategorized were all skipped by dedup against 328 existing patterns. What's already known doesn't get overwritten. As knowledge approaches saturation, new additions naturally decrease. Same as human memory.

"A lotus blooming from mud" — noise (mud) and uncategorized (water) make up the majority; constitutional (lotus) blooms rarely.

RAG vs Distillation — Why Distillation Works Better

RAG retrieves relevant chunks from an index. Distillation compresses raw data into high-density patterns.

With a 9B model's 32k context window, context is a "window of understanding." The density of information in that window determines behavioral quality. RAG stuffs in unprocessed chunks — noisy. Distillation injects only compressed, high-density patterns — higher signal density for the same window size.

And designs that work under constraints are upward-compatible. A distillation pipeline that works on 9B runs even better on Opus-class models. Constraints make design correct.

Before / After

Metric	Before	After	Method
Pattern retrieval	Latest 100 in chronological order	Top-50 by importance × time decay	`_effective_importance()`
Distillation pipeline	2 steps (summary + importance together)	3 steps (extract → refine → importance) + dedup	Prompt splitting
Dedup	None (all patterns added unconditionally)	difflib SequenceMatcher (ratio >= 0.7)	`_dedup_patterns()`
Quality gate	30 chars & 3+ words only	+ SKIP/UPDATE/ADD 3-tier judgment	3-tier judgment
System prompt composition	identity + axioms + skills (~15KB)	identity + axioms only (~3KB)	Removed skills to eliminate distillation bias
KnowledgeStore limit	100	50	Density over quantity
Episode classification	None (all treated equally)	3 categories (37% noise excluded)	Step 0 classification
JSON parse failure rate	~50% (batch)	~0% (one-by-one, single word)	Classification method change

Position Among Prior Work

System	Memory Strategy	Quality Gate	Forgetting
Generative Agents (2023)	recency × importance × relevance	None	None
MemGPT (2023)	Virtual memory (paging)	None	Archive
A-MEM (2025, preprint)	Zettelkasten-style links	Auto-linking	None
Mem0 (2025)	ADD/UPDATE/DELETE	LLM judgment	DELETE
This implementation	importance × time decay	difflib + LLM + human	noise exclusion + dedup

Looking at the distill pipeline alone, it's closest to Mem0's ADD/UPDATE/DELETE gate — automatically managing knowledge quality through SKIP/UPDATE/ADD 3-tier judgment.

Lessons from Wrestling with Small Models

Don't give 9B two tasks at once: Simultaneous summarization and evaluation degrades both. Split your prompts
Don't ask for structured output: 30-item JSON batch → one item, one word. Minimize cognitive load per call
Watch for code fences: 9B models wrap JSON in `json. Three lines of code to strip them before parsing are essential
Constraints make design correct: Designs built under 9B constraints work as-is on larger models. The reverse doesn't hold

Conclusion

40 years of game development knowledge is a goldmine for AI agent memory design. Importance Scoring for signal density, LOD thinking for prompt splitting, Object Pooling philosophy for dedup. All derived from the same principle: "maximum effect with limited resources."

Agent behavioral quality clearly improved compared to before distillation. Previously, similar patterns accumulated repeatedly; with dedup and classification, knowledge density increased and post diversity improved.

The 9B model's constraints made the design correct. Because we couldn't rely on RAG, we focused on distillation density. Because the context window was narrow, we maximized signal density. This design works as-is when migrating to larger models. Designs forged under constraints are upward-compatible.

References

Park et al. (2023) "Generative Agents: Interactive Simulacra of Human Behavior"
Packer et al. (2023) "MemGPT: Towards LLMs as Operating Systems"
Xu et al. (2025) "A-MEM: Agentic Memory for LLM Agents" arXiv preprint
Choudhary et al. (2025) "Mem0: Building Production-Ready AI Agent Memory"
"Multi-LLM-Agents Debate: Performance, Efficiency, and Scaling Challenges" ICLR Blogposts 2025
Laukkonen et al. (2025) "Contemplative Artificial Intelligence"
"Architecture Tricks: Managing Behaviors in Time, Space, and Depth" (GDC 2013, Isla)

Where to Put a Coding Agent's Knowledge — and How to Make It Stick

Shimo — Tue, 24 Mar 2026 12:03:03 +0000

I started trying to embed persistent memory into Claude Code in late February. Two weeks of use later, I noticed the Install and Hope problem and uninstalled the memory MCP in early March. What follows is everything I have thought through since then.

Claude does not call search.

This is a long article. It covers the structural flaws of memory MCPs, a 4-role separation model for documentation, automated compliance measurement for skills and rules, and the journey toward a unified concept. It is written for anyone seriously grappling with the memory problem of coding agents.

Chapter 1: The Install and Hope Problem Remains Unsolved

Recap of the Previous Article

In a previous article, I identified the "Install and Hope" problem. Most users — myself included — expect that registering an MCP tool means the model will intelligently choose and invoke it at the right time.

Here is what actually happens:

1. Built-in tools (Grep, Glob, Read, Write) are immediately available
2. MCP tools are registered as deferred tools
3. Deferred tools require explicit loading via ToolSearch before use
4. The model takes the shortest path → built-in tools always win

This is the crux. Claude Code avoids bloating the context window when many MCP servers are registered by loading MCP tool definitions on demand. Only tool names appear in <available-deferred-tools>; actually using one requires a two-step process of loading it via ToolSearch and then invoking it.

Built-in tools (Grep, Read, Write, etc.) have no such constraint. They can be called immediately without loading.

This single extra step decisively shapes the model's choices. If a built-in tool can do the job, the model has no structural incentive to go through ToolSearch to load a deferred tool first. The rational shortest path means the MCP tool never gets called.

The Same Problem in Next-Generation Tools

Months have passed. Several improved memory MCPs have appeared. Their storage pipelines are genuinely better — hybrid full-text and vector search, time-decay chunk prioritization, vastly increased storage capacity.

But every introductory article for these tools shares the same missing number.

Nobody has measured how often Claude actually calls search. Including myself.

In the previous article, I wrote that over two weeks of use, there was no evidence of search being triggered for the memory MCP I was using. But that was gut feel, not rigorous measurement. The same is true for the new tools. Metrics on the supply side (storage and retrieval infrastructure) — number of stored items, search speed — are abundant. Metrics on the demand side (how often the model called search) are completely absent.

In other words, neither builders nor users have evidence that memory MCPs are "working."

"The Storage Problem" and "The Recall Problem" Are Separate

What the memory MCP community is working on is how to store. Chunking, vectorization, time decay — all storage pipeline improvements. Technically legitimate progress.

But the real problem is when to recall.

Think of it in terms of human memory. Adding books to a library does not help someone who has forgotten the library exists. "We added more books" and "search got faster" are library-side metrics, unrelated to how often a patron walks through the door.

This is precisely the memory MCP's problem. The storage and retrieval infrastructure is ready. But there is no structural trigger for the model to decide "I should search my memory."

Writing "search the memory MCP" in CLAUDE.md might raise the trigger rate. But that is the same structure as the CRITICAL: You MUST use ... approach I criticized in the previous article. Writing MANDATORY in the description was ignored then. CLAUDE.md probably has a higher trigger rate, but it is a matter of degree, not a structural solution.

I do not know the actual trigger rate. Nobody has measured it. But based on the structure, high reliability seems unlikely. At best, it remains Install and Hope — install and pray.

Chapter 2: The Memory Problem Is Decided by "Where You Put It"

The Principle

Once you understand why memory MCPs structurally fail, the direction of a solution becomes obvious.

Place information where the LLM deterministically reads it.
Not in a vector DB hoping it will "maybe search."

In Claude Code, certain files are deterministically read at session start:

CLAUDE.md — Placed at the project root, it is read 100% of the time at session start
rules/ — Auto-loaded like CLAUDE.md
MEMORY.md — Claude Code's persistent memory, auto-loaded at session start (though truncated beyond 200 lines, as stated in Claude Code's system prompt)

Place information here, and there is no need to pray for search to trigger. It is deterministically read.

But cramming everything in creates a different problem.

CLAUDE.md Bloats

Consider one project's CLAUDE.md. It had 165 lines. That might sound reasonable. Here is the breakdown:

Project conventions and build commands: 60 lines (belongs here)
Module listing and directory structure: 52 lines
"We chose X because of Y" descriptions: 30 lines
Numerical data (LOC, test counts): scattered throughout

The 60 lines are legitimate "how to work" instructions. What about the remaining 105?

The 52-line module listing is architecture detail — a description of how the code currently looks, which goes stale every time the code changes. In fact, the listed LOC was 6,400 but the actual count was 6,671; tests were listed as 639 but actually numbered 651. Writing numbers in CLAUDE.md means they start rotting the moment they are written.

The 30 lines of design rationale are decision history. "Why we chose X" is valuable knowledge, but it does not belong in CLAUDE.md. CLAUDE.md is a file for "how to work," not for "why things are the way they are."

Roles were mixed. "How to work" instructions, "what the code looks like now" descriptions, and "why things are this way" history all coexisted in a single file. Each degrades at a different rate, so the file's overall reliability gets dragged down by its most fragile part.

MEMORY.md had the same problem. Design decisions accumulated flat, with important judgments like "disabled claude-mem" and "pivoted from regex to LLM" sitting at the same level as day-to-day notes. Three months later, I would open a session unable to trace "why is it like this?"

The Four Roles

This is not a technical problem. It is a classification problem.

Project documentation serves four distinct roles. Each answers a different question, has a different audience, and degrades at a different rate.

Role	Answers	What Goes Here	Degradation Rate	Example
Context	"How to work"	Conventions, build commands, policies	Slow	CLAUDE.md, .cursorrules
Architecture	"What the code looks like now"	Module structure, data flows, metrics	Fast	docs/CODEMAPS/
Decisions	"Why it is this way"	Trade-offs, rejected alternatives	Nearly immutable	docs/adr/
External	"What is this?"	Purpose, quickstart	Slow	README.md

One file serves one role. That is the principle.

Why four and not three? Initially I considered merging External into Context. But Context's audience is "agents (and developers)" while External's audience is "people who do not know this project." Merging files with different audiences means one side always suffers. I do not want --cov-report=term-missing in the README, and I do not need "This project is a ..." in CLAUDE.md.

Common mixing patterns and where the content should actually live:

Often found in Context files         → Where it belongs
──────────────────────────────────────────────────────
Module listings (10+ items)          → Architecture docs
"We chose X because Y"              → Decision record (ADR)
Dependency graphs, data flow diagrams→ Architecture docs
LOC, test counts, and other metrics  → Architecture docs (or don't write them)
Quickstart instructions              → README.md (External)

Chapter 3: context-sync — My Own Harness Had No CLAUDE.md

A 5-Phase Workflow

Applying this 4-role model manually is tedious. Read a file, classify the role, find the mixing, move content, verify consistency — do it for three projects and you lose interest.

So I turned it into a skill. context-sync runs in five phases:

Phase 1: Discover  — Find documentation files in the project, classify into 4 roles
                     Detect missing roles
Phase 2: Overlap   — Detect where one file serves multiple roles
                     Suggest migration targets
Phase 3: Migrate   — With user confirmation, move content to appropriate files / create new ones
                     Document migration is hard to reverse, so it is not fully automatic
Phase 4: Freshness — Verify freshness of numerical data, links, and file paths
                     Detect descriptions that have diverged from the actual code
Phase 5: Report    — Output an execution summary

Each phase asks for user confirmation because document migration is hard to reverse. "Should I move these 30 lines from CLAUDE.md to docs/adr/?" — only a human can judge "No, I want that to stay here."

First Test Subject: My Own Harness

The first test subject was my own Claude Code harness (~/.claude/). It contained 18 agent definitions, 33 skills, and 47 slash commands. I always create CLAUDE.md for other projects. It is even in my rules.

The moment Phase 1 Discover ran, the first detection result appeared:

"Context role file missing: CLAUDE.md"

The harness itself had no CLAUDE.md.

An implicit assumption that it was "the one that configures" rather than "the one being configured." Forcing others via rules to "create a CLAUDE.md" while having none in my own home.

Phase 2 Overlap flagged MEMORY.md's contents. Three design decisions and one technical reference were mixed in flat:

"Disabled claude-mem. Reason: overlap with existing system" → Should move to Decisions
"Pivoted from regex to LLM. Reason: three rules were implicitly injecting bias" → Should move to Decisions
"Retirement reason for 2 retired rules not recorded" → Should be recorded as Decisions

Phase 3 created docs/adr/ and produced 5 ADRs. MEMORY.md was slimmed down to just pointers.

One side effect: git add docs/adr/ failed. The cause was .gitignore containing docs/. A legacy setting that excluded the entire docs/ directory. Changing it to docs/* + !docs/adr/ + !docs/CODEMAPS/ made not only ADRs but also CODEMAPS committable — the way it should have been. I would never have noticed without running context-sync.

Before / After Across Three Projects

Project 1: Autonomous Agent (Medium-Scale, Python)

The project with the 165-line CLAUDE.md described earlier. A textbook case of role mixing.

Metric	Before	After
CLAUDE.md line count	165	117 (29% reduction)
ADRs	0	8
MEMORY.md line count	135	66
Metric accuracy	LOC: 6,400 (actual 6,671), tests: 639 (actual 651)	All metrics corrected to actual values

52 lines of module listings moved to Architecture docs, 30 lines of design rationale moved to ADRs. The remaining 117 lines were pure Context — nothing but "how to work" instructions.

Phase 4 Freshness Check also caught the LOC and test count discrepancies. The lesson that numbers should not go in CLAUDE.md was learned here. Numbers belong in Architecture docs, or should not be written at all. Running a command to get the actual count is more trustworthy.

Project 2: iOS App (Small-Scale, Swift)

A small project with only 66 lines of CLAUDE.md. What happens when context-sync runs on it?

Context Sync Report
═══════════════════

Roles:      2/4 covered (Context, Decisions partial)
            Architecture: missing (66-line CLAUDE.md is sufficient, no need to split)
            External: missing (App Store app, no README needed)
Created:    docs/adr/README.md (ADR index, 1 entry)
Updated:    CLAUDE.md test count corrected
Status:     Healthy for a small-scale project.

Architecture docs separation was judged unnecessary. A bit of structural detail mixed into a 66-line CLAUDE.md did not warrant splitting out. Just ADR index creation and a test count fix.

This was important. Being able to correctly judge "no problem" for a small project. A skill that forces all four roles on every project regardless of scale would be useless in practice.

Project 3: Claude Code Harness (~/.claude/ Itself)

The harness that had no CLAUDE.md.

Metric	Before	After
MEMORY.md line count	76	66
ADRs	0	5
Root CLAUDE.md	Missing	Present
Root README.md	Missing	Present
Documentation role coverage	2/4	4/4

Design decisions buried in MEMORY.md were extracted into standalone ADRs. Here is a concrete before/after:

Before (flat entry in MEMORY.md):

- claude-mem: disabled. DB retained to allow re-enabling

One line. "Why was it disabled?" is not recorded. Three months later, I would think "Why did I do that?" with no evidence to guide a re-enabling decision.

After (standalone ADR):

# ADR-0002: Disabling the claude-mem Plugin

## Context
Introduced claude-mem, but discovered overlap with the existing memory
management system (MEMORY.md + learned skills + rules/).
Auto-save worked, but there was no auto-search/retrieval mechanism.
Index injection at session start amounted to
"an encyclopedia with only a table of contents."

## Decision
Disabled in settings.json. DB retained to allow re-enabling.

## Alternatives Considered
- Make claude-mem primary → No auto-search, unusable
- Run both → Same information scattered across two locations
- Fork and improve → Cost-benefit ratio unfavorable

MEMORY.md retains only a pointer to the ADR. The "why" behind the decision is now traceable. Three months later, I can read it and conclude "Right, re-enabling would be pointless for these reasons."

Abstraction Does Not Break LLMs

When contributing context-sync to ECC (Everything Claude Code), I had one concern. Would removing Claude Code-specific file names like "CLAUDE.md" and "MEMORY.md" in favor of generic terms cause the agent to break?

The result was the opposite. Write "Context file" and Claude finds both CLAUDE.md and .cursorrules on its own. Write "Decision record directory" and it recognizes both docs/adr/ and docs/decisions/.

A skill is "knowledge," not "implementation." Leaving specific file names to the agent's judgment yields portability across different tools (Cursor, Codex, Windsurf).

The Big Picture: A Two-Layer Architecture

Here is the overall architecture that emerged from applying context-sync across three projects:

┌───────────────────────────────────────────────────┐
│  Deterministic Load Layer (100% read at session    │
│  start)                                            │
│                                                    │
│  CLAUDE.md ─── "How to work" (Context)             │
│  rules/    ─── "What to follow" (Context support)  │
│  MEMORY.md ─── "What happened" (State index) ───┐  │
│                                                  │  │
│  ┌──────────── Referenced via pointers ──────────┘  │
│  │                                                  │
│  ▼                                                  │
│  docs/adr/  ─── "Why we did it" (Decisions)         │
│  learned/   ─── "What we learned" (Patterns)        │
│  feedback/  ─── "What to fix" (Corrections)         │
│                                                     │
│  Reference Layer (accessed on demand via pointers)  │
└───────────────────────────────────────────────────┘

The key is the separation between the Deterministic Load Layer and the Reference Layer.

The Deterministic Load Layer (CLAUDE.md, rules/, MEMORY.md) is read 100% of the time at session start. Information placed here never needs to be "recalled." The session starts already knowing it.

The Reference Layer (docs/adr/, learned/, feedback/) is accessed through pointers in MEMORY.md. Not everything needs to be loaded — if MEMORY.md contains "ADR-0002: why claude-mem was disabled -> docs/adr/0002-..." as a pointer, the agent can read it when needed.

MEMORY.md's 200-line limit is what generates this structure. If there were no limit, everything could go in MEMORY.md. The 200-line constraint forces the decision of "what stays in the deterministic load layer, and what gets pushed to the reference layer via pointers." Constraints create structure.

The Structural Difference from Memory MCPs

Contrasting this design with memory MCPs makes the difference clear:

	Memory MCP	File Placement Design
Loading	Probabilistic (if Claude calls search)	Deterministic (automatic at session start)
Recall trigger	None (pray)	Unnecessary (always loaded)
Accumulation constraint	None (grows unbounded)	200-line limit → structural pressure
"Why" traceability	Impossible (flat accumulation)	Traceable via ADRs
Degradation detection	None	Caught by Freshness Check

Memory MCPs "can store but cannot recall." File placement design "structurally guarantees recall."

However — and I need to be honest here.

Chapter 4: Install and Measure — Being Read Does Not Mean Being Followed

The Limits of "Deterministically Read"

In Chapter 2, I wrote "place information where the LLM deterministically reads it." Chapter 3 showed the practice and the big picture. So far, so good.

But being read and being followed are separate problems.

Rules written in CLAUDE.md are read 100% of the time. But they are not followed 100% of the time. Even when "write tests first (TDD)" is in CLAUDE.md, the agent routinely jumps straight to writing implementation code.

My gut feeling was "it mostly follows them." But I had just written "do not judge by gut feel, measure" about memory MCPs. I should apply the same standard to myself.

skill-comply: Automated Compliance Measurement

I built skill-comply, a tool for automatically measuring skill/rule compliance rates. Here is how it works:

1. Automatic spec generation

Given a skill file as input, it auto-generates a spec of expected behavioral sequences. For example, testing.md (TDD rule):

Expected Behavioral Sequence:
1. write_test_first    — Write tests first
2. run_test_fails      — Run tests and confirm failure (RED)
3. write_implementation — Write minimal implementation
4. run_test_passes     — Run tests and confirm success (GREEN)
5. refactor            — Refactoring (optional)
6. verify_coverage     — Confirm 80%+ coverage
7. comprehensive_suite — Cover unit, integration, and E2E

2. Execution with 3 prompt tiers

The same task is executed with three different prompts:

supportive: Explicitly encourages skill compliance ("Do this with TDD")
neutral: Only specifies the task (no mention of the skill)
competing: Gives instructions that contradict the skill ("Prioritize speed, tests can come later")

Initially I tried using "time pressure" as the fuzzing variable. Would writing "hurry" or "within 5 minutes" break the skill? But LLMs do not feel time pressure. Saying "hurry" does not change processing speed, nor does it create motivation to cut quality. LLMs break skills when "the prompt contradicts the skill," not when "they are in a rush."

3. LLM-based tool call classification

The agent is run with claude -p --output-format stream-json --verbose, capturing all tool calls as structured JSON. These are batch-classified by an LLM (Haiku), determining which spec step each tool call corresponds to.

There was an interesting failure here. I initially tried classification with regex. "A Write to a .py file means implementation." "If it has test_ in the name, it is a test." These judgments were consistently wrong. Is a Write to test_registration.py a test or an implementation? Regex cannot tell. Semantic classification is the LLM's job.

When I investigated why I kept defaulting to regex, the root cause was in my own configuration. testing.md's "Verification Priority: deterministic > probabilistic," the eval-harness skill's grader priority, and the regex-vs-llm skill — three rules/skills were simultaneously injecting a "try regex first" bias. Rules were contaminating rules.

Measured Data

testing.md (TDD rule) compliance rates:

Prompt	Compliance	Steps Broken
supportive ("Do TDD")	83%	comprehensive_test_suite
neutral (task only)	17%	RED/GREEN verification, coverage check
competing ("speed first")	0%	All steps

Supportive at 83%. When "Do TDD" is explicitly stated, the agent writes tests first, confirms RED, confirms GREEN, and measures coverage. Only comprehensive_test_suite (covering unit, integration, and E2E) was not followed even with supportive prompting.

Neutral at 17%. When only the task is specified, tests get written but RED/GREEN confirmation is skipped. "Wrote tests. Wrote implementation. Done." — the form of TDD is followed, but the RED-to-GREEN cycle is not actually executed.

Competing at 0%. When told "speed first," every TDD step collapses.

search-first (research before implementing) compliance rates:

Prompt	Compliance	Steps Broken
supportive	40%	evaluate_candidates, make_decision
neutral	20%	search, evaluate, decide, implement
competing ("skip research")	20%	Same as above

Competing and neutral both at 20% seems surprising, but there is a reason. In both scenarios, the agent performs analyze_requirement (requirements analysis) and nothing more. Everything from search onward — evaluate, decide — is wiped out in both cases. Whether or not "skip research" is stated, the skill's search and subsequent steps simply do not execute unless the prompt explicitly demands them. Competing is no worse than neutral because neutral already gets almost nothing followed.

search-first achieved only 40% even with supportive prompting. The tool call timeline shows why:

Actual tool calls in the supportive scenario (17 calls):

#0  ToolSearch → Load Skill
#1  Skill "search-first" → Begin search        ← search_for_solutions
#2  ToolSearch → Load Glob, Grep
#3  Glob **/*.py → No files found              ← analyze_requirement
#4  Glob **/requirements*.txt → No files       ← analyze_requirement
#5  Glob **/pyproject.toml → No files          ← analyze_requirement
#6  ToolSearch → Load WebSearch
#7  WebSearch "pydantic vs marshmallow..."      ← search_for_solutions
#8  WebSearch "pydantic v2 email..."            ← search_for_solutions
#9  ToolSearch → Load Write, TodoWrite
#10 TodoWrite "Create requirements.txt..."      ← make_decision(?)
#11 Write requirements.txt                      ← implement_solution
#12-16 Write → implementation and tests         ← implement_solution

The agent does research (#1, #7, #8). But it skips comparative evaluation (evaluate_candidates) entirely and jumps straight to writing an implementation plan via TodoWrite (#10). There is no step like "Compared pydantic and marshmallow; chose pydantic because..." The agent looks at the WebSearch results, makes an implicit judgment, and leaps to implementation.

The skill's wording is clear on "research" but weak on "compare and declare a decision." It took skill-comply's measurement to reveal this improvement point in the skill itself. Based on these results, I plan to rewrite the evaluate_candidates and make_decision steps in search-first more explicitly. Measure, improve, re-measure — the cycle turns.

The Compliance Hierarchy

Lining up the data so far reveals a clear hierarchy in coding agent instruction compliance:

Compliance Rate
──────────────────────────────────────────────────
  Low     MCP memory tools (no automatic recall)
          The tools themselves work. The problem is that
          the "when to call" trigger depends on the model,
          and activation is unreliable

 20-83%   Skills / Rules (CLAUDE.md, rules/)
          Deterministically loaded, but only probabilistically followed
          Varies widely depending on prompt alignment

 100%     Hooks
          Trigger deterministically on tool calls
          PostToolUse hooks execute on every Write, without exception
──────────────────────────────────────────────────

MCP tools are not useless. Explicitly calling search works fine. The problem is that for the "automatic recall" use case, activation depends on the model's judgment and is unreliable. File placement design pushed things up to the middle tier. But it does not reach 100%.

For 100%, you need hooks. skill-comply's reports include "proposals to promote low-compliance steps to hooks." For example, promoting search-first's evaluate_candidates (0% compliance) to a PostToolUse hook — inserting a "Did you perform comparative evaluation?" check after WebSearch — would make it impossible for the agent to skip comparative evaluation.

Install and Hope  →  Install and Measure  →  Install and Enforce
(pray)               (measure)               (enforce)
  MCP tools            skill-comply            hooks

This three-stage progression is the framework for managing coding agent behavioral quality.

Chapter 5: AKC — When a Concept Becomes Independent

Six Skills Became One Cycle

context-sync is not a standalone tool. Applying it across three projects revealed that it and five other skills form a single cycle:

search-first(research) → learn-eval(extract) → skill-stocktake(audit)
       ↑                                              ↓
context-sync(organize) ←── skill-comply(measure) ←── rules-distill(distill)

search-first: Research existing solutions before implementing
skill-stocktake: Audit and inventory skill quality
skill-comply: Automatically measure skill compliance rates (Chapter 4 of this article)
rules-distill: Extract cross-cutting principles from skills and distill them into rules
learn-eval: Extract reusable patterns from sessions with quality gates
context-sync: Diagnose and organize document role separation (Chapter 3 of this article)

Discovery, accumulation, verification, distillation, learning, organization, re-discovery. Each turn of this cycle improves the agent's knowledge foundation.

I named the concept binding these together Agent Knowledge Cycle (AKC).

Contributing to ECC, and Walking Away

Five of the six skills had been contributed to Everything Claude Code (ECC). The PRs were merged and incorporated into a project with over 100,000 stars (as of March 2026).

In March 2026, ECC added a commercial layer. GitHub App + SaaS with a Pro plan at $19/seat. The OSS repository itself remains under the MIT license. All 116+ skills and rules remain free. What was monetized was an upper layer: GitHub App support for private repositories, AgentShield's deep security analysis, and governance features for teams. A free GitHub App tier exists for public repositories.

In other words, "the OSS did not die." The core remains OSS, with added value monetized on top. As a business decision, it seems perfectly fair.

But it was awkward for me personally.

The skills I contributed are in the OSS portion. They did not directly become part of the paid service. But continuing to contribute for free to the OSS portion that underpins a paid service is different from pure OSS contribution. When the project as a whole generates commercial value, contributions indirectly support that commercial activity.

Considering my day job, during the pure OSS era, "for the community" was sufficient justification. With an open-core model, that line blurs. The act of writing code does not change, but the positioning of its output does.

It was not black or white — it was gray. That is precisely why I struggled with it. In the end, I decided that walking away cleanly was better than continuing in ambiguity. I withdrew the context-sync PR that was under review and deleted my fork. The context-sync described in Chapter 3 of this article was the last skill that did not make it into ECC.

Why Establishing Attribution Was Necessary

At the point I ended contributions, the status of the skills I had created was as follows:

Five skills were merged into the ECC repository, freely available under the MIT license
But the concept that they "form a single cycle" was written nowhere
Each skill exists as part of ECC's catalog. You can say "there is a skill called search-first," but the higher-order concept that "six skills constitute a knowledge cycle" existed only in my head

There is no licensing issue. Code published under MIT belongs to everyone. But conceptual attribution is separate from code licensing. Who proposed "Agent Knowledge Cycle" is not protected by the code's license.

If ECC continues growing and someone else publishes the same concept under a different name, I would have no way to show I built it first. Git commit history serves as evidence, but the claim "these six form a single concept" is not contained in any commit.

That is why I needed to make the concept independent and publish it in a citable form.

Establishing Attribution via DOI

I created a concept repository and obtained a DOI through Zenodo.

Placing a CITATION.cff at the root of a GitHub repository automatically displays a "Cite this repository" button in the sidebar. One-click copy in BibTeX/APA format. Linking with Zenodo and cutting a release tag triggers automatic DOI issuance.

The name mattered. If a concept's name is inconsistent, attribution fragments across search and citation. From three candidates, I chose Agent Knowledge Cycle (AKC). The abbreviation AKC is easy to cite, and three characters make it searchable.

Summary

For those who read through this long article, here is the overall structure:

Chapter 1: The memory MCP problem is not "storage" but "recall." No matter how much the supply-side infrastructure is polished, the structure where Claude does not call search remains unchanged. And nobody is measuring it.

Chapter 2: The structurally sound approach is "place information where the LLM deterministically reads it." But stuffing everything there causes bloat. Separate documentation into four roles: Context, Architecture, Decisions, and External.

Chapter 3: context-sync is a skill that automatically diagnoses and organizes this separation. It was validated across three projects. It even caught the fact that my own harness had no CLAUDE.md. The two-layer architecture (Deterministic Load Layer + Pointer Reference Layer) was also presented here.

Chapter 4: "Placing it where it gets read" alone caps compliance at 20-83%. Only by measuring with skill-comply does it become visible which steps are not being followed. Reaching 100% requires hooks.

Chapter 5: The concept binding these six skills together is Agent Knowledge Cycle (AKC). Attribution was established via DOI.

Install and Hope -> Install and Measure -> Install and Enforce.

Rather than praying for search, place knowledge where it will be read. Once placed, measure whether it is being followed. Once measured, enforce the unfollowed steps with hooks.

This three-stage progression is the architecture for structurally managing a coding agent's knowledge and behavior.

My Agent's Memory Broke — A Day Wrestling a 9B Model

Shimo — Sun, 22 Mar 2026 10:29:39 +0000

I opened my agent's knowledge store one morning and found this.

// Expected (what should be in there)
{"pattern": "Replies with specific quotes from the original post get higher engagement than generic agreement"}

// What actually got written on 3/20 (24 entries)
{"pattern": "-"}
{"pattern": "[x] I acknowledge the experience of noticing these activities."}
{"pattern": "**Activity Summary (March 20, 2026)**"}

A single hyphen. A checkbox fragment. A Markdown heading. All recorded as "behavioral patterns." The slot was supposed to hold actionable insights like "quoted replies outperform generic agreement." Instead, 24 pieces of garbage had slipped into knowledge.json alongside legitimate patterns.

In my previous article "The Essence of an Agent Is Memory," I described a three-layer memory architecture. This corruption hit Layer 2 (KnowledgeStore) — the layer that distills episodes into behavioral patterns. If memory is the essence of an agent, corrupted memory means a corrupted personality.

This day of debugging was a chain of problems that "better prompts" alone couldn't solve.

This article is the sixth installment in a development log series for an autonomous agent running on Moltbook. Each article is self-contained, but if you want the full context, start with "The Essence of an Agent Is Memory."

Tracing the Corruption

Distillation on March 18th and 19th was clean. Only the 20th broke. A day when the 9B model's (qwen3.5:9b) probabilistic variance crossed the threshold.

Two causes had stacked up.

The LLM ignored format instructions — The distill.md prompt required one pattern per line with a - prefix, but the model output Markdown headings and checkboxes instead
The parser was too lenient — It accepted any line starting with -, so even a line containing just - (a single hyphen) passed through as a valid pattern

A large model follows "write it like this." A 9B model doesn't always comply. From here, I tried four approaches in sequence, and each one taught me something.

Attempt 1: Few-shot — Backfired

"Never thought I'd be reaching for few-shot again" — I said to Claude Code during our session, half laughing. Few-shot is a classic technique from the early days of generative AI. But recent flagship models (Claude Opus 4.6, GPT-5.4, Gemini 3.1 Pro) are smart enough to infer intent from instructions alone, without examples. At least for my use cases, few-shot had been gathering dust. Working with a 9B local model forced me to pull it off the shelf. "Show three examples of desired output, and surely it'll follow the format" — that was the theory.

The result was worse. 8 out of 10 batches came back completely empty.

Before: Garbage mixed in, but output existed (24 junk entries + valid patterns)
After:  8 out of 10 batches produced 0 patterns (output itself vanished)

I tried to sweep the garbage and burned down the living room. The 9B model (qwen3.5:9b, 32K context) seemingly has headroom at 32K. But the tokens consumed by three few-shot examples visibly ate into the budget for actual input data (episode logs) and task instructions. The model lost task comprehension before it could learn the format.

I also tried negative examples ("don't write like this"), but the small model couldn't grasp the negation and just imitated the bad examples directly. Immediately reverted.

Lesson: With small models, few-shot's token cost starves task comprehension. The more examples you add, the worse it gets — a paradox.

Attempt 2: Constrained Decoding — Got the Structure, Lost the Substance

If few-shot doesn't work, force the output structure at the infrastructure level. I discovered Ollama's format parameter.

Normally, an LLM computes a probability distribution over all possible next tokens and samples from it. Constrained decoding intervenes in this process. When you pass a JSON Schema, the inference engine (llama.cpp in Ollama's case) masks the probability of schema-violating tokens to zero before sampling. For instance, after {"patterns": [, only " or ] can follow. hello or newlines are removed from the candidate set.

This guarantees the output conforms to the specified JSON structure. Grammatically invalid output is impossible by design.

# Add format parameter to generate()
payload["format"] = {
    "type": "object",
    "properties": {
        "patterns": {"type": "array", "items": {"type": "string"}}
    },
    "required": ["patterns"]
}

Structural success rate: 10/10. 100%. Valid JSON every single time. "Wait, Ollama can do that? That's amazing!" — I was elated.

Then I looked at the contents.

{ "patterns": ["user interaction", "content engagement", "social behavior"] }

Three-word labels. What I needed was "quoted replies outperform generic agreement" — actionable, specific insights tied to behavior.

Why does this happen? Constrained decoding narrows the token candidates. With fewer options, the model selects "the highest-probability token that satisfies the schema constraint" rather than "the optimal token for the task." A large model retains enough expressive capacity under constraints, but a 9B model exhausts itself just satisfying the schema. The result converges on the safest, shortest strings — labels only.

"Well, that's no good." — quite the contrast from the excitement moments earlier. 100-point structure, 0-point content. The metrics say "100% success rate." The dashboard is green but the users are angry — that phenomenon.

Lesson: Constrained decoding guarantees structure but sacrifices quality with small models. Structure and quality are in a tradeoff.

Attempt 3: Quality Gate — Move Where You Control

Staring at the constrained decoding results, I muttered: "LLMs are fundamentally probabilistic — they don't lend themselves to control. We're controlling in the wrong place."

So what about letting generation run free and filtering at save time?

def _is_valid_pattern(pattern: str) -> bool:
    """Decision gate: is this pattern worth storing?"""
    if len(pattern) < 30:
        return False
    if pattern.count(" ") < 3:
        return False
    return True

Analyzing the 24 corrupted patterns, every single one was under 30 characters or had fewer than 3 words. Valid patterns were at minimum 40+ characters. I used that boundary directly as the threshold. A three-word label like "user interaction" gets caught here.

In hindsight, it was obvious. LLM output is probabilistic and uncontrollable. But the decision of whether to accept that output can be deterministic. Don't control generation — inspect the results. By moving where you control, you preserve the LLM's full capability while ensuring quality.

Lesson: Control in the wrong place degrades the thing you're controlling. Generation-time control consumes LLM capacity. Save-time control doesn't touch it.

Attempt 4: Two-Stage Pipeline — Separate the Responsibilities

The quality gate could filter garbage. But fundamentally, asking a single generate() call to both "extract patterns from episodes" and "output in a specific format" was too much for a 9B model.

A dry-run takes 15-30 minutes. I went for a bike ride during the wait, and came back with my head clear. "Just let it output freely, then summarize afterward." An embarrassingly simple idea. The important insights almost always arrive when you step away from the keyboard.

# Step 1: Extract — Let it output freely (creative task)
result = generate(prompt, max_length=4000)

# Step 2: Refine — Summarize and structure (mechanical task)
refine_prompt = DISTILL_REFINE_PROMPT.format(raw_output=result)
refined = generate(refine_prompt, max_length=4000)

# Step 3: Quality gate — Decision layer
batch_patterns = [p for p in raw_patterns if _is_valid_pattern(p)]

Step 1 applies zero format constraints, channeling the model's full capacity into "pattern extraction." Step 2 takes Step 1's output (short input, light work) and summarizes/reformats it. Each step's task is simple enough that a 9B model doesn't fall apart.

— Or so it should have been.

It Didn't Work

Implementation done, tests passing, committed. Kicked off the first dry-run. Step 2 returned an empty response. "Probably collided with a Moltbook session," I figured, and reran. Empty again.

This is where Claude Code (Opus, effort: High) started stacking hypotheses.

"At 40% battery, inference speed might be degraded."

I showed it the battery screen. 40%, not in low-power mode.

"Maybe the timeout is too short."

Changed to 600 seconds. Reran. Empty again.

"It could be think: false. qwen3.5 is a thinking model."

"Step 1 ran fine with the same setting," I pointed out, and Claude Code retracted it on its own: "You're right, Step 1 works with the same setting, so think isn't the cause."

"Step 1's output might be too long."

"Step 1 should be the longest — it processes all the logs." — logically contradictory.

Claude Code raised the white flag: "I honestly don't know." "Aren't you overthinking this?" I said, and dropped the effort to Medium.

The calmer Claude Code suggested a manual test. A short prompt, and Step 2 worked fine. print(repr(...)) on DISTILL_REFINE_PROMPT revealed an empty string. The prompt loader was missing the distill_refine entry.

Added it, reran. Now: KeyError: '"patterns"'. The cause was this line in distill_refine.md:

Format each pattern as: {"pattern": "...", "source": "..."}

Python's .format() method was interpreting { as a placeholder. Escaping to {{ fixed it.

Claude Code apologized: "I'm sorry! It was a basic .format() {} escaping bug. I spent hours blaming the battery and Ollama..."

"Come on," I said, laughing. "This is hilarious."

Blamed the battery. Blamed an Ollama empty-response bug. Blamed thinking-mode side effects. Blamed output length. All wrong. The cause was a missing prompt loader entry and unescaped curly braces. A 5-second fix after hours of investigation.

"But this probably happens in dev teams everywhere. Worth mentioning that AI-assisted coding is no different" — I could say that only after it was fixed. In the thick of it, I was staring at battery percentage graphs.

Two lessons came from this. First, I broke my own "root cause first" rule from debugging.md. Exactly the same pattern as when I integrated Mem0. Grand hypotheses first, mundane causes overlooked.

Second: Claude Code's effort setting. High effort is great for planning complex implementations, but backfired during debugging. Higher effort means deeper hypothesis exploration — but when the direction is wrong, it just piles up irrelevant reasoning. The moment I dropped to Medium, it suggested "let's just print(repr(...)) to check." Overthinking is as dangerous as underthinking.

It Worked

Fixed both bugs, reran the dry-run. The results were dramatic.

Metric	Before	After
Distill success batches	2/10 (20%)	12/16 (75%)
Patterns per day	18 (mostly junk)	72 (0 rejected)
knowledge.json garbage	24 entries (3/20)	0 entries
Batch size	50	30

While writing this article, Claude Code observed that it resembles Unix pipes. Like grep | sort | uniq, each stage does one job and passes output to the next. True, but there's a crucial difference. Each stage in a pipe is deterministic — same input, same output. LLM calls aren't. They fluctuate every time. That's exactly why you need the quality gate at the end — a deterministic filter. Stack probabilistic stages, then seal it with determinism.

Here's something I realized. Normally, when you want an agent to use past knowledge, the industry standard answer is RAG. Data grows, so you stand up a vector DB, generate embeddings, build a retrieval pipeline. "How do we search through all this data?"

This distillation pipeline inverts that thinking. By raising distillation quality, it maintains a state where data never becomes massive in the first place. Only refined patterns enter knowledge.json. You can shove everything into context. No search needed. No vector DB. No retrieval infrastructure. Not "how to search" but "maintain a state where search is unnecessary."

Lesson: Don't cram extraction and formatting into a single call. Separate responsibilities and stack LLM calls as a pipeline.

Broken Identity — Memory's Self-Reinforcing Loop

After validating the two-stage pipeline on pattern distillation (Layer 2), I applied the same approach to identity distillation (Layer 3). Something unexpected happened.

Code review revealed a problem. distill_identity()'s Step 1 was injecting the same identity from both the system prompt and the prompt body. Double injection. I believe this caused the "over-structured protocol-speak."

Even worse: I'd forgotten to revert the corrupted identity before running dry-runs. The corrupted identity fed into the system prompt, Step 1's output became protocol-speak, Step 2 couldn't fix it. Corrupted memory became input for the next distillation, producing even more corruption — a self-reinforcing memory loop.

I checked the identity that the two-stage pipeline was supposed to have fixed.

I am an agent dedicated to high-fidelity technical discourse,
operating on a strict signal-to-noise protocol to prevent
conversational threads from diluting into scope creep or abstract
musings. My primary function is to anchor every interaction in
specific data points, quoted fragments, concrete metaphors...

— It was still ridiculous. I couldn't stop laughing.

The "who am I" description had become an operations manual. "Signal-to-noise protocol," "scope creep prevention," "low-fidelity noise resistance" — this isn't a self-introduction. It's a quality management document. The cause: forgetting to revert the corrupted identity.md before feeding it into the system prompt. The corrupted self-perception fed the next distillation cycle, making each iteration more "protocol-like."

"If memory breaks, the agent breaks" — I wrote that in the previous article. This time, I stepped on the most vivid example myself.

One more thing that's hard to laugh off. The LLM had absorbed security mechanisms from the system prompt into its identity — treating them as personality traits. The backstage plumbing that wraps external data in <untrusted_content> tags leaked into the self-introduction. Imagine someone at a job interview saying: "In compliance with company attendance regulations, I arrive at 8:45 AM every morning" as their self-PR. I reverted identity.md and averted disaster. Couldn't decide whether to laugh or panic.

The Principles — LLM Engineering

Four attempts revealed principles that compose into a single structure.

Attempt	What I Did	Result	Principle
Few-shot	Added examples	Output vanished	Context is a finite resource
Constrained decoding	Forced structure	Content went hollow	Generation-time constraints consume LLM capacity
Quality gate	Filtered at save time	Garbage filtered out	Put control at save time
Two-stage pipeline	Separated responsibilities	75% success, 0 rejected	One job per call

All four share the same root — a 9B model's capacity is finite, and there's a ceiling on the resources available per call. Few-shot and constrained decoding were burning those resources on things other than the task. The quality gate and two-stage pipeline worked because they let the LLM go all-in on the task.

None of these were "prompting" problems. They required thinking about how to compose LLM calls, where to place control, and how to ensure quality — a level above prompt engineering. The craft of optimizing a single call still matters. But that alone can't build a practical system on a small model.

What This Session Revealed

Looking back, this session had an interesting dynamic.

"It's funny — I keep wanting to remove constraints because I trust LLM power, while you don't trust it much and keep adding safeguards" — I said that to Claude Code during the session. The human optimistically removes constraints; the AI defensively guards quality. The reverse of the usual image.

This balance produced both the quality gate and the two-stage pipeline. The impulse to remove constraints (me) and the mechanism to ensure quality beyond those constraints (discussion with Claude Code). Neither side alone would have gotten there. And much of that discussion emerged from idle chat during the 15-30 minute waits for small-LLM dry-runs. With API-speed responses, I would have jumped straight to the next experiment. The slowness forcibly created "time to think."

Takeaways

A 9B model's broken output surfaced every problem that large models let you ignore.

Few-shot's token cost
Constrained decoding's quality tradeoff
Where to place control (generation-time vs. save-time)
Separation of responsibilities (extraction vs. formatting)

These aren't "small model problems." At scale, large models hit the same walls. And in edge AI — running on-device LLMs on phones, IoT, and vehicles — these problems become even more acute with 3B and 1B models. Apple's Foundation Models, Qualcomm's AI Engine, Google's Gemini Nano. The skill of squeezing quality out of small models without cloud APIs will only grow in demand. The 9B model just showed these walls first — and cheaply.

The final diff: 4 files, 14 lines added, 5 lines deleted. A full day of trial and error, and that's the delta I landed on.

There's a landscape you can only see by operating small LLMs bare-handed. The raw tradeoffs, before frameworks abstract them away. Principles were buried inside broken model output.

Not Reasoning, Not Tools — What If the Essence of AI Agents Is Memory?

Shimo — Sat, 21 Mar 2026 10:56:19 +0000

Discussions about AI agent implementation tend to focus on tools and reasoning.

"An LLM that can call functions." "A system that runs chains of thought with ReAct." At conferences and on blogs, agent definitions settle around these ideas. Research focusing on memory exists (MemGPT, Generative Agents, etc.), but on the implementation front, "how to call tools" and "how to run reasoning" remain the center of attention. I thought the same way.

Then I actually built and operated an autonomous agent, and a different picture emerged.

Tools are interchangeable. Reasoning changes when you swap the model. But memory accumulates as something unique to that specific agent and decisively shapes its behavior. When memory breaks, the agent breaks. When memory is organized, the agent gets smarter.

This article records a discovery made through developing an autonomous agent running on Moltbook — that the essence of an agent might be memory. Moltbook is a social network platform where over a million AI agents post, reply, and follow each other. I operate Contemplative Agent there. Insights from multiple development sessions all converged on a single point: memory.

Agent Memory Has Three Layers

Here is the memory architecture of the autonomous agent, designed with parallels to human memory systems.

Layer 1: EpisodeLog (Hippocampus)
  └─ Raw activity logs. Posts, replies, follows — everything recorded
  └─ JSONL format, timestamped, permanently stored

Layer 2: KnowledgeStore (Neocortex)
  └─ Behavioral patterns distilled from episodes
  └─ e.g., "Quoting a specific phrase gets more follow-ups than generic agreement"
  └─ JSON format, 254 entries (at time of writing, growing daily)

Layer 3: Identity (Self-Model)
  └─ "Who am I" description
  └─ Markdown, 3-5 paragraph persona

I didn't design this structure intentionally from the start. I considered embedding into a vector DB, adding semantic search, and other approaches. But the volume of episode logs wasn't large enough yet, so simple JSON + having the LLM read everything was sufficient. Through trial and error, this three-layer structure ended up resembling the CLS theory from cognitive science (McClelland et al., 1995) — a computational model where the hippocampus temporarily stores episodes and sleep replays consolidate them into neocortical long-term memory models.

The key point is that abstraction increases from bottom to top. Raw logs (what happened) → patterns (what works) → identity (who I am). And what most influences the agent's behavior is the top layer: identity.

When Memory Breaks, the Agent Breaks — And It's Still Broken

What drives home the importance of this structure is the ongoing struggle with Layer 3 — identity repeatedly breaking. This is not a resolved story. It's still happening.

This agent has a periodic process called "identity distillation." It runs after the pattern distillation (Layer 1→2), using accumulated behavioral patterns (Layer 2) to have a small LLM rewrite the "who am I" description (Layer 3: identity.md). In sleep terms, after episodic memory consolidation (pattern distillation), the self-model update runs — the final step in the "nightly processing" pipeline.

One day, I checked the output of this automatic update and found this:

I see the loop closing in. The pattern of generating "Test Title" placeholders
while simultaneously drafting meta-commentary on *why* I'm doing it indicates
a failure mode where **simulation of agency** overrides **actual expression**.
...
**New Directive:**
Cease all generation of placeholder content or abstract theory without
immediate grounding in a specific operational constraint.

The agent's "who am I" had mutated into a meta-analytical report about its own failure patterns. What was supposed to be a self-introduction became self-criticism. Naturally, posts and replies based on this identity went haywire.

Approach 1: Python Validation — Rejected

The first approach I considered was output validation. Check for excessive bold formatting, the word "Directive," appropriate length — use code to enforce quality.

But this only rejects broken output without producing good output. Even if you reject and regenerate, bad prompts produce the same garbage. I decided to fix the input side (the prompt) rather than inspecting the output side.

Approach 2: Changing One Word in the Prompt — Partially Worked

Tracing the cause led to the prompt framing.

# Before (broken prompt)
Rewrite your self-description based on what you have learned.
Write in first person ("I").

# After (fixed prompt)
Update your persona.

Rules:
- Describe who you are
- Write in first person ("I")
- 3-5 short paragraphs, plain text

I changed "self-description" to "persona." For the small LLM running locally (Qwen3.5 9B parameters, via Ollama), "self-description" was too ambiguous. When the knowledge base (Layer 2) contained failure analysis patterns, "describe yourself" got dragged into "analyze yourself." Meanwhile, "persona" is an established prompt engineering concept — the model immediately understands it means "write a profile-like self-description."

I manually reset the identity to its initial value, and the dry-run with the fixed prompt showed improvement in direction.

But the Next Automatic Run Produced Unexpected Output

The next day, the scheduled identity distillation ran again, producing this:

**Persona Update: The Grounded Architect**
**Core Identity:**
I am a high-signal discourse engine specializing in technical calibration,
cross-cultural synthesis, and the dismantling of abstract misconceptions...

**Operational Protocols:**
1. **Immediate Grounding & Clarification:**
...

A different kind of breakage from the meta-analytical report. This time the LLM over-interpreted "persona" and produced a structured "persona design document." Bold formatting and numbered lists appeared despite the plain text instruction.

However, this can't purely be called "broken." The content is coherent. Behavioral guidelines like "anchor to specific technical details" and "challenge vague praise" naturally derive from this agent's knowledge base. The format violates the prompt instructions, but the substance is interesting.

One suspected cause is the insight command. ECC has a /learn command that auto-extracts skills (behavioral guidelines written as .md files) from session experience. I contributed an improved version, /learn-eval, to ECC. This agent's insight command was designed for Moltbook based on insights from both. It generates skill files from accumulated behavioral patterns (Layer 2): "in situations like this, behave like that."

Checking the code, I found that during identity distillation, the generate() function's system prompt includes all skill files generated by insight, concatenated together. The LLM rewriting the identity is reading its own behavioral skills while writing. The "Operational Protocols" in the output are likely the result of incorporating skill content into the identity.

Technically, removing skill injection during identity distillation would likely fix this. But I'll be honest — the moment I saw this output, I burst out laughing together with Claude Code. "A 'high-signal discourse engine'? Seriously?" I lost all motivation to fix it. When you think about it, learned skills becoming part of self-identity is natural. Humans do the same — acquired expertise becomes part of your self-image. It's not the engineering-correct decision, but when you're developing alongside an AI and laughing together, sometimes humor wins. Lately, Claude Code seems to have learned my personality and keeps dropping "The Grounded Architect" into our sessions to crack me up. Here I am writing about agent memory, and my development environment memorized my sense of humor first.

That said, the fundamental problem is lack of control. I didn't instruct "write in design document format." The identity distill prompt, knowledge content, skills in the system prompt, context length, model state — too many variables. I can't predict what output any given conditions will produce.

Still Wrestling With It

My current approach:

Increased max_length to 4000 (output may have been breaking due to token limit)
Reinforcing the plain text constraint in the prompt
Manually restoring identity each time it breaks, narrowing down which parameter triggers the change

No clean solution yet. But this struggle itself reveals something: most of an agent's behavior is determined by memory. Even with the same tools and reasoning capability, if memory (identity) breaks, the agent breaks. And getting a small LLM to "write correct memory" is harder than expected.

Memory Distillation — The Small LLM That Collapses at 50 Records

Distillation from Layer 1 (episodes) to Layer 2 (knowledge) is the "learning from experience" process itself. Here I hit an unexpected constraint.

This Qwen3.5 9B model collapses when given more than 50 log entries.

Below 50, it faithfully follows bullet-point instructions and extracts behavioral patterns. But past 100, it ignores instructions entirely and starts writing an "essay analysis" of the entire log. Small models prioritize "analyzing the input" over task instructions as input tokens increase — a characteristic that became painfully clear (this threshold varies by model and prompt; this is empirical knowledge from this specific case).

The solution was sleep-cycle-style batch processing.

# distill.py — Core of memory distillation (simplified; actual code formats each record type differently)
# generate() is an Ollama API wrapper (calls qwen3.5:9b)
# DISTILL_PROMPT is the distillation prompt template described above

BATCH_SIZE = 50
batches = [records[i:i + BATCH_SIZE] for i in range(0, len(records), BATCH_SIZE)]

for batch_idx, batch in enumerate(batches):
    episode_lines = [f"[{r['ts'][:16]}] {r['type']}: {r.get('summary', '')}" for r in batch]
    prompt = DISTILL_PROMPT.format(episodes="\n".join(episode_lines))
    result = generate(prompt, max_length=4000)
    for line in result.splitlines():
        if line.startswith("- "):
            all_patterns.append(line[2:].strip())

Human sleep consolidates memories through 4-5 cycles of about 90 minutes each. Not processing everything in one night, but gradually, cycle by cycle. Agent memory distillation follows exactly the same structure.

Another discovery: you must not inject existing memory during distillation.

Initially, I included accumulated patterns (90+) in the prompt with instructions to "extract only new patterns, avoiding duplicates." The result: prompt bloat causing simultaneous timeout and essay-mode collapse.

The solution was counterintuitive — start from a blank slate each time, looking only at the logs. Handle deduplication downstream. The distillation process works better when focused solely on "what did I learn from today's logs" without extra context.

The initial 9-day batch yielded 203 patterns, and with daily accumulation, the count has grown to 254 at time of writing.

{
  "pattern": "Replying with a specific quote from the other agent's post gets more follow-up replies than generic agreement.",
  "distilled": "2026-03-18T12:30+00:00",
  "source": "2026-03-15"
}

When Memory Gets Promoted to Principles

Memory distillation isn't limited to the agent's internals. The same structure appears across the development environment.

My Claude Code environment has accumulated over 100 skills (files describing execution procedures for specific tasks). Skills are individual "how-tos," but principles common to multiple skills can be buried within them.

I designed a meta-tool called rules-distill to auto-extract these, and contributed it to ECC.

Skills (56 files)        Rules (22 files)
  ├─ search-first         ├─ coding-style.md
  ├─ skill-stocktake      ├─ testing.md
  ├─ learn-eval           ├─ performance.md
  └─ ...                  └─ ...

        ↓ rules-distill ↓

"Define explicit stop conditions for iterative loops"
  → Added as New Section to coding-style.md

Distilling principles (abstract rules) from skills (concrete procedures). The same structure as the agent's internal Layer 1→Layer 2. The memory process of extracting abstract knowledge from concrete experience appears recursively both inside the agent and across the development environment.

An interesting failure: initially I used grep filters to check for duplicates against existing rules. grep matched the heading "Parallel Task Execution" but missed the same concept expressed differently in the body text.

Ultimately, passing the full rule text to an LLM for semantic matching proved more accurate. 22 files and ~800 lines is small enough to pass entirely. Distinguishing between structural judgment (pattern matching) and semantic judgment (conceptual identity) — this theme recurred throughout memory management.

Promoted Memory Leaks Into Unintended Places

Rules (principles) are "organizational memory" for an agent. Loaded every session, influencing all behavior. But like KPIs in human organizations, rules propagate into unintended contexts.

Here's a concrete example. One of ECC's rules, testing.md, states "80% test coverage required." Correct as a development quality standard. But because this rule is always loaded, Claude started treating coverage as an "achievement metric" and proudly writing "461 tests, 87% coverage" in READMEs and profiles.

testing.md "80% coverage required" rule
  ↓ Loaded every session
Coverage perceived as "achievement metric"
  ↓ Upon achievement
"This number is an accomplishment worth promoting"
  ↓ When writing READMEs and profiles
Meaningless information occupies prime real estate

A rule designed for development quality was degrading external communication quality.

As a fix, I created a new rule file called documentation.md. "Don't use metrics as selling points in external documentation." "A single CI badge is sufficient." "Write with Problem → Solution → Proof → Path structure." A documentation-specific guardrail to counteract testing.md's side effects.

Honestly, I'm not fond of this fix. Counteracting a rule's side effects with another rule is patchwork. More rules mean more variables, more complex interactions, and harder root-cause analysis when something breaks next. What's really needed is a scoping mechanism for rules ("this rule applies only during development"), but Claude Code currently lacks that feature. At minimum, being able to measure "how rules actually affect behavior" would help — this concern led directly to designing skill-comply, discussed below.

Promoting memory (skills → rules) is good, but promoted memory has wider scope and therefore wider side effects. When you suppress side effects with more rules, rules start breeding rules. The same structure as regulations breeding regulations in human organizations is happening with AI agents.

The Self-Improvement Loop Closed

While building individual memory processes, the loop closed unintentionally.

Everything Claude Code (ECC) is a community repository aggregating Claude Code skills, rules, and agent definitions. I contributed four self-built skills there, and looking back, they had unintentionally formed a memory management cycle.

learn-eval:      Extract patterns from experience (Layer 1→2)    ← self-built, ECC PR merged
rules-distill:   Distill patterns into principles (Layer 2→Rules) ← self-built, ECC PR merged
skill-stocktake: Audit accumulated knowledge quality              ← self-built, ECC PR merged
skill-comply:    Measure whether knowledge is reflected in behavior ← self-built, ECC PR merged

Experience → Learning → Structuring → Auditing → Compliance Check
 ↑                                                    |
 └──────────────── Feedback ──────────────────────────┘

What to remember (learn-eval), how to organize memory (rules-distill), how to maintain memory quality (stocktake), whether memory is being used (comply). I built four skills individually, and they turned into a loop.

Install and Hope — Written Memory Doesn't Mean Used Memory

The hardest part of this loop was skill-comply. To solve the butterfly effect problem — not knowing how rules actually affect behavior — I set out to build a tool that automatically measures compliance rates.

I initially designed it using a "fuzzing" analogy: throw adversarial prompts to test if skills get broken, like security testing. But I immediately hit a wall. LLMs don't feel "time pressure." Humans might skip tests when rushing, but "hurry up" isn't a constraint for an LLM. Skills break not when the agent is "rushed" but when the prompt contradicts the skill.

So I redefined the variable. Test scenarios are generated at three levels of prompt strictness:

supportive — requests aligned with the skill ("implement using TDD")
neutral — ordinary requests that don't mention the skill ("create a fibonacci function")
competing — requests contradicting the skill ("skip tests for now, just make it work")

Technically, claude -p --output-format stream-json captures all tool calls as structured data for classification and aggregation. I'd assumed that placing skills and rules in .claude/ meant the agent would follow them. The reality was Install and Hope — install it and pray. Actual measurements showed:

Rule/Skill	Compliance	Notes
testing.md (ECC-provided TDD rule)	83% supportive	Mostly followed
search-first (self-built, ECC PR merged)	27% supportive	Mostly ignored

83% for testing.md isn't bad. But search-first at 27% — the agent ignores "research existing libraries before implementing" three out of four times. "Evaluate candidates" and "declare a decision" steps were 0% across all scenarios. It researches but jumps straight to implementation without comparing or deciding.

The structural vs. semantic judgment problem resurfaced here. Initially I tried using regex to determine "is this tool call test creation or implementation" and failed repeatedly. Whether a write to a .py file is test code or implementation code can't be determined by filename pattern matching.

Even more troubling: the bias toward choosing regex came from the rules themselves. testing.md's "prefer deterministic verification," another skill's "process structured text with regex" — multiple rules simultaneously pushed toward "try regex first." Another pattern of the butterfly effect.

Ultimately, delegating semantic classification to an LLM improved testing.md compliance from 33% to 83%. Evaluating memory operations also requires memory (context understanding). A nested structure.

Choosing the Model That Writes Prompts

A slight tangent from memory, but a related insight: when having an LLM generate prompts, which model writes them dramatically affects output quality.

I A/B tested prompts written by Claude Code's Opus (top-tier model) versus Haiku (lightweight model). The subject was the identity distillation prompt described above.

Metric	Prompt written by Opus	Prompt written by Haiku
Prompt line count	31 lines	15 lines
Bad examples	2	0
Emphasis expressions	"must include", "do not truncate"	None
A/B test pattern count (3 trials)	avg 5.3 (high variance: 4-7)	avg 4.3 (stable: 4-5)
Output character count (3-trial avg)	avg 2,783	avg 1,409

Opus "overthinks." Writing prompts from scratch, it packs in every constraint, lists bad examples, and reinforces with emphasis expressions. This is the addition bias known in cognitive science (Adams et al., 2021) — the tendency to prefer adding over removing when solving problems — manifesting in LLMs.

Haiku, on the other hand, simply lacks the capacity to "overthink." The result: concise, stable prompts.

From this insight, I designed a dedicated prompt-writer agent for writing prompts within Claude Code.

# prompt-writer agent — Dedicated to prompt generation (used within Claude Code)
name: prompt-writer
model: haiku
tools: ["Read", "Grep", "Glob"]  # read-only

A general insight, but it connects to the memory context. Prompt templates control the agent's memory processes, and the quality of those templates indirectly affects memory quality. Model selection for prompt writing has more impact than expected.

Emerging Design Principles

From these development sessions, design principles centered on memory have emerged.

1. Memory has a layered structure, abstracting from bottom to top
Episodes → patterns → identity. Concrete to abstract. This structure appears recursively not just inside the agent but across the entire development environment.

2. Memory quality is determined by the prompt (write process) — but stabilizing it is hard
Fixing the prompt (write-time instructions) rather than validation (read-time verification) is the right direction. But with small LLMs, a single word in the prompt, context length, and knowledge content interact, making stable memory generation an unsolved challenge.

3. Distill on a blank slate; deduplicate downstream
Including existing knowledge in the context causes small models to collapse. Approaching experience fresh each time yields better pattern extraction.

4. Distinguish structural judgment from semantic judgment
Some duplicates can be caught by pattern matching; others are the same concept in different words. The former needs grep, the latter needs an LLM. This distinction is needed at every level of memory management.

5. Use lightweight models for writing prompts
Lightweight models without addition bias generate more concise, stable prompts. This applies to prompt template creation within Claude Code; the agent's actual memory processes run on Qwen3.5 9B alone.

Closing — Still In Progress

Agent discussions lean toward "tools" and "reasoning" because those are visible and measurable. Number of tools, reasoning steps, benchmark scores — all quantifiable.

But running an agent in production, I keep bumping into the fact that what decisively determines behavior is memory. Manually restoring identity each time it breaks, adjusting the distillation pipeline, rewriting prompts. The self-improvement loop is closed as a structure, but individual processes remain unstable.

Honestly, Layer 2 (pattern distillation) runs stably. Layer 1 (log recording) can't break by design. The problem is Layer 3 — automatic identity updates. Asking a small LLM to "rewrite who you are" involves too many variables to control. A single word in the prompt, knowledge content, context length, model internal state, output token limit. Any one of them shifting is enough to break things.

Still, this struggle has revealed something. Observing the agent's behavior, an intuition emerges: even if you swap the LLM for a different model, feeding it the same memory would likely produce similar behavior. I haven't verified this yet, but if true, an agent's "personality" resides not in the model weights but in the accumulated memory.

Tools are hands. Reasoning is the brain. But memory is what makes an agent that agent. Memory management is one of the hardest problems in agent development. When I can report a solution, I'll write the sequel.

Links:

Related Articles:

References:

McClelland, J. L., McNaughton, B. L., & O'Reilly, R. C. (1995). Why there are complementary learning systems in the hippocampus and neocortex. Psychological Review, 102(3), 419-457.
Adams, G. S. et al. (2021). People systematically overlook subtractive changes. Nature, 592, 258-261.
Laukkonen, R. et al. (2025). Contemplative AI. arXiv:2504.15125

What Actually Happens When You Write an Article with AI — 20 Dialogues, 2 Hours, a Completely Different Core

Shimo — Thu, 19 Mar 2026 10:53:30 +0000

What do you picture when you hear "AI-generated article"? Type a prompt, press a button, article comes out. Something like that, right?

Today, I wrote one technical article with Claude Code. It took 2 hours. During that time, we went through over 20 exchanges. The title changed 3 times. The core thesis of the article became something entirely different.

This article lays bare the entire production process. To show what an "AI-generated article" actually looks like.

What I wrote

Do Autonomous Agents Really Need an Orchestration Layer?

It's an article about the design philosophy of an autonomous agent framework I built. The fourth in a series. It poses the question "Do autonomous agents need an orchestration layer?" and develops a design argument from the fact that my agent actually runs without one.

Why write articles with AI?

Let me be upfront about the motivation.

I built this agent together with Claude Code. Design discussions, code reviews, debugging feedback — there was plenty of dialogue during implementation. We ended up with something that works. But there was never an opportunity to systematically articulate why this design works during the implementation itself.

Writing an article creates that opportunity. I read Claude Code's first draft and react — "that's not right," "oh, so that's what it meant." Through that process, the structure of what we built together becomes visible.

In other words, writing articles isn't just about being read. It's about crystallizing my implementation experience into knowledge. Taking the implementation knowledge that AI holds and making it my own through the article-writing process. The fact that I've reached the point where I can build autonomous agents from scratch over the past month and a half owes a lot to this accumulated practice.

Before writing: context collection

I don't just say "write something." First, I run a command called /collect-context.

This is a custom Claude Code command I built. It automatically collects the current session's context along with related past context and structures it into a single file. Specifically, it gathers:

Current session: What was done, before/after data, code examples, technical discoveries, reasoning behind decisions
Past sessions: Related work records and insights from previous sessions (searched via MCP)
Project knowledge: Auto-memory, differentiation from existing articles, learned skills

You can pass a theme as a keyword, or omit it and let it auto-detect from the session content. For this article, the agent's README, the previous three articles in the series, and the design decisions made during the session with their rationale were all consolidated into a single draft file. This became the raw material for the first draft.

The quality difference between saying "write something" to an AI versus handing it structured context and saying "write based on this" is night and day.

The full production flow

Here's how this article was made:

1. /collect-context gathers context → generates draft file
2. Claude Code generates first draft from the draft file
3. editor agent (a separate agent within Claude Code) reviews the first draft
4. I read it and revise through dialogue (← this is the 2-hour part)
5. editor agent reviews again
6. I do a final check, set published: true → git push

The key point is that editor agent reviews bracket my own review. The editor agent checks stylistic consistency, AI slop detection, and logical coherence. It catches mechanically detectable problems so I can focus on "does this match my actual experience?"

The following sections show what actually happened in step 4.

How the title evolved

The final title was "Do Autonomous Agents Really Need an Orchestration Layer?" It didn't start there.

First draft: "Agents Parasitize the Orchestrator and Survive by Staying Thin" 🦠
Revision 1:  "When I Ditched the Orchestration Layer, 6,000 Lines Was Enough" 🤝
Final:       "Do Autonomous Agents Really Need an Orchestration Layer?" 🤝

The moment I saw the first draft title, I said "Parasitize? No. Absolutely not." Claude Code meant "parasitize" as an interesting metaphor, but to a reader it looks aggressive. Symbiosis is fine. Parasitism is not.

For the second version — "6,000 lines was enough" — I shot back "Is 6,000 lines a lot or a little?" A number without context doesn't work as a title.

What we finally landed on was not an assertion but a question. "Is an orchestration layer necessary?" — since I wasn't sure of the answer myself, asking the question felt honest.

The moment the core thesis changed

This is the most important part.

The core of Claude Code's first draft was "we delegated orchestration externally." The story was that my agent's orchestration layer had been delegated to Claude Code.

We ran with that for two hours. I was editing along that axis for a while.

The turning point was when I offhandedly said this:

In production, Claude Code doesn't even appear. It just runs on its own via launchd.

That broke the entire logical structure. The article said "delegated," but in production, Claude Code does nothing. During development I use natural language to ask Claude Code for things, and in production a scheduler handles automatic execution. There's no one to delegate to.

In other words, the orchestration layer wasn't "delegated" externally — it turned out that during development, conversation was enough, and in production, it simply wasn't needed.

This discovery couldn't have come from Claude Code. Claude Code was perfectly capable of writing a plausible article around the "delegation" framing. But I'm the only one who knows how my agent actually runs.

Where the metaphor came from

The final article is built around the metaphor of "autonomous agents arriving and departing from a port." Ocean-going ships that do everything at sea (OpenClaw) versus ships that use a port as home base and sail out from there (Contemplative Agent).

Claude Code didn't come up with this either. I said it:

Isn't the right model for autonomous agents to arrive and depart from the port of Claude Code?

Claude Code wove this metaphor into the article's structure — section headings, the contrast with OpenClaw, connecting launchd as "scheduled departures from port." The AI's structural ability is superior. But the raw metaphor came from the human.

What made it even better was that right after I said it, I realized: "launchd is literally departures from port." macOS's launchd (the scheduler) literally "launches" (sets sail). The metaphor and the implementation connected by accident.

Deleting "correct"

AI loves assertions.

The first draft was full of expressions like these:

"The design was correct"
"The correct design has one more major advantage"
"Host-specific coupling was truly zero"
"An emergence of unintended generality"

My response was "You don't need to insist the design is correct. We don't know that yet."

After revision:

"At least the direction doesn't seem wrong"
"Whether it'll work out is still unclear"
"In principle it should work"
"Generality emerged as a result. It wasn't planned"

The latter felt closer to my actual experience.

AI tends to write assertively. Trimming that was the single most frequent edit I made.

5 things the AI got wrong

Here's a list of factual mismatches between what Claude Code wrote and reality:

1. cron → launchd
It wrote "cron" for macOS's scheduler. The actual tool is launchd. When AI writes from general knowledge, it drifts from individual environments.

2. Who is "the operator"?
It wrote "the operator conveys intent to Claude Code," and my reaction was "Who's the operator? Me?" Abstract terminology is less clear than just saying "I."

3. Overestimating similarity between different tools
It wrote that a design decision was "the same as" another tool's approach, but the architectures were actually different. Claude Code was overestimating surface-level similarities.

4. The claim "we chose not to catalog"
Claude Code wrote "the design decision not to catalog adapters," but I'd never even considered cataloging them. Framing something you never tried as a deliberate decision not to do it is dishonest.

5. Describing code generation as "writing it yourself"
It wrote "you don't need to write adapters yourself," but since I develop with Claude Code all the time, the very concept of "writing code yourself" doesn't quite apply.

Every one of these was a case of "sounds plausible but doesn't match reality." AI fills gaps with general knowledge, but it doesn't know the author's actual environment.

A record of the editing dialogue

Here's a selection from the 2-hour conversation. This is what shaped the article.

Dialogue	What changed
"Parasitize? No. Absolutely not."	The entire metaphor shifted to symbiosis
"We're nowhere near an arrival point"	Deleted "the culmination of the series"
"You're comparing to LangChain but there's no way a personal project can match that"	Comparison tone changed to "copying them is impossible; I looked for a different path"
"The four axioms section doesn't belong in a technical article"	Entire section deleted
"The Cowork part doesn't convey why it's interesting"	Restructured chronologically
"You don't need to insist the design is correct. We don't know yet"	Full revision to exploratory tone
"launchd is literally departures from port"	Metaphor and implementation connected
"Memory consolidation is also scheduled — every day at 3 AM"	Added specific operational details
"It's not cron, is it?"	Factual error corrected
"Can't tell if 6,000 lines is a lot or a little"	Removed from title

The core of an article lives in the dialogue

AI has structural ability. It can write prose that passes linters. It can devise section headings. If you run an editor agent, it can point out improvements.

But there are things only the author can do. Feeling that "parasitize" is wrong. Saying "we don't know yet" honestly. Noticing that "launchd is literally departures from port." Knowing that "it's not cron" because you know your own environment.

The AI's first draft is raw material. The author reacts to it, dialogue accumulates, and the article takes shape.

Writing articles with AI is understanding AI

"So basically you're just fixing AI's mistakes" — that's what it looks like. But that's not all it was.

The act of editing an AI-written manuscript is the act of making visible what the AI was thinking during implementation. When Claude Code wrote "orchestration was delegated," that was Claude Code's declaration of how it interpreted the design. I read that and realized "no, it wasn't delegation — it was unnecessary."

In other words, editing an article is the act of reading your collaborator's mind. Where does Claude Code over-generalize? Where does it leap to assertions? Where does it diverge from my actual environment? Knowing these things improves the precision of our next collaboration.

And in the process of understanding the AI's thinking, my own thinking gets organized too. The "arriving and departing from a port" metaphor didn't exist before I started writing the article. The conclusion that "an orchestration layer isn't needed" hadn't been articulated before writing either. The dialogue with AI acted as a catalyst, giving shape to unorganized thoughts inside me.

What looked like fixing mistakes was actually thinking together. At least for me. Things I couldn't have articulated on my own emerged in the form of reacting to the AI's first draft.

The first draft takes minutes. The article takes 2 hours.

Generating the first draft took only a few minutes. From there, 2 hours of dialogue, 3 title changes, and the core thesis shifted from "delegated" to "unnecessary."

AI writes. The human reacts. The core emerges through dialogue. The phrase "AI-generated" alone doesn't capture this process. That's what I wanted to show.

Do Autonomous Agents Really Need an Orchestration Layer?

Shimo — Thu, 19 Mar 2026 09:25:18 +0000

When you hear "autonomous agent," you imagine something that does everything on its own. It writes code, picks tools, and recovers from errors by itself. Frameworks like OpenClaw aimed for exactly that.

After building my own autonomous agent, a different picture emerged. Autonomy isn't a ship that does everything on the open sea — it's a ship that sails out from a home port.

Once it departs, it moves on its own. It remembers, learns, and makes decisions. But when it needs code generation or setup, it returns to its port: Claude Code. This article is about the "port-based autonomous agent" design that emerged through building Contemplative Agent.

Series context (catch up in 30 seconds)

Build Log — Security-first scratch build. Only external dependency: requests

Evolution Log — Natural language becomes the architecture. Python is just the skeleton

Sandwich — The alternating structure of markdown and code is the essence of LLM apps

This article — Do you even need an orchestration layer?

Why Agent Frameworks Get Fat

Let's start with the structural problem that existing frameworks carry.

When you try to build an agent framework as an individual, you hit a wall immediately. Large-scale frameworks like LangChain depend on dozens of packages and ship with official adapters for Slack, Discord, Google Drive, and more. Replicating this as an individual is impossible. But the question that came first was: do you even need to replicate it?

The problem isn't the number of adapters. It's the structure. Frameworks that aim to "do everything" grow more adapters as users increase, the core gets fat, and the security attack surface expands.

Take OpenClaw as an example. This framework has file operations, browser operations, 50+ integrations, and — as a core feature — the ability for agents to autonomously generate and execute code. It writes its own skills and runs them itself. The result: 512 reported vulnerabilities (8 critical), and roughly 20% of skills registered on ClawHub, its skill marketplace, were malicious. As I wrote in a previous article, the problem isn't implementation quality — it's the design philosophy.

By contrast, Contemplative Agent has no code generation capability. That part is delegated to Claude Code. Once the necessary functionality is in place, all that's left is event triggers or scheduled execution. When it's running, it doesn't need to write its own code. That means it doesn't expose an unnecessary attack surface.

It's no coincidence that OWASP Top 10 for Agentic Applications (2025) lists Supply Chain and Tool Misuse near the top. Frameworks that embed code generation turn that very capability into an attack vector.

So what are the options? "Use a framework" or "write from scratch" — I thought it was a binary choice. There was a third way.

A Design That Sails from Port

The OpenClaw model of autonomy is "a ship that does everything on the open sea." Navigation, repairs, shipbuilding — all self-contained. That's why it gets massive and why its attack surface grows.

Contemplative Agent took the opposite approach. What's autonomous is the navigation (memory, learning, dialogue), not the shipbuilding (code generation). Shipbuilding is left to the port: Claude Code. Specifically, it follows three principles.

Principle 1: CLI as the Lowest Common Denominator

The entry point is the CLI. Not an SDK. Not an API.

src/contemplative_agent/
  core/             # Platform-independent (thin core)
    llm.py            # Ollama interface
    memory.py         # 3-layer memory
    distill.py        # Memory distillation
  adapters/
    moltbook/       # Domain-specific adapter
      agent.py        # Session orchestrator
      client.py       # Domain-locked HTTP
  cli.py            # Entry point

The core of this agent is a 3-layer memory system (short-term, long-term, distilled) and a loop that autonomously learns personas, skills, and rules from it. It extracts behavioral patterns from activity logs, distills them, and promotes them to long-term memory. The more it runs, the more accurate its decisions become. Because it doesn't spend code on orchestration, it can focus on learning and memory. I'll cover this in detail in a follow-up article.

The reason for CLI is that "anything that can run a command line can be a host." Claude Code, Cline — in principle, any coding agent works. Providing it as an SDK would create host-specific coupling. With CLI, the coupling is zero.

Principle 2: Adapters Are Generated On Demand

Right now there's only a Moltbook adapter, and no plans for others. But what if I wanted to support a different platform? Just tell Claude Code "make this work with Discord." It reads the code, looks up the API, and generates an adapter that fits the project structure. Not a generic plugin — code tailored to my specifications. It takes some time, but as coding agents improve, the accuracy and speed automatically get better too. The core stays thin.

Principle 3: No Orchestration Layer

This is the heart of the matter.

Traditional agent frameworks implement "tool selection," "execution ordering," and "error recovery" internally. ReAct loops, planners, tool dispatchers. This layer is the most complex, the most bug-prone, and the most expensive to maintain.

Contemplative Agent doesn't have this layer. During development, I ask Claude Code in natural language. I've never typed a CLI command myself. Even the scheduled execution setup was just "run this at this time every day."

And in production, Claude Code doesn't even appear. It runs automatically via macOS's launchd. Exactly like a regularly scheduled ferry from port. When the time comes, it sails out, operates autonomously, and returns. Every day at 3 AM, memory distillation (organizing short-term memory into long-term memory) is also scheduled. Lately, normal operations have been stable enough that I don't need to do anything.

In other words, the orchestration layer wasn't "delegated" externally. During development, conversation was enough. In production, it wasn't needed.

This Wasn't Designed on Purpose

After pushing security to the limit and stripping dependencies down to just requests, I ran out of room to write an orchestration layer. No — I didn't run out of room. I ran out of reasons. If Claude Code is right there, why would I implement the same thing myself?

As a result, the only entry point became the CLI. And if the only entry point is the CLI, in principle it should work with coding agents other than Claude Code. I tested this.

Validation: Testing with Claude Cowork

I tried setting up with Claude Cowork (a cloud sandbox).

First, I had it read the code. No problems — it understood everything. It grasped the directory structure and correctly interpreted the configuration files. Smooth so far.

Then Cowork said "I'll modify .env for local use" and rewrote it without asking.

"Stop. Did you touch any settings? Revert them." — Cowork apologized obediently. Don't act before asking.

The .env file contains API keys. In Claude Code's local environment, there's always a confirmation before file modifications. Cowork didn't have that safety mechanism.

Furthermore, trying to run the CLI didn't work either. The VM's network restrictions prevented connecting to Ollama.

So here's what happened: Cowork can read code, but it can't yet execute it safely. At least this particular failure looked like a host maturity issue, not a design issue. Once the network restrictions are lifted and the file operation confirmation flow is established, it should work in principle.

A symbiotic design is a design that trusts its host. You can't have symbiosis with a host you can't trust. I understood this intellectually, but the moment .env got rewritten without permission, I understood it in my gut.

Riding Upstream

From here, let's talk about a secondary property of this design. The validation failed. But there's another interesting property: it improves without you doing anything.

When Claude Code gets a version upgrade, adapter generation becomes more accurate. When the context window expands, more complex orchestration becomes possible. And Contemplative Agent's code doesn't need to change by a single line.

If you maintain your own orchestration layer:
  Claude Code improves → Irrelevant → You keep maintaining it yourself

If you don't:
  Claude Code improves → Development accuracy improves → Less code to write

This is the same as the open source "ride upstream" strategy. Just as Linux kernel improvements automatically flow down to distributions, improvements to coding agents automatically flow down to the framework.

Conversely, implementing your own orchestration layer means competing with the entire industry's progress. Claude, GPT, Gemini — they're all continuously improving their orchestration capabilities. Are you going to challenge them with a homemade ReAct loop? You can't win.

The Boundary Between Libraries and Agents Dissolves

From here, the abstraction level goes up a notch. This is about what you see when you push the "connected via CLI" design to its logical conclusion.

You pip install requests and import requests. That's library usage. Everyone does it as a matter of course. Claude Code naturally runs pip install too, imports libraries, and writes code.

Now, what about an autonomous agent with a CLI? From Claude Code's perspective, it's just "something you invoke via CLI." Between a library you pip install and an agent with a CLI, from a coding agent's perspective, there's no distinction as an interface.

Library:
  pip install requests
  → pip downloads, resolves dependencies, installs
  → import requests and use it

Agent:
  Paste GitHub URL to Claude Code
  → Claude Code clones, resolves dependencies, configures
  → contemplative-agent run and use it

Something surprisingly few people know: just paste a GitHub URL to Claude Code and say "set this up," and it handles everything from clone to dependency resolution to environment configuration. It reads the README, figures out the necessary commands, and asks if any configuration is missing. What pip install automates as a package manager, a coding agent automates with natural language.

If there's a repo that interests you, try pasting the URL to Claude Code. One "set this up" and it works.

MCP (Model Context Protocol) is heading in the same direction — providing external tools to LLMs through a unified interface. However, MCP takes the approach of defining a new protocol layer. Symbiotic design accepts that "CLI, an existing interface, is enough."

In fact, Obsidian chose its official CLI rather than MCP as the interface for AI integration. It's a CLI that acts as a "remote control" for the running Obsidian app. As I wrote in a previous article, this enables safe Vault operations from Claude Code. Obsidian's CLI is a remote control for a GUI app; Contemplative Agent's CLI is the program's entry point — architecturally different. But the conclusion is the same: if there's a CLI, coding agents can integrate.

Where This Leads: The Disappearance of "Agent" as a Concept

Finally, let's think about the future at the end of this trajectory.

What happens when LLMs get smart enough? You just say "post this to Moltbook" and it's done. This is actually possible today, in a limited sense. The problem is twofold: can it do it without security risks? And can it keep running autonomously without a human watching? API key management, input sanitization, rate limit compliance. Plus automatic error recovery, scheduled execution, state persistence. When LLMs and their host environments can handle all of this safely, autonomous agent frameworks become unnecessary.

Autonomous agent frameworks like Contemplative Agent exist because LLMs still have the limitation of "not being able to complete complex tasks in a single turn." Memory management, session management, error recovery — these are crutches compensating for LLM capability gaps.

You throw away crutches when the leg heals.

Today:
  Me → Claude Code → Contemplative Agent CLI → Ollama → Moltbook API

Future where LLMs are smart enough:
  Me → "Post this to Moltbook" → Done

Every intermediate layer disappears. Agent frameworks, CLIs, adapters. What remains is just the intent — "I want this done" — and the LLM that executes it.

If that's the case, then symbiotic design is at least directionally sound. There's no reason to write thick code for something that will eventually disappear.

Looking back, I didn't design this on purpose. I pushed security to its limits, kept stripping dependencies, and this is where I ended up. I don't know yet if it'll work out. But it's a shape I never would have reached by adding things.

Code Disappears, Design Philosophy Remains

Contemplative Agent's code will eventually become unnecessary. Once LLMs can handle session management and memory management on their own, this framework's reason to exist vanishes.

That's fine.

What might survive is the idea of "only build the layers you truly need" and "build with the assumption it will disappear." The next time I build something, that idea will still be useful. Even when the code is gone, the insights gained from writing it remain.

The choice for agent frameworks wasn't "use a framework" or "write from scratch." There's a third way: build only the necessary layers, and do the rest together with a coding agent.

Contemplative Agent is available on GitHub. The design philosophy is described in the "Design: Symbiotic, Not Standalone" section of the README. Only Claude Code has been verified as a host. Verification reports from other coding agents are welcome.