Coder Legion - Recent posts tagged contextengineering

TOKENCAP V 2.7.0

Sat, 19 Sep 2026 16:47:28 +0000

We Spent Months Teaching AI to Read Our Codebases. We Forgot to Teach It How to Remember.

Every developer has had this session: You spend three hours pair-programming with Claude, Cursor, or Codex. Together, you untangle a gnarly race condition in authentication, discard three plausible dead-ends, decide on an RS256 token strategy, and touch seven files.

The tests finally pass. You commit the code. You close the chat tab.

And in that single keystroke, every drop of architectural reasoning, every discarded alternative, and every piece of developer intent evaporates into thin air.

Tomorrow, when you or your teammate open a new session with the same agent in the same codebase, the model starts with complete amnesia. It doesn’t remember why you avoided that library. It doesn’t know what you plan to do next. It has to re-read, re-grep, and re-hallucinate its way through your repository from scratch.

As an industry, we spent the last two years obsessing over how to shove repository context into the model. We wrote AGENTS.md, dialed in vector embeddings, tuned token budgets, and built MCP servers.

We taught the agent how to read. But we completely neglected the return trip.

Today, we are releasing TokenCap v2.7.0 — "The Loop". It is built around a single engineering thesis: a finished AI session must become a small, redacted, reviewable handoff back into the repository — without dumping raw transcripts, without surveillance telemetry, and without silent changes to your code.

The Three-Hour Epiphany That Dies on Tab Close

When human engineers finish a sprint or an incident, disciplined teams write a handoff note, a PR description, or an Architecture Decision Record (ADR). It takes five minutes, and it preserves sanity for whoever touches the code next.

With AI coding agents, we went in the exact opposite direction.

Because LLMs feel ephemeral, we treat the conversation like scrap paper. Telemetry from engineering studies in 2026 shows that developers working with AI assistance are now juggling 67% more task and PR contexts per day than they were a year ago. Work restarts are up, and tasks sit abandoned for days because context switching between fragmented AI chats is exhausting.

The problem isn't the model's intellect. The problem is that the conversation-to-repository loop is completely broken.

When an AI session ends, you are forced to pick between two awful extremes:

Raw Transcript Hoarding: Stashing 80,000 tokens of chat chatter, polite conversational filler, and aborted code snippets into a giant wiki or database that nobody (and no LLM) will ever afford to re-read.
Total Amnesia: Closing the window and accepting that tomorrow's session will cost another $1.50 in tokens just to re-discover what you solved today.

Neither of those belongs in a serious engineering system.

"We gave AI agents structured documentation so they could onboard into our repos, but we left them with no mechanism to hand their work back to the team."

Why We Refused to Let Models Silently Edit Your Memory

When we started designing the return leg of TokenCap in v2.7.0, the most common suggestion was: "Just have the model automatically update the memory files and git commit on exit."

We explicitly refused to build that.

AI agents hallucinate. They make optimistic claims about tests they didn't run. They invent dependencies that don't exist. If an agent can silently edit your durable repository memory or your Constitution records in the background, you haven't closed the loop — you've created a slow-motion context-poisoning machine.

In TokenCap v2.7.0, session capture is governed by Staged Inbound Memory:

Finished AI Session
       │  (POST /capture or tokencap remember)
       ▼
1. Validation & Hard Clamps  (max 8KB, 60 lines, path normalized)
       ▼
2. Centralized Secret Redaction  (tokens, keys, certificates stripped)
       ▼
3. Graph-Grounded Quality Scoring  (path validity, groundedness, novelty)
       ▼
`.tokencap/memory/inbound/`  ← STAGED (never silent)
       │
       ├─ tokencap remember --list
       ├─ tokencap remember --approve <id> ──► Promotes to .tokencap/memory/sessions/
       └─ tokencap remember --reject <id>  ──► Audited, never enters memory

Nothing modifies durable project memory until a human developer types tokencap remember --approve. It is reviewable, provenance-stamped, and 100% deterministic.

Scoring Grounding, Not "Truth"

One of the hardest engineering challenges in v2.7.0 was designing the quality gate. How do you evaluate whether a session summary written by an AI is safe to ingest?

Most tools attempt to use a secondary LLM to judge the first LLM. That adds cost, latency, non-determinism, and network egress.

TokenCap does something fundamentally different: we score grounding against your local AST knowledge graph.

Path Validity: Did the summary reference files that actually exist in the git tree?
Groundedness: When the summary claims it changed validateToken, does that symbol actually exist in the AST of src/auth.ts?
Specificity: Does the summary mention concrete functions, files, and architectural decisions, or is it vague filler like "refactored code and fixed issues"?
Novelty: Does this duplicate a session that was already approved yesterday?

We don't claim to evaluate the philosophical "truth" of an agent's reasoning. We evaluate whether the agent's summary is structurally anchored to the ground truth of your code.

Build Health: Because 40% of Agent Failures Are Rotten Context

If you hand an agent a 2-week-old context snapshot while your git working tree has 14 uncommitted changes and unmapped files, the agent will hallucinate. Then developers blame the model.

In v2.7.0, we introduced Repository Build Health (tokencap health).

Instead of guessing whether your context layer is trustworthy, TokenCap computes an explainable 0–100 health score before every session:

$ tokencap health

Build health: 94/100 · built 1.2h ago
  100  freshness — built 1h ago
   90  sourceDrift — 1 uncommitted change since build
   95  detection — Node.js, TypeScript, Next.js detected
   90  coverage — 3/3 intelligence layers present

Remediation:
  [low] 1 uncommitted file in src/auth/ -> run `tokencap make`

If your build health drops, TokenCap doesn't fail silently. It prints exact, copy-pasteable remediation steps (tokencap rebuild) and surfaces the health factor directly into MCP tools like tokencap_overview.

Honest Host Adapters (No Fake "Auto-Capture")

Every AI tooling company loves to put logos on their landing page and claim "Works seamlessly with every host!"

We took the opposite path in v2.7.0.

Run tokencap remember --hosts in your terminal today:

Host	Capture Level	Honest Reality
Claude Code	Assisted	Hooks exist, but session-end lacks a reliable native hook. Falls back to `remember`.
Cursor	Manual / CLI	Background extension cannot observe chat window termination.
Windsurf	Manual / CLI	Extension sandbox does not provide conversation-end lifecycle hooks.
Antigravity	Native MCP	Discovers staged inbound memories; manual review preserved.
Codex	Assisted	Staged review via CLI; never auto-committed.

We refuse to mark any host as "automatic" unless there is a verified, un-fakable session-end signal. An MCP process shutting down is not a conversation end — it's often just an editor reloading a window. Treating process kills as session saves corrupts repositories. TokenCap tells you the truth about what each host can and cannot do.

Closing the Loop Without Giving Away Your Sovereignty

The easiest way to build session memory would have been to spin up a SaaS cloud, ask you to paste an API key, upload your chat logs to an external database, and charge you $20/month per seat.

TokenCap v2.7.0 sticks strictly to our Four Laws:

Zero Network Egress: 100% of computation — the AST graphs, the secret redactions, the health scores, the staging engine — runs on your CPU. Not a single byte leaves 127.0.0.1.
Strictly 4 Dependencies: Zero native compilation toolchains. Pure Tree-sitter WebAssembly.
Budget-Capped: The latest approved session handoff (tokencap handoff) is formatted into clean, tight Markdown that fits comfortably in under 800 tokens.
Local Sovereignty: Your code, your memories, and your architectural intent stay inside .tokencap/ in your git repository.

Get Started with v2.7.0

TokenCap v2.7.0 is available on npm today.

# Update globally
npm install -g tokencap

# Check repository build health
tokencap health

# Capture your first session summary
tokencap remember --summary "Reworked auth middleware to JWT" --files src/auth.ts --decision "Used RS256 with 15m expiration"

# Review staged captures
tokencap remember --list
tokencap remember --approve <session-id>

# Export the handoff note for your next AI session
tokencap handoff

Stop teaching every AI your codebase from scratch. Close the loop.

TokenCap is an open-source, local-first context layer for AI coding agents.
Website · [GitHub]
(https://tokencap.vansharora.app/docs)

TokenCap v2.3.0 is live.

Sun, 30 Aug 2026 17:34:53 +0000

This release is about something I think AI coding tools are missing: a safe floor.

For months, I kept seeing the same failure mode.

You give an AI agent a refactoring task.

It renames a function.-->Breaks 11 files.-->Ships the change.

You spend the next 3 hours undoing it.

The problem isn't always that the AI is "dumb."

The problem is that it is allowed to make changes without deterministic safety guarantees.

So in v2.3.0, we built those guarantees into TokenCap.

TokenCap doesn't run your test suite.

Instead, it analyzes the AST call graph and identifies symbols with zero detected test coverage before you modify them.

No test runner.
No network.
No build pipeline.

This is the direction I'm taking TokenCap in.

Not another wrapper around an LLM.

Not another cloud service.

Not "AI for your codebase."

TokenCap is becoming deterministic infrastructure around AI-assisted development, designed to make AI coding agents safer to run.

v2.3.0 shipped with 82 tests, all green.

Install it:

npm install -g tokencap

Website: https://tokencap.vansharora.app
GitHub: https://github.com/vansharora21/tokencap
npm: https://www.npmjs.com/package/tokencap
VS Code Marketplace: https://marketplace.visualstudio.com/items?itemName=VanshArora21.tokencap
Open VSX: https://open-vsx.org/extension/VanshArora21/tokencap

TokenCap #OpenSource #DeveloperTools #AI #AICoding #Refactoring #TypeScript #JavaScript #SoftwareDevelopment #BuildInPublic

TokenCap v2.1.0 is out.

Mon, 17 Aug 2026 17:31:28 +0000

This release is focused on one idea:

Give AI coding agents better context, while reducing the amount of unnecessary context they need.

When working across Claude Code, Cursor, Windsurf, Copilot, Cline, Antigravity, and other coding agents, a lot of tokens are wasted repeatedly discovering the same repository structure, reading the same files, and rebuilding context.

TokenCap is built to solve that.

What’s new in v2.1.0:

Code Simplification
tokencap analyze simplify

Find unreachable code, duplicate logic, unnecessary abstractions, and reinvention patterns across JS/TS with evidence and confidence levels.

Context Compression
tokencap compress

Compress CLAUDE.md, AGENTS.md, .cursorrules, and similar context files while preserving headings, code fences, links, and URLs.

Token Savings
tokencap stats

Track how much context and tokens you actually save across runs.

Debt Ledger
tokencap debt

Track TODOs, FIXMEs, and deferred shortcuts without relying on expensive git blame operations.

MCP v2

Expose repository overviews, symbol impact, call graphs, and delta diffs directly to MCP-compatible agents and IDEs.

Also crossed 2,500+ installs on the VS Code Marketplace, which is honestly pretty cool to see for an open source project I started building for my own workflow.

The idea behind TokenCap is simple:

Your AI coding agent should not have to rediscover your codebase every time you start a session.

Website:
https://tokencap.vansharora.app

VS Code Marketplace:
https://marketplace.visualstudio.com/items?itemName=tokencap.tokencap

GitHub:
https://github.com/vansharora21/tokencap-plugin

Install:

npx tokencap make

Why Production Agents Are Ditching Pure RAG for Context Caching

Sun, 16 Aug 2026 10:07:01 +0000

Why Production Agents Are Ditching Pure RAG for Context Caching

Three months ago, our agentic workflow hit a cost wall. We were running a multi-step research agent that performed iterative document analysis. Every user request triggered between 12 and 18 agent steps. Across 50,000 active daily sessions, our vector database query costs and LLM input token bills were spiraling out of control—and worse, median step latency hovered around 4.2 seconds.

Like most teams building in 2024 and 2025, we assumed the fix was "better vector search." We tweaked top-k parameters, tried hybrid dense-sparse reranking, and chunked documents down to tiny 256-token fragments. It didn't fix the core problem. The bottleneck wasn't retrieval quality; it was retrieval architecture.

In production agentic systems, replacing pure vector retrieval-augmented generation (RAG) with long-context prompt caching (Cache-Augmented Generation or CAG) combined with lightweight local router models reduces median agent step latency by up to 68% and cuts monthly API inference spend by over 80%. This architectural pattern leverages deterministic context reuse over fragment chunking.

TL;DR / Key Engineering Takeaways

Vector RAG introduces compounding latency in agent loops: Each agent hop requires vector embedding, similarity search, top-k ranking, and prompt assembly, multiplying network overhead across multi-turn sessions.
Context Caching eliminates redundant prefix processing: Modern API providers allow long documentation, system schemas, and conversation histories to be cached at the edge, reducing token input costs by 75%–90% on cached prefixes.
Hybrid Local Routing stops token leakage: Routing lightweight classification, routing, and tool-selection decisions to local 8B–30B models reserves heavy frontier models only for final synthesis.
The 2026 Agent Standard is hybrid: Vector search handles sparse global discovery across millions of items, while context caching handles the dense session working memory.

The Production Bottleneck: Why Vector RAG Struggles in Agent Loops

When we first built our agentic pipeline, we followed the standard textbook pattern. Every agent step extracted state, searched a vector index, pulled the top-5 chunk snippets, and fed them into the prompt window alongside system instructions.

It worked great in prototypes. But once we moved to multi-agent orchestration—where agents delegate sub-tasks, summarize intermediate progress, and call tools repeatedly—the flaws became obvious.

[ Traditional Vector RAG Agent Step ]
State -> Query Gen -> Embed Query -> Vector DB Search -> Top-K Rerank -> Build Prompt -> LLM Inference
Total Step Latency: ~3.8s - 5.2s (Repeated for 15 steps = ~60s total session time)

[ Context Caching / CAG Agent Step ]
State + System Context (Pre-Cached Prefix) -> LLM Inference (Cached Hit)
Total Step Latency: ~1.1s - 1.6s (Repeated for 15 steps = ~18s total session time)

In an agentic loop, context is not static; it evolves incrementally. In our earlier writing on what an agent actually is, we broke down how an agent's harness relies on continuous feedback loops. Re-embedding queries and assembling fragmented chunks at every step creates three major friction points:

Lost Semantic Coherence: Chunking long technical specifications or codebase trees into 500-token snippets strips away critical cross-document relationships.
Double-Payment on Tokens: You pay vector database read costs and re-pay LLM input token processing fees for text the model already parsed two steps ago.
Compounding Latency: Adding 300ms vector index latency across a 15-step agent execution loop adds nearly 5 seconds of pure overhead to every user request.

Enter Context Caching (CAG): How Deterministic Prefix Reuse Works

Context Caching changes the economic math entirely. Instead of searching a vector database for relevant fragments on every turn, we load entire documentation bundles, domain schemas, or codebases directly into the LLM's extended context window (128k to 1M tokens) and cache the KV-cache states at the provider layer.

When the agent executes subsequent steps, the model processes only the new delta tokens (e.g., tool call outputs or user turns). The static prefix—which contains 95% of the total tokens—is retrieved instantly from the cached KV state.

+-------------------------------------------------------------------------+
| CACHED PREFIX (Static - 95% of Tokens)                                  |
| System Persona + API Schemas + Entire Core Codebase / Knowledge Base   |
| (Cost: ~90% Discount / Latency: ~50ms TTFT)                             |
+-------------------------------------------------------------------------+
| UNCACHED DELTA (Dynamic - 5% of Tokens)                                 |
| Current State + Latest Tool Execution Result + User Query               |
+-------------------------------------------------------------------------+

As we explored in our breakdown From RAG to CAG: A Smarter Approach to AI, shifting from retrieval-on-demand to context pre-loading simplifies system design. You eliminate vector index maintenance, embedding pipelines, and chunking heuristics.

Empirical Benchmark: Vector RAG vs. Context Caching vs. Local Hybrid

To measure the exact performance difference, we benchmarked three architectural approaches across 1,000 multi-step technical research tasks (averaging 12 agent turns per task, analyzing a 100,000-token technical repository):

Metric	Standard Vector RAG (Top-K=10)	Pure Context Caching (CAG)	Hybrid Router + Context Caching
Median Step Latency (TTFT)	3,840 ms	1,210 ms	890 ms
Total Session Latency (12 turns)	46.08 s	14.52 s	10.68 s
Input Token Cost / Session	$0.184	$0.038	$0.021
Task Accuracy / Completion Rate	78.4%	91.2%	92.6%
Vector DB Read Cost / 1k Sessions	$12.50	$0.00	$0.00

Benchmark Takeaways:

Latency: Context Caching dropped Time-to-First-Token (TTFT) by 68.4% compared to traditional vector RAG because the prompt prefix didn't require re-computation.
Cost: Token costs dropped 79.3% under pure CAG and 88.5% under the Hybrid Router approach because cached tokens incur a fraction of standard input pricing.
Accuracy: Full-context availability eliminated RAG retrieval failures (where vector search missed the relevant chunk due to poor keyword matching or semantic drift).

Architectural Deep Dive: Building the Hybrid Local Router Pattern

While Context Caching is powerful, pre-loading 100k tokens into a frontier LLM on every step can still be wasteful if the agent only needs to make a binary decision or select a simple tool.

To optimize latency further, we introduced a Local Hybrid Router.

How the Hybrid Router Architecture Works

                        +----------------------------+
                        |     Incoming User Request  |
                        +----------------------------+
                                      |
                                      v
                        +----------------------------+
                        |  Local Router (8B / 30B)   |
                        | (Tool Choice / State Check)|
                        +----------------------------+
                               /              \
                              /                \
          Simple Action / Tool Call          Complex Reasoning / Synthesis
                            /                    \
                           v                      v
           +-----------------------+   +------------------------------------+
           | Local Execution Loop  |   | Frontier LLM with Context Caching  |
           | Fast & Zero-Cost API  |   | Cached KV Prefix (100k+ Tokens)    |
           +-----------------------+   +------------------------------------+

Step 1: Local Triage: Incoming step state is evaluated by a small local model (e.g., an 8B model running on local GPU infrastructure or edge endpoints).
Step 2: Simple Execution: If the step is a mechanical tool invocation (e.g., git log, read_file, check_status), the local model executes it directly.
Step 3: Frontier Synthesis: If the step requires deep reasoning or complex synthesis across the codebase, the request routes to the frontier LLM backed by the cached KV prefix.

This hybrid approach mirrors the principles we outlined in our guide on real-time ranking systems at scale: decouple high-frequency lightweight operations from heavy, resource-intensive compute paths.

When Vector RAG Still Wins (And When to Avoid CAG)

Context Caching is not a silver bullet. During our production migration, we identified explicit boundaries where pure CAG fails and vector RAG remains necessary:

1. Corpus Size Exceeds Window Capacity

If your domain knowledge base spans millions of documents (e.g., 500 million tokens of legal case law), pre-loading the entire corpus into context is impossible or prohibitively expensive.

2. Low Prefix Reuse Ratio

Context caching relies on prefix stability. If user queries are entirely distinct and share no common system prompt, documentation context, or conversation history, you pay cache-creation surcharges without reaping cache-hit discounts.

3. Dynamic Write-Heavy Databases

If your knowledge base updates thousands of times per minute, invalidating the cached KV prefix on every write negates the performance benefits of caching.

Lessons Learned & Production Migration Checklist

If you are currently operating a production RAG pipeline and struggling with latency or costs, here is the incremental migration path we recommend:

[x] Audit your prompt prefix stability: Group your agent prompts into static prefixes (system instructions, tool definitions, reference docs) and dynamic suffixes (user query, latest message).
[x] Enable provider-level prompt caching: Activate KV-caching on your primary LLM endpoints (Claude, Gemini, or OpenAI) to instantly capture 50%–75% input cost savings on static prefixes.
[x] Implement a hybrid retrieval gate: Use vector search only for initial broad document discovery (filtering 10M tokens down to 100k tokens), then cache that 100k-token working set for the rest of the agent session.
[x] Offload simple tool routing to local models: Deploy a small local model to handle state-tracking and simple tool selections without waking up the frontier LLM.

Conclusion

Building reliable agentic systems requires moving past prototype patterns. Vector RAG served us well during the early era of short context windows, but in 2026, forcing multi-turn agents to constantly query vector databases is like making a developer query a database for every line of code they write.

By combining long-context prompt caching with intelligent local routing, you give your agents the entire working memory they need while slashing inference costs and step latency.

TokenCap is officially live on Product Hunt.

Mon, 10 Aug 2026 17:30:21 +0000

After months of building, iterating, breaking things, and shipping, I’m excited to finally launch TokenCap on Product Hunt.

TokenCap helps AI coding agents work with codebases more efficiently by generating graph-ranked, token-budgeted context so agents spend less time rediscovering the codebase and more time actually building.

We’ve already crossed 2.1K installs on Open VSX, and this launch is the next step in taking TokenCap further.

If you build with AI coding agents, I’d love for you to check it out, try it, and share your feedback.

We’re live on Product Hunt today.

Your support would mean a lot.

Links:

Product Hunt
https://www.producthunt.com/products/tokencap-2?launch=tokencap-2

Website
https://tokencap.vansharora.app

NPM
https://www.npmjs.com/package/tokencap

VS Code Extension
https://marketplace.visualstudio.com/items?itemName=VanshArora.tokencap

Open VSX
https://open-vsx.org/extension/VanshArora/tokencap

GitHub Plugins
https://github.com/vansharora21/tokencap-plugin

Context Engineering: The Skill Replacing Prompt Engineering

Mon, 06 Jul 2026 06:48:10 +0000

A couple of years ago, everyone was talking about Prompt Engineering.

People experimented with prompts like:

"Act as a senior software engineer."
"Think step by step."
"Explain like I'm five."

And it worked.

A better prompt often produced a better answer.

But AI is evolving.

Today, there's another skill that's becoming even more important:

👉 Context Engineering.

Let's understand why.

💡 What is Prompt Engineering?

Prompt Engineering is about asking better questions.

For example, instead of saying:

"Write code."

You might say:

"Write a scalable REST API in Node.js using TypeScript with proper error handling."

The better your prompt, the better the response.

Simple.

🚀 What is Context Engineering?

Context Engineering is about giving AI the right information, not just the right instructions.

Think about it.

If you ask an AI:

"Fix this bug."

It doesn't know:

Your project structure
Business requirements
Database schema
API contracts
Coding standards

Now imagine providing that context.

Suddenly, the AI can make much better decisions.

That's Context Engineering.

🤖 A Simple Example

Imagine two developers ask the same question.

Developer A

"Build a login API."

The AI makes assumptions.

Developer B

Provides:

Existing project structure
Authentication flow
Database schema
User roles
Tech stack
Coding guidelines

Then asks:

"Build a login API."

The second answer will almost always be better.

Not because the prompt changed.

Because the context changed.

🧩 Why Context Matters More

Large software projects aren't just code.

They're made up of:

Architecture
Business rules
Team conventions
Existing services
Dependencies

Without that information, even the smartest AI has to guess.

And guessing leads to mistakes.

📚 Where Does Context Come From?

Good AI systems gather context from many places, such as:

Code repositories
Documentation
Databases
APIs
Knowledge bases
Previous conversations

The goal is simple:

Give the AI enough information to make informed decisions.

⚡ Why This Matters for Developers

As AI becomes better at generating code, the real challenge isn't writing prompts.

It's providing the right context.

Developers who understand:

What information the AI needs
How to organize project knowledge
How to connect AI with tools and documentation

will get much better results.

🎯 Prompt vs Context

Think of it like this:

Prompt Engineering answers:

"What should I ask?"

Context Engineering answers:

"What should the AI know before it answers?"

Both are important.

But without context, even a perfect prompt has limits.

💡 Final Thought

The future of AI isn't just about writing smarter prompts.

It's about building systems that give AI the right context at the right time.

That's why many AI engineers are shifting their focus from Prompt Engineering to Context Engineering.

Because the best answers don't come from better questions alone.

They come from better understanding.

And in the AI era, context may become your biggest advantage.

💬 What do you think?

Is Prompt Engineering still enough, or do you think Context Engineering is becoming the more valuable skill?

Let's discuss below 👇

AI #ContextEngineering #PromptEngineering #LLM #AIAgents #SoftwareEngineering #Developers #Programming

AI Fundamentals - Part 2: Why AI Gets Things Right... and Wrong

Sun, 05 Jul 2026 05:24:31 +0000

In Part 1, we learned how an LLM turns your prompt into a response. It all comes down to predicting one token at a time using the information available in its context window. But that raises another question: if AI is capable of writing code, planning trips, and explaining complex topics, why does it sometimes confidently give completely wrong answers?

To answer that, let's continue building our AI-powered Travel Planner.

Running Example

Our Travel Planner is now live, and a user asks:

I'm visiting Tokyo next week. Recommend a famous ramen restaurant that's popular with locals.

The AI replies:

Tokyo Dragon Ramen is one of the city's most popular local restaurants.

The response sounds convincing and highly professional. The only problem? The restaurant does not exist. Why did this happen? Let's find out.

Pretraining: Where the Model Learns Its Knowledge

Before an LLM can answer questions, it goes through a phase called pretraining. During pretraining, the model learns patterns from an enormous collection of books, websites, articles, and other publicly available text. It isn't memorizing every sentence; instead, it learns the relationships between words, ideas, facts, and writing styles-similar to a student spending years reading library books before taking an exam. Once this learning phase is complete, the model's knowledge is static and fixed. It does not automatically learn new information every day.

💡 Developer's Takeaway

An LLM only knows what it learned during training. It doesn't browse the internet every time you ask a question.

(Note: While consumer chat applications like Google Gemini or ChatGPT can browse the web, they do so by using an external application wrapper that runs a search engine query behind the scenes, retrieves the results, and feeds that fresh information into the model's prompt. The core LLM itself remains static.)

Knowledge Cutoff: Why Models Don't Know Everything

Imagine a new observation deck opens in Tokyo tomorrow. If your model was trained last month, it won't know the place exists. This is called the knowledge cutoff-the point in time up to which the model has learned information. Anything that happened after that date is entirely missing. This is why questions like "Who won yesterday's match?", "What's today's weather?", or "Has this restaurant recently closed?" cannot be answered accurately by the model alone.

💡 Developer's Takeaway

If your application depends on current or frequently changing information, you'll need to provide that information from an external source at runtime rather than relying solely on the model's internal memory.

Hallucinations: When AI Makes Things Up

Instead of saying "I don't know," the model confidently invented Tokyo Dragon Ramen. This is known as a hallucination-when the model generates information that sounds believable but is incorrect, misleading, or entirely fabricated.

Hallucinations don't happen because the model is trying to deceive you. Remember from Part 1: the model's job is simply to predict the next token. Sometimes, the most statistically likely sequence of tokens forms a statement that simply isn't true. That's why hallucinations sound so convincing-the writing is fluent and the confidence is high, but the facts are completely wrong.

💡 Developer's Takeaway

Never assume an LLM's response is factually correct just because it sounds fluent and confident. Always validate important information.

Grounding: Giving the Model Reliable Information

How do we stop our travel planner from inventing restaurants? Instead of relying only on what the model learned during training, we can provide trusted information at runtime. For example, before asking the model to respond, our application retrieves a list of verified restaurants from a travel database.

Now the prompt effectively becomes:

Here are verified ramen restaurants in Tokyo:

Ichiran Shibuya

Ramen Street (Tokyo Station)

Menya Itto

Recommend one that's popular with locals.

Now the model isn't guessing; it's generating an answer based on reliable facts we've supplied. This process is called grounding. Grounding means providing the model with relevant, verified information so it can generate responses based on facts instead of assumptions. We'll explore how applications retrieve this information in Part 3.

💡 Developer's Takeaway

Grounding is one of the most effective ways to reduce hallucinations in production AI applications.

Prompt Engineering: Helping the Model Help You

Not every poor response is caused by the model itself; sometimes the prompt simply isn't clear enough. Consider these two prompts:

Prompt A: Recommend places to visit.
Prompt B: I'm visiting Tokyo for 7 days in October with my family. We enjoy history, local food, and walking tours. Recommend places to visit and explain why each is worth visiting.

The second prompt gives the model far more useful context to tailor its response. This is the essence of prompt engineering-the practice of writing prompts that help the model produce better results. It is less about finding "magic words" and more about providing enough context for the model to understand your exact intent.

💡 Developer's Takeaway

The quality of the output directly depends on the quality of the input. Clear prompts usually produce clearer, more relevant responses.

System Prompt vs. User Prompt

Most AI applications don't send only the user's message to the model; they also include hidden instructions. For example, our Travel Planner might send:

System Prompt: You are an expert travel planner. Recommend only verified locations. If you don't know the answer, say so instead of guessing.
User Prompt: Recommend a ramen restaurant in Tokyo.

The system prompt defines the model's role, rules, and behavior, while the user prompt contains the user's specific request. The user usually sees only their own prompt, but both are combined in the context window the model receives.

💡 Developer's Takeaway

Think of the system prompt as your application's permanent rules and the user prompt as the conversation happening within those rules.

Zero-shot, One-shot, and Few-shot Prompting

Sometimes telling the model what to do isn't enough; showing it an example works even better.

Zero-shot Prompting: You simply ask the model to perform a task without examples (e.g., "Summarize this itinerary.").
One-shot Prompting: You provide one example before the task (e.g., "Input: Two-day trip to Kyoto... Output: Short summary... Now summarize this new itinerary.").
Few-shot Prompting: You provide several examples before asking the model to complete the task. This helps the model understand the exact format, style, and length you expect.

💡 Developer's Takeaway

If the model isn't producing the format you want, showing one or two examples in the prompt is often more effective than writing a longer set of text instructions.

In-context Learning: Learning Without Retraining

Suppose we extend our prompt with three examples of great travel recommendations. The model starts producing responses that resemble those examples. Has it learned something permanently? No. It's simply using the information currently available in its context window.

This behavior is called in-context learning. The model adapts its responses based on the examples you provide during the conversation, without changing its underlying parameters. Once the conversation ends, those examples are gone, and the model hasn't been retrained.

💡 Developer's Takeaway

Providing examples can dramatically improve responses, but those examples only influence the active request or conversation context.

Bringing It All Together

Let's look at the flow behind the scenes when a user asks our grounded Travel Planner for a ramen recommendation:

User Request: The user asks for a recommendation.
Grounding: The application queries a database for verified restaurants and embeds them in the prompt.
Instructions: The application appends the system prompt and few-shot examples.
Pretraining & Context: The model uses its pretrained knowledge combined with the runtime context to generate a factual, formatted, and safe response.

This flow explains why two AI applications built on the same model can produce very different results: the difference lies in the quality of the grounding data and instructions.

Recap

In this article, we covered why AI behaves the way it does, detailing:

Pretraining and the knowledge cutoff.
Hallucinations and the power of grounding.
Prompt engineering, system prompts, and few-shot examples.
In-context learning.

In Part 3, we'll explore where this grounding information comes from, detailing embeddings, semantic search, vector databases, chunking, and how techniques like RAG and CAG help AI retrieve information.

CAG: The Simpler Way to Ground Your LLM

Sun, 28 Jun 2026 05:09:39 +0000

If you've been building AI applications recently, you've probably come across Retrieval-Augmented Generation (RAG). It has become the go-to way of giving LLMs access to external knowledge.

But RAG isn't the only option.

As context windows continue to grow, another approach is becoming increasingly practical: Cache-Augmented Generation (CAG).

Before we begin, a small disclaimer. This article intentionally argues in CAG's favor. Think of it as a friendly debate where CAG finally gets a chance to speak while RAG takes a short coffee break.

Why RAG Became So Popular

RAG solved a real problem.

Instead of expecting an LLM to know everything, we store information in a vector database. When a user asks a question, we retrieve the most relevant pieces and send them to the model.

A typical RAG pipeline looks like this:

Query → Embed → Search → Rank → Retrieve → Generate

It's a proven approach and works really well, especially when your knowledge base is large or changes frequently.

The only downside is that every question has to go through this retrieval process before the model can generate an answer.

That means more infrastructure, more moving parts, and a little extra latency.

Meet CAG

CAG takes a much simpler approach.

Instead of searching for information every time someone asks a question, it loads the required knowledge into the model's context once and keeps using it.

The workflow becomes:

Load knowledge → Cache context → Generate

That's the entire idea.

No vector search.

No retrieval step.

No ranking.

The model already has the information it needs.

Why Is This Possible Now?

A couple of years ago, CAG wasn't practical.

Context windows were simply too small.

Today, that's no longer true.

Many modern models support hundreds of thousands and sometimes even millions of tokens.

That changes the question from:

"How do I retrieve the right documents?"

"Can I fit my knowledge into the context window?"

For many internal tools, company documentation, onboarding guides, product manuals, and API references, the answer is surprisingly often yes.

RAG vs CAG

Both approaches solve the same problem, but in different ways.

Choose RAG when:

Your knowledge base is too large to fit into the model's context.
Information changes frequently.
Different users need different subsets of knowledge.
You need real-time data.

Choose CAG when:

Your documentation comfortably fits in the context window.
Most of the information is relatively static.
Low latency is important.
You want a simpler architecture with fewer components.

Neither approach is "better."

The right choice depends on your use case.

A Simple Example

A traditional RAG pipeline might look like this:

query = "What's our refund policy?"

embedding = embed(query)
chunks = vector_db.search(embedding, top_k=5)

context = "\n".join(chunks)

response = llm.generate(
    f"Context:\n{context}\n\nQuestion: {query}"
)

A CAG implementation is much simpler:

with open("knowledge_base.txt") as f:
    knowledge = f.read()

system_prompt = f"""
You are an assistant.

Use the following knowledge when answering questions.

{knowledge}
"""

response = llm.generate(
    system=system_prompt,
    user="What's our refund policy?"
)

The biggest difference isn't the amount of code.

It's that there is no retrieval happening during inference.

Why Not Use Both?

In practice, many applications don't have to choose one over the other.

A hybrid approach often works best.

Keep your stable documentation in the model's cached context using CAG.

Retrieve only the information that changes frequently using RAG.

This gives you fast responses for most questions while still allowing access to fresh information whenever needed.

Final Thoughts

As developers, we sometimes assume that every LLM application needs a vector database.

But that's not always true anymore.

Before building a RAG pipeline, ask yourself one simple question:

Does my knowledge base actually fit inside the model's context window?

If it does, CAG could be a simpler solution that's easier to build, easier to maintain, and often faster to serve.

If it doesn't, RAG is still an excellent choice.

The goal isn't to replace RAG.

It's to recognize that modern context windows have changed what's possible, and CAG deserves a place in the conversation.

TL;DR

RAG retrieves relevant information before every query.
CAG loads knowledge into the model's context upfront.
Modern context windows make CAG practical for many use cases.
If your knowledge fits in context, CAG is worth considering before reaching for a vector database.
For large or frequently changing knowledge bases, RAG remains the better choice.

Sometimes the simplest architecture is the one that gets out of the model's way.

ContextVault

Sat, 27 Jun 2026 22:31:11 +0000

From Conversation Recorder to Context Engine: Building Local-First Memory for AI Development

How ContextVault 1.3 unifies browser conversations, terminal sessions, and coding-agent decisions in one searchable local context engine — without a backend, tracking, or hidden AI calls.

You spend forty-five minutes walking a coding agent through a Redis connection bug. Together, you find the root cause, test a fix, and uncover a configuration detail that is not documented anywhere. Then the context window fills up. Two weeks later, the same bug appears in staging. The original session is gone, the browser conversation is buried, and the next agent knows nothing about what you already discovered. You start again. This is context fragmentation: project knowledge scattered across ChatGPT conversations, coding-agent sessions, terminals, accounts, models, and limited context windows. It creates a quiet tax on every AI-assisted workflow.

Exporting conversations helps, but only partially. A directory full of Markdown exports is still a directory full of disconnected files. The information is preserved, but it is not organized as project memory. That distinction changed the direction of ContextVault. What began as a browser conversation recorder evolved into a local-first context engine designed around a broader idea:

Git tracks code. ContextVault tracks context.

Why Exporting Conversations Is Not Enough

I originally built ContextVault as a Chrome extension for capturing conversations across multiple LLM platforms. The extension solved an immediate problem: preserving complete conversations locally and exporting them in portable formats.

But capturing browser conversations addressed only one surface.

The decisions that shaped a project were also happening inside Codex sessions, Claude Code investigations, Cursor workflows, terminal debugging, human notes, failed experiments, and task discussions. Those sessions often disappeared when a terminal closed or an agent reached its context limit.

I did not need another folder of exports. I needed a way to preserve what happened, classify it, search it, and prepare it for the next agent.

That led to three connected layers:

Browser Capture
Vault Terminal
The Unified Context Engine

Layer One: Building Browser Capture

Browser Capture is the original ContextVault surface. It is a Chrome Manifest V3 extension that captures conversations from ChatGPT, Claude, Gemini, Perplexity, Poe, DeepSeek, and Copilot.

The extension uses a hybrid DOM and network capture strategy. It watches provider DOM mutations, observes supported network responses, assembles streamed messages in the content-capture layer, and sends finalized messages to the background service worker for local storage.

This hybrid approach matters because LLM interfaces are dynamic. Assistant responses arrive incrementally, DOM elements change while streaming, and provider implementations differ.

Once captured, conversations remain in IndexedDB by default. Users can export them as individual Markdown files or bulk ZIP archives. Each exported conversation includes YAML frontmatter containing metadata such as platform, model, date, conversation ID, and tags.

The data flow is intentionally contained:

Provider page
    ↓
DOM and supported network capture
    ↓
Stream assembly
    ↓
Background service worker
    ↓
Local IndexedDB storage
    ↓
Explicit Markdown or ZIP export

The extension does not send captured conversations to a ContextVault server because no ContextVault server exists. It does not require an account, collect telemetry, or call an external AI API.

Browser Capture solved the first problem: preserving conversations. It did not yet solve project memory.

Layer Two: Building Vault Terminal

Browser conversations are only part of an AI development workflow. Important context also appears while working with coding agents and terminals: a failed authentication fix, a decision about middleware boundaries, an unresolved production problem, a task discovered during debugging, a note explaining why one approach was rejected.

Vault Terminal provides an explicit way to record those moments. It is a Node.js CLI published on npm as @aliabdm/contextvault.

Run it directly without installing anything globally:

npx @aliabdm/contextvault init

Or install globally:

npm install -g @aliabdm/contextvault
contextvault init

To start recording:

contextvault record

Inside the recorder, context is entered using typed commands:

/source codex
/title Fix auth middleware
 
/user The login redirect is broken.
 
/agent I found the issue in middleware order.
 
/decision Keep auth checks in middleware and policy checks in controllers.
 
/task Add a regression test for the redirect loop.
 
/problem The session cookie is missing on callback.
 
/end

These commands become structured context events. Each session is saved as a local Markdown file under .contextvault/sessions/. The files are human-readable, inspectable, searchable with standard tools, easy to archive, and ignored by Git by default.

There is no automatic summarization, rewriting, or external model call. Vault Terminal records what you explicitly provide. It does not intercept every terminal process or automatically capture complete Codex, Claude Code, or Cursor sessions. That limitation is deliberate and visible.

The CLI also supports:

contextvault list
contextvault search "Redis"
contextvault export

Vault Terminal solved the second problem: preserving agent work, decisions, tasks, problems, and notes outside the browser.

The next challenge was connecting both capture surfaces.

Layer Three: Building the Unified Context Engine

The Unified Context Engine turns separate captures into searchable project context. It imports Browser Capture exports, reads Vault Terminal sessions, normalizes both sources into shared models, and builds a local index.

Browser exports can be imported from Markdown files, ZIP archives, or directories:

contextvault import ./chatgpt-export.md
contextvault import ./contextvault-export.zip
contextvault import ./browser-exports/

The importer reads Markdown entries in memory, validates ContextVault frontmatter, sanitizes filenames, prevents unsafe archive extraction, applies deterministic duplicate detection, and enforces safety limits.

Current limits:

100 MB per archive
10 MB per Markdown file
1,000 files per import
ZIP entries are processed in memory rather than extracted to arbitrary disk paths. If the same export is imported twice, the duplicate is skipped. If an updated export shares the same conversation_id, the existing source is updated rather than duplicated.

Normalizing Different Context Sources

Browser chats and terminal sessions do not begin with the same structure. The normalization layer maps both into two shared models: ContextSession and ContextEvent.

Browser messages are mapped as user and agent events, with platform and role metadata preserved. Terminal events retain their explicit types: user, agent, decision, task, problem, and note.

The normalizer also supports legacy snake_case metadata fields — started_at, ended_at, git_branch — alongside current camelCase fields. This keeps existing Markdown sessions readable without requiring a destructive migration.

Building the Local Index

After importing or recording context, rebuild the index with:

contextvault index

The engine reads terminal sessions and imported browser conversations, normalizes them, and writes a local JSON index to .contextvault/index/context-index.json.

Markdown remains the source of truth. The JSON index is derived data. If it becomes corrupted or outdated, delete it and rebuild from the original Markdown files:

Local Markdown
    ↓
Normalize
    ↓
Rebuildable JSON index

There is no proprietary database format and no dependency on a hosted service. Users can inspect, edit, archive, or process their context without ContextVault.

Retrieving Evidence Across Capture Surfaces

Once indexed, context can be queried across both surfaces:

contextvault history --since 2w
contextvault decisions auth --source codex
contextvault problems redis --since 30d
contextvault retrieve "auth middleware" --type decision,task

Supported filters: --type, --source, --since, --limit.

Retrieval is local and deterministic. Ranking considers phrase matches, token matches, event-type boosts, and recency. It does not use embeddings, vector databases, semantic search, external models, or hidden AI calls.

The engine answers: What have I captured about this topic?

It does not claim to answer: What does all my project data mean?

The first question is grounded and testable. The second requires a semantic retrieval layer that ContextVault does not currently include.

Preparing Context for the Next Agent

The prepare command creates a focused context package:

contextvault prepare "auth middleware"

The generated file is written to .contextvault/exports/prepared-context.md. It can include project memory, relevant sessions, decisions, tasks, problems, and source metadata — portable Markdown that can be handed directly to Codex, Claude Code, Cursor, or another AI tool.

ContextVault does not call those tools. It prepares grounded context for the user to move explicitly.

Architecture Overview

The architecture separates four responsibilities:

Capture preserves browser or terminal context
Normalization converts sources into shared records
Indexing and retrieval make those records searchable
Preparation produces portable context for another agent
This separation creates boundaries for future adapters without changing the core storage model.

Integrations are adapters. The engine is the product.

Why Markdown Remains the Source of Truth

Project context should remain usable without the application that created it. A proprietary database can be fast, but it also creates dependency and obscures the raw material.

Markdown provides different guarantees: it opens in any editor, works with standard search tools, can be archived directly, remains readable if ContextVault disappears, and can be transformed with scripts or moved between tools.

The JSON index exists for retrieval performance. It is disposable. The Markdown is not.

Git tracks code history. ContextVault preserves the discussions, failed attempts, decisions, and discoveries surrounding that code.

Privacy by Design

ContextVault follows a local-first model. No captured data is sent to a ContextVault backend because there is no backend.

No backend — data remains on the local machine
No accounts — users control their own context
No telemetry — no usage tracking of any kind
No external AI calls — terminal capture and retrieval work entirely locally
No automatic cloud sync — files stay where you put them
No hidden model calls — retrieval stays deterministic
The .contextvault/ directory is ignored by Git by default. This matters because raw sessions may contain prompts, local paths, environment details, logs, debugging output, and potential secrets. Automatically committing that material would be an irresponsible default.

Users can choose how to archive or back up their files. ContextVault does not make that choice for them.

What ContextVault Does Not Do Yet

A useful technical project should make its boundaries as visible as its features.

No automatic terminal-agent interception. Vault Terminal captures what the user explicitly records. It does not hook into every shell process or capture complete Codex, Claude Code, or Cursor sessions.

No semantic search. Retrieval is lexical and deterministic. Optional local semantic indexing is future work.

No built-in natural-language answers. ContextVault retrieves evidence and prepares context packages. It does not synthesize answers. Users provide the prepared Markdown to the model they choose.

No automatic IndexedDB synchronization. Browser conversations enter the Context Engine through explicit Markdown or ZIP export and import. The extension does not automatically synchronize with .contextvault/.

Browser adapters can change. LLM providers regularly modify their interfaces. Provider changes may require adapter updates, and the generic adapter remains best-effort.

These are not hidden limitations. They are the honest boundaries of ContextVault 1.3.

Who ContextVault Is For

ContextVault is useful when:

You switch between ChatGPT, Codex, Claude Code, Cursor, or other tools
Coding-agent context windows reset during ongoing work
You need to revisit what an agent attempted several days ago
You want a searchable record of project decisions and problems
You need portable context packages that can move explicitly between tools
You want local ownership without accounts or telemetry
It is especially relevant for developers whose AI workflow has grown larger than any single conversation.

Why Not Just Use a Notes App?

Notes applications are useful for polished summaries. They are less effective at preserving raw working context: the failed attempt before the fix, the partial command output that revealed the bug, the agent response that influenced a decision, the unresolved problem discovered during another task, the reason an architectural approach was rejected.

ContextVault preserves that intermediate state. An /agent event records what the agent said — not what you later remember. A /decision event captures an explicit project decision. A /problem event keeps an unresolved issue available for future retrieval.

ContextVault is not a replacement for documentation. It is the context layer that makes future documentation easier to produce because the underlying evidence remains searchable.

Roadmap

The Unified Context Engine now exists. The next phase is reducing manual handoffs and improving retrieval without weakening the local-first model.

MCP Server — Expose project context through the Model Context Protocol so compatible agents can query it through an explicit integration.

VS Code Extension — Surface project decisions, tasks, problems, and related sessions directly inside the editor.

Agent Integrations — Build adapters for Codex, Claude Code, Cursor, and similar tools that can emit the shared context structure automatically.

Optional Local Semantic Indexing — Improve ranking with optional local embeddings while preserving the existing deterministic retrieval path.

Encrypted Backups and Optional Self-Hosted Sync — Support off-machine durability without requiring a third-party hosted service.

These are roadmap items, not implemented features. The current architecture provides the shared models, normalization layer, index schema, and adapter boundaries needed to build them incrementally.

Try ContextVault

ContextVault is fully open source and available today under the MIT License.

Initialize Vault Terminal directly from npm:

npx @aliabdm/contextvault init

Or install it globally:

npm install -g @aliabdm/contextvault
contextvault init

Start recording:

contextvault record

Build and query the local context index:

contextvault index
contextvault history --since 2w
contextvault retrieve "auth middleware"

Capture browser conversations, record coding-agent sessions, build a local context index, and prepare grounded context packages — all while keeping your data on your own machine.

Project links:

GitHub
npm Package
Live Demo
Technical FAQ
If you try ContextVault, I'd genuinely appreciate technical feedback. Does retrieval surface the context you expected? Is there a command or workflow you think is missing? How would you improve the developer experience?

Feel free to open an issue, submit a pull request, or connect with me on LinkedIn.

About the Author

Mohammad Ali Abdul Wahed is a Senior Software Engineer specializing in backend systems, Laravel, distributed applications, and AI developer tooling. He is the creator of ContextVault, an open-source local-first context platform that combines a Chrome Extension and an npm CLI to preserve browser conversations, coding-agent sessions, project decisions, and developer workflows across AI tools.

GitHub · LinkedIn · Portfolio

Your Folder Tree Is Already a Context Engine

Sun, 14 Jun 2026 03:55:48 +0000

Most developers think of a folder tree as a way to organize files.

For AI systems, it can be much more than that.

The Interpret-able Context Methodology (ICM), also known as the Model Workspace Protocol (MWP), introduced by Jake Van Clief and David McDermott, explores how structured project workspaces can improve AI reasoning and navigation.

My article explores this idea further and introduces MWP-Tool, an experimental visualization layer that transforms a repository into a navigable terrain map. The objective is to help AI agents and developers discover context through project structure instead of relying solely on larger prompts or increasingly complex retrieval systems.

If the repository already contains hierarchy, relationships, and intent, perhaps the folder tree itself is one of the most valuable context artifacts we have.

mwp-tool repository

Cognizant's AI Builder Vision: Closing the Gap Between Hype and Enterprise Reality

Fri, 05 Jun 2026 17:25:52 +0000

There's a moment in Ravi Kumar's keynote at the Cognizant AI Forum 2026 that cuts through a lot of the noise around enterprise AI. He puts it simply: a trillion dollars has already been invested in AI infrastructure. Another six to seven trillion is coming by 2030. And yet, the production value enterprises are actually getting from AI is nowhere near where the capability is.

That gap — between what AI can do and what it's actually delivering for businesses — is the problem Cognizant is positioning itself to solve. And it's the same problem that's been at the center of most conversations I've had with IT leaders, developers, and architects over the past two years.

Kumar isn't wrong about the diagnosis. He cites MIT, McKinsey, and Bain, along with comments from Uber and Microsoft, all pointing to the same challenge: token consumption has been reckless, ROI linkage has been weak, and enterprises are now asking hard questions about where the return actually is. Chapter one of enterprise AI — broad, open-ended experimentation — is over. Chapter two is about specifics, cost, and accountability.

Cognizant's answer is to reframe what a services company does in this environment. Kumar's term for it is "AI builder." The shift is from system integrator — the role Cognizant and firms like it have played for the past 25 to 30 years — to something that spans systems, people, and digital labor together. The addressable market he's describing isn't the familiar trillion-dollar IT services space. It's a $6 trillion opportunity that includes business operations, agentic workflows, and the messy integration work between old and new systems.

For developers and architects, a few things from the forum are worth paying attention to.

Context Engineering Is the New Craft

Kumar has been saying this since 2024, and the live demonstration at the forum makes it concrete. Work Fabric co-founder Rohan showed a working system — not a pilot — running across Cognizant's global sales force. The system extracts tribal knowledge from emails, contracts, conversations, and distributed team interactions, synthesizes signals across geographies, and surfaces revenue opportunities that no individual human could have found on their own. The result: $200 million in incremental pipeline, with a goal of $1 billion by year end.

The underlying idea is important. Models don't understand organizations. They process what you give them. Context engineering is the discipline of deciding what to give them — the work graphs, guardrails, tribal knowledge, and organizational nuance that makes an agent actually useful in a specific enterprise environment. That's a real engineering problem, and it's going to require people who understand both the technical and operational sides.

Token Economics Is an Architectural Problem

Kumar frames token spend as something that needs to be engineered, not just managed. Model routing, context quality, harness design, continual learning — these are all levers for making agentic systems more efficient and more predictable. For teams building or integrating AI systems, this is a cost discipline that's going to matter as much as any functional requirement.

The Agentic Sprawl Into Operations Is Real

Cognizant isn't just talking about AI-assisted software development. The bigger bet is on business operations — the $4.5 trillion of labor in global enterprises that Kumar says is exposed to agentification. The technical work here involves integrating agents with existing SaaS platforms, building what he calls "headless" interfaces to legacy systems, and designing agent development lifecycles that are fundamentally different from classical software delivery.

The forum also featured a telling example from LPL Financial, where Niteshun Bhasa, firm-wide AI leader, described how they think about AI as a multiplier of advisor judgment — not a replacement for it. The framing is useful: AI removes friction from everything that isn't judgment and relationship. That's a practical design principle, not a philosophical one.

These themes aren't new to anyone covering enterprise AI closely. Agentic systems, context engineering, human-digital labor integration, and token economics have been showing up in conversations with IT leaders, developers, and architects for the past two years. What's different now is that companies like Cognizant are moving from talking about these ideas to deploying them at scale — with real numbers attached.

Kumar's $6 trillion framing is ambitious. But the underlying observation is sound: the lines between systems and people are blurring, and the companies that figure out how to operate in that blurred space are going to be the ones that matter in the next decade. For developers and architects building in this environment, that's not an abstract question. It shows up in every design decision about where agents fit, what context they operate in, and how outcomes get measured.

That's the work. And it's just getting started.

Sanitization by Construction: Bounded Context Before the Network

Tue, 26 May 2026 08:00:00 +0000

Sanitization by Construction: Bounded Context Before the Network

Regex redaction on arbitrary broker exports fails the moment a column renames, a locale shifts decimal separators, or a merged cell appears. We chose structural exclusion: the Ask AI path never serializes a free-form ledger string because we never build one for the model.

The mechanism is buildPortfolioContext in app/lib/ai/contextBuilder.ts.

Edge Compiler = function contract, not a package

Edge Compiler is a term of art for this deterministic reduction. There is no EdgeCompiler npm module — only a pure function with a fixed output template:

const TOP_HOLDINGS_COUNT = 10;
// ...
lines.push('Portfolio summary (for personalization only):');
lines.push(`Total positions: ${totals.totalPositions}`);
lines.push(`Total trades: ${trades.length}`);
// Top holdings: ticker, shares, currency, value %, P/L %

Source comment (accurate):

// No raw ledger rows, no PII, no account identifiers—sanitization by construction.

Two pipelines — do not conflate

Stage	Input → output	What crosses the network for Ask AI
Import	Broker CSV → `Trade[]` via `packages/importer`	Not the default Ask AI body (Part 5)
Context build	`Trade[]` + positions → template string	Yes — bounded aggregate only

Import may touch account-ish columns while parsing; the inference boundary is the second stage. By the time buildPortfolioContext runs, only template fields can appear in the output lines.

What the LLM receives

Approved: “The LLM receives a bounded, user-approved aggregate context payload.”

Prohibited: “AI never sees your data.” The model also receives the user message, optional attachment content (explicit user action), and route-defined server injections (e.g. live quotes) per app/api/ai/chat/route.ts and docs/IP-TECHNICAL-MECHANISMS.md.

Approved: No PII and no account identifiers on the Pocket Analyst inference path as designed in contextBuilder.ts.

DevTools receipt

On a typical allocation question:

Client calls buildPortfolioContext(trades, positions).
Network tab shows a short context field in the POST body — not 10,000 trade rows.
Compare to guest localStorage or Firebase-backed trade count in application state — orders of magnitude larger than the payload.

Performance

Reduction is O(n) over trades for position derivation plus sort of position list for top-N — typically milliseconds on-device. Publish latency numbers only after measurement on target hardware.

Part 2 of Sovereign Ingestion & Stateless Inference.

Read the full Sovereign Intelligence book, explore Open Portfolio, or try Pocket Portfolio.

How many times have you told the agent the same thing this week

Wed, 13 May 2026 11:22:19 +0000

I caught myself, again, telling Claude that we don’t do it that way in this codebase.

Not the first time that week. Not the first time that day. Different repo, same correction. The kind of correction that doesn’t belong in a CLAUDE.md because it’s not really about that repo — it’s about how I work, the patterns I’ve learned the hard way, the shapes of solutions I trust because I’ve watched the alternatives blow up. But it’s also too specific to live in my global system prompt, because half of it only applies to certain kinds of services, certain teams, certain problem domains.

The agent was infinitely patient about it. I was the one running out of patience with myself.

Your judgment lives in a layer that has no home

Your CLAUDE.md knows the conventions of one repo. Your system prompt knows you, in the abstract. Neither of them knows why you stopped trusting that ORM after the migration last spring, or why you always pull a prod data sample before sketching a backend model, or why this particular service has a query pattern that looks wrong but is actually load-bearing for a reason nobody documented.

That stuff lives somewhere. For most of us, it lives in our heads. And it leaks — because every new agent session starts from zero, because the corrections you give the agent are exactly the corrections you used to internalize through reps, because you’d rather retype an instruction for the fifth time than build a system to remember it for you.

There’s a layer between the repo and the person where most of a senior engineer’s actual judgment lives. The investigation patterns that work across services. The bug classes you keep seeing in your team’s code. The query you wrote three weeks ago that nothing remembered. Almost nobody is engineering that layer deliberately. The whole AI tooling conversation is about giving the agent more context. Almost no one is talking about the engineer keeping their own.

This is the layer worth engineering. The question is where.

Some of this already existed

I’ve kept a dev journal for years. I wrote about it in What I’m Doing to Not Become Irrelevant — daily notes on what I worked on, what broke, what decisions I made. As a self-reflection tool, it’s solid.

Around it, other practices had grown. Deep-dive docs when I picked up hard problems. Spec-shaped files before I let myself code. Short retrospectives on how the spec held up to reality. Three or four practices, all separate, all useful in isolation — and none of them feeding the work itself, only my reflection on the work.

What changed wasn’t that I started writing things down. I’d been doing that for years. What changed was realizing the same artifacts — extended slightly, structured deliberately, made readable by an agent — could stop being a record of past work and start being an active substrate for current work. The foundation was already there. It just had one job.

Once I saw that, the rest followed. If the artifacts were going to feed the work, they needed somewhere to live where the agent could find them and the next stage could pick them up. Not a folder I’d drop notes into. A structure with rules about what goes where, named consistently, organized so a triage on Tuesday could read what a post-pr review wrote three weeks earlier. The journal taught me that writing things down was worth the friction. Building the hub was about making the things I’d written down do something for me beyond reflection.

The hub is a git repo. The structure is the argument.

The git repo part is boring. What makes it work is what flows through it.

The submodules are the actual work repos — the services I ship into at my job, pulled in as git submodules so the hub can cross-reference live code without copying it. The artifacts are markdown files with structure, named for the linear ticket they belong to, organized so the next stage can find them.

The repo is the persistence layer between stages of an engineering loop that, without it, would be stateless.

`triage`

The one that changed the most about how I work. It pulls the ticket, asks clarifying questions, then investigates in stages.

First pass is code-only: trace the relevant logic through the submodules, build an initial hypothesis. Second pass is data — Postgres read replica, gcloud logs, Datadog where it makes sense. The first-pass hypothesis either survives contact with reality or it doesn’t. Most of mine don’t, fully.

Then a proposed solution, scored 0 to 10 on confidence, separately for the diagnosis and the proposed fix. They fail differently; conflating them hides where the uncertainty lives. For bugs, the proposal splits in two: the immediate action (often a data fix or a manual op to stop bleeding) and the long-term solution.

Each stage writes its own markdown file. Data and code references in one. Problem statement and root cause in another. Solution and confidence breakdown in a third. The agent asks me questions, I push back. The score is a conversation seed, not a verdict.

`spec`

After triage, I write the spec. Investigation produces it. I’ll come back to why this inversion matters.

`review`

Same review command for my code and for teammates’ PRs. Same rules, same checks. The moment I have one set of standards for code I wrote and another for code I’m reviewing, the standards are theater.

It checks against the spec, against team conventions, against the project’s history of past mistakes. The last part is the one I care about most: searching past resolution docs for shapes we’ve seen before. For history search, I’m currently using ripgrep. I’ll come back to that too.

`post-pr review`

After the PR merges, this runs and produces a resolution doc. It diffs what I planned in the spec against what shipped, pulls in PR comments, and writes a short reconciliation.

The artifact I undervalued for years and now consider the most important one. Specs lie about what was built. The reconciliation doc tells the truth. When the next triage looks at history, it’s the resolution docs that catch the patterns.

`weekly review`

Runs every Friday. Reads everything I generated that week, distills it into themes, recurring problems, decisions worth remembering. Also the doc I lean on for 1:1s and performance reviews. Closes a loop the rest of the system would otherwise leave open: artifacts feeding back into how I think about my work, not just into the next ticket.

The more detailed the spec, the more it drifts

I want to call this out on its own because it’s the strangest thing I’ve learned from running this for a while.

The detailed upfront specs I used to write — the ones I felt best about, the ones that looked most professional — drifted from what actually shipped more than the looser ones did. Not less.

The reason is obvious in retrospect. Detailed upfront specs are confident guesses about a problem you haven’t investigated yet. Every concrete claim is a claim that has to survive reality, and the more of them you make before reality has a vote, the more turn out to be wrong.

A loose spec is just guesses with the honesty to look like guesses. A detailed upfront spec is guesses cosplaying as a plan.

Investigation produces the spec, not the other way around

The standard AI workflow goes: write a clear spec, hand it to the agent, review what it produces. That works for trivial work. It collapses the moment the problem is non-trivial, because it assumes the spec is correct, and the spec is almost never correct on the first pass.

The triage-first flow inverts this. By the time I’m specifying anything, the agent and I have already grounded the work in real code paths, real data shapes, real production behavior, real failure modes from past resolution docs, and explicit confidence scores. The spec describes what to build given what we know — not what we assumed before we looked.

The discipline echoes how good teams ship LLM features in production: you don’t trust the model’s confidence to substitute for evidence, so you build evals. Investigation-first is the same move applied to your own thinking. You don’t trust your confidence either.

I have not solved long-term memory

If I left it here it would sound like everything works. It doesn’t.

The biggest open problem is retrieval. The whole system depends on past artifacts being findable when they’re relevant. Right now, retrieval is mostly ripgrep — and ripgrep works better than it should. That’s the part that worries me. I probably don’t have enough volume yet to expose its limits.

I’ve tried chromadb, lancedb, a couple of small knowledge-graph experiments. None of them clearly beat ripgrep at my current scale. The vector results came back feeling like a search engine — close-enough matches that weren’t the right doc. Ripgrep came back feeling like memory — exact matches when they existed, honest absence when they didn’t. I’d rather be told nothing was found than be handed a confident wrong answer.

I’m also not running the full pipeline on every ticket. A copy change doesn’t need triage. A new field with no downstream effects doesn’t need a full investigation. I log them minimally because the weekly review benefits from a complete picture, but I’m not going to LARP investigation discipline on work that doesn’t need it.

Knowledge belongs in layers, and most of it is in the wrong one

The hub isn’t the lesson. It’s one instance of a lesson, which is that the discipline now is putting knowledge in the layer where it’ll actually fire.

There’s no bulletproof solution here, and I’d be lying if I said mine was one. The tools will keep changing. What stays is the question: where does this piece of knowledge belong so that the right agent in the right context can use it without me retyping it?

Most engineers have something working at the top and the bottom — a personal system prompt, a CLAUDE.md per repo. The middle is where the work is. It’s where your taste lives, your hard-won patterns, the corrections you keep retyping. It’s also where MCPs and skills should be scoped: attached to the kind of work they’re useful for, not loaded into every session globally or buried in one repo’s config.

The discipline is asking, every time you find yourself teaching the agent something: what’s the smallest layer this belongs in? If it’s true for one ticket, it lives in the task docs and dies with the ticket. If it’s true for one repo, it goes in CLAUDE.md. If it’s true across a domain of your work, it belongs in the middle layer — the one most people don’t have. If it’s true about you regardless of context, it goes in the global layer. Putting knowledge in the wrong layer is almost as bad as not capturing it: too narrow and you retype it, too broad and it pollutes contexts where it doesn’t apply.

History sits across all of it. Resolution docs, post-pr reviews, weekly distillations — they belong to past work but they feed every future stage. Retrieval is how history becomes context.

The reason this matters more than any specific tooling choice is that knowledge is the input that limits everything else now. The agents are fast. The compilers are fast. The deploys are fast. The bottleneck moved. What separates a senior engineer’s output from a junior’s with the same tools is almost entirely what they know and how reliably they can bring it to bear on the problem in front of them. Organizing your own knowledge — across layers, scoped correctly, retrievable later — is part of the craft now. Not a productivity hack.

Context is one slice of knowledge. Build for the whole stack.

The repo is the implementation. The argument is that knowledge is now an engineering artifact — and senior engineers either own theirs deliberately, scoped to the right layers, or accept that AI is going to hallucinate in the gaps where their judgment used to live.

We’ve spent two years getting better at giving the agent context. Almost no one is engineering the layers in between, or the history that feeds back into them. The agent has no memory. Your system prompt is too coarse. The repo file is too local. The middle is where most of your judgment lives. The history is where the lessons sit. Right now, for most people, both are leaking on the floor.

Don’t copy my structure. It won’t fit you, and even if it did it’ll be obsolete in a year. Notice that the layers exist. Notice which one each piece of knowledge belongs in. Build something — yours, ugly, evolving — that puts it there and lets it compound.

What to try Monday

Pick one piece of work you’re starting this week. Write the investigation before you write the plan. Note the code paths. Pull the real data if you can. Score your own diagnostic confidence on a scale you’d be embarrassed to fudge. Then write the spec.

Notice how much your specs were guessing before, and how much less they guess once they’re downstream of evidence.

The review process built on top of this is its own post — the part that pulls prod data correlation into the review itself, where this stops being a knowledge management story and starts being a production-engineering one. That’s next.

If your specs aren’t drifting from what you ship, you’re either not specifying enough or not shipping enough. Either way, the gap is the lesson, and right now most of us are throwing it away.

The post How many times have you told the agent the same thing this week appeared first on sudoish.

If you are using Claude Code in production, the agent is not the problem

Fri, 08 May 2026 21:44:38 +0000

The agent is not the problem. The substrate around the agent is. Here is the four-file shape that made my Convex production-database write boring on 2026-05-06, plus a stdlib Python script the Claude Code agent calls but did not generate.

Before the question lands: the bridge is not an agent improvising near prod. It is a deterministic Python script the agent calls. It writes to a bounded Convex HTTP endpoint. Prod writes need an env flag and a 401-preflight to fire. The cache dedups on a composite idempotency key. The logger strips anything that smells like a secret before it hits disk. The agent did not invent any of that.

In late April, a viral Reddit thread about an agent deleting a production database was making the rounds (recap). The fear was real. My bridge is still running because the agent did not have the room to improvise. Below is what made that true. Every claim has a file path you can grep for in your own setup.

What context engineering actually means in Claude Code

Vendors are calling context engineering the skill that separates serious solo operators from people who dabble. The trend is real. NxCode says over 60,000 public GitHub repos now include some form of agent instruction file. What it means in Claude Code is concrete: a CLAUDE.md at every project root, a global one at ~/.claude/CLAUDE.md, an auto-memory layer at ~/.claude/projects/, plus the skills directory, plus the templates directory, plus the hooks. Each one is a slot where context lives across sessions instead of being retyped into the chat.

Context engineering is not prompt engineering 2.0. Prompt engineering happens in the user message. Context engineering happens in the files Claude Code reads before the user message. Identity. Business state. Registries. Decisions. Voice. Scripts. Memory.

The common framing is one big system prompt and hope for the best. That breaks the moment your work spans more than one task surface. The layered framing replaces it. Folders, files, hooks, memory, vault. Each layer answers a question Claude would otherwise have to guess at.

There is a name for the pattern people are converging on: the control stack. Project rules plus reusable skills plus bounded sub-agents plus deterministic tools. The label is just the label, but the substance is what matters. Project rules go in CLAUDE.md. Reusable skills go in ~/.claude/skills/. Bounded sub-agents are described per-task in their own SKILL or template files. Deterministic tools are scripts the agent calls (not generates) when the task needs a specific outcome.

A vibe-coded one-shot script and a rail with all of this behind it can both run on a Tuesday. The difference is what is around the script. Tests, logs, idempotency cache, config gates, audit trail.

Both ship. Only one survives Wednesday.

Only one helps when you come back six weeks later and need to remember why a flag is set the way it is. The vibe-coded one is forgotten code. The control-stack one composes.

Concretely, here is what feeds my Claude Code session every conversation, before I type anything:

~/projects/agent-os/CLAUDE.md is the load-bearing identity file. Who I am, what I sell, who I sell to, the 90-day priorities. The agent does not ask. It reads.
~/.claude/projects/-home-jon/memory/MEMORY.md is the auto-memory index. User profile, feedback rules, project state, references that survive across sessions. The agent does not relearn me every conversation.
references/framework.md is the operator playbook. How decisions get made, what to optimize for, and what holds the rest together when the work scales.
decisions/log.md is the append-only why-log. Not just what changed. Why.

Those four files are part of the substrate. The identity and memory layers are loaded by default. The others are where the agent goes when the task calls for them.

The layers, one folder at a time

The Agent OS lives in three roots. ~/projects/agent-os/ for the project layer. ~/.claude/ for the global layer. ~/vault/ for the second-brain layer. Each layer has one job, and Claude Code reads them in a known order.

connections.md is the registry of every external system Jon-OS can reach. Gmail wired via the gws CLI. Drive the same way. GitHub via gh. Gumroad via PAT. NotebookLM via the notebooklm CLI. Status and last-touched date on each. When I started the Skool bridge, the agent did not have to guess whether Convex was reachable. The registry said yes, here is the deployment slug, here is the auth model. One row per system. The bridge never blocked on "is X wired."

decisions/log.md is the append-only record of every non-trivial decision and why. Reversible decisions get a one-line entry. Load-bearing ones get the full receipts. The decision to gate prod writes on SKOOL_ALLOW_PROD_WRITES=1 plus a 401-preflight against an allowlisted Convex deployment lives there. So does the decision to keep member content deny-by-default in logs. Future me reads it. Future agent reads it. When a teammate asks "why is this flag here," the answer is already written.

references/ holds voice samples, API guides, framework writeups. references/skool-api.md had the Skool Sheets endpoint shape, the field names, and the failure modes spelled out before any code got written. The composite idempotency key was specified there as {tab_slug}:{normalized_transaction_id}, before any handler. The bridge inherits the discipline of the spec. The spec inherits the discipline of the research that produced it.

scripts/ holds gumroad_api.py, skool_sheets_to_convex.py, and a handful of others. Stdlib-only Python. Deterministic tools the agent calls, not generated on demand. The Skool bridge is skool_sheets_to_convex.py. The redacting logger is one function in that script that strips email-shaped substrings and known secret prefixes before any line lands in the journal. The agent did not write that on a hunch. It came from the spec.

~/.claude/skills/ and ~/projects/agent-os/.claude/templates/ hold reusable skills and prompt templates. The Bike Method (training wheels first, then take them off) is encoded here. Prompt template first, then SKILL.md, then orchestrator. New capability gets the lowest-autonomy version that works. It only graduates when I make an explicit edit. The content pipeline I am running this post through started life as a prompt template. The next phase turns it into a skill. Slow on purpose.

~/.claude/projects/-home-jon/memory/ is Claude Code's auto-memory layer. It survives across conversations. The workflow rule that produced the Skool bridge lives here as a feedback memory. Research, then planning, then spec, then implementation, with Codex adversarial review at each phase. The agent does not relearn that every session. It just does it.

~/vault/ is the Obsidian second-brain. PARA-routed. Sessions, drafts, insights, workflows, references. The session note for the Skool bridge ship day lives at sessions/2026-05-06-skool-rail-live-content-pipeline-aegis-staged.md. Markdown plus frontmatter plus wikilinks. Plain text, plain folders, no platform lock-in.

Each layer has one job. Adding a new system means adding one row to connections.md and maybe one script to scripts/. The layers stay stable, so the work compounds. That is the boring promise of the control stack.

A worked example: the Skool transactional rail

The Skool transactional rail is a Python bridge. It polls two Google Sheet tabs that Skool-driven Zaps populate. New paid-member rows POST to a Convex HTTP endpoint that owns my YCAH member table. The other tab parses through without posting. The bridge runs on a systemd user timer:

OnCalendar=*:0/10

Every 10 minutes on the boundary. It has been live in prod since 2026-05-06.

Here is how it got safe.

The spec lived in references/skool-api.md before the code existed. Endpoint shape, field names, normalization rules, failure modes, idempotency strategy. Researched first, written second. The composite idempotency key was decided there:

{tab_slug}:{normalized_transaction_id}

Before any handler.

The spec went through Codex twice for adversarial review. The first pass killed a cookie-auth approach that would have violated Skool's ToS. The second pass drove composite idempotency keys and the prod-write guard. Both passes still missed an inferred field assumption. I had assumed Skool's "Answered Membership Questions" trigger exposed the member's email. The dry-run caught that the field was not there. Not Codex. Not me re-reading my own spec. The dry-run, against real data. The honest version: review found a lot, but the empirical step still earned its keep.

The pivot was clean because the spec was a document, not a vibe. I rewrote the affected section to "parse the QA tab, but do not POST member rows from it (the email-bearing trigger is the New Paid Member event on the Paid Members tab)," shipped Option A, kept moving. If the spec had only lived in my head, I would have been mid-implementation when reality disagreed. Instead, I edited a markdown file.

The cache had a quieter bug. The initial _read_json swallowed JSONDecodeError and returned a default empty dict. Under the corruption test in the verification checklist (step 0e: deliberately corrupt the cache file, run the bridge, check what happens), it would have silently rebuilt the processed-events cache and double-POSTed every prod row that had already been posted. Caught and fixed before the canary ran. To be precise: the test caught it. Not the spec, not the agent, not me eyeballing the diff. The verification checklist did its job.

The other guardrails earned their keep too:

Prod-write guard: SKOOL_ALLOW_PROD_WRITES=1 plus a 401-preflight against the allowlisted Convex deployment slug means a misconfigured run cannot touch prod. Fails closed at startup, before the first row is read.
Redacting logger: strips email-shaped substrings and known secret prefixes from every line before it hits the journal. Member content is deny-by-default. The bridge never logs row contents, only IDs and outcomes.
Canary verified: jgerton+*Emails are not allowed* landed clean in prod Convex. The idempotent re-run produced 0 new POSTs, 1 skipped, 0 errored.

None of those guardrails came from the agent improvising. They came from the spec. The spec came from the research phase. The research phase came from the workflow rule in memory. The substrate persists the rules. Discipline runs them. The dry-run and the corruption test catch what reviews miss. The agent itself wrote unsafe cache behavior on the first pass. The checklist caught it.

Sidebar: my Claude Code workflow rule

The discipline above is anchored in one feedback memory at ~/.claude/projects/-home-jon/memory/feedback_workflow_research_to_implementation.md:

Research, then planning, then spec, then implementation, with Codex adversarial review at each phase.

Codex (the OpenAI Codex CLI) is the adversarial reviewer that runs alongside Claude Code in my setup. It runs against the spec, then again against the implementation, before anything ships. The reviews catch the things I am too close to see. The dry-run catches the things Codex assumes. The verification checklist catches the things the dry-run does not exercise. The agent itself catches almost nothing past the first draft, and that is fine, because the agent is not the safety net. The workflow rule is. The rule lives in Claude Code's memory layer because the rule is the part that has to survive across every session. The agent does not relearn it. It just does it.

What compounds

The audit score ticking from 77 to 85 is not the point. What got cheaper is. The /audit pass surfaced a missing freshness column in connections.md, an old voice sample I had outgrown, and a reference doc whose code paths had moved. Each fix made the next session faster. The agent stopped re-explaining state I had already encoded.

Bigger payoff: the Aegis migration. I spent a day bulk-staging 75 skills, 66 commands, 5 agents, and 8 hooks from my desktop to the always-on minipc that runs Jon-OS 24 hours a day. None of those got built. They got recon'd, staged, and gated behind a settings diff, then activated. The hard work is path rewrites and activation order, not authoring.

The one I lit up first: the notebooklm skill. NotebookLM is now reachable as a CLI on this minipc, with ~/vault/CLAUDE.md mapping each domain to its dedicated notebook. I wrote a thin wrapper at ~/.claude/workflows/nlm-queue.py so the session-extract skill can auto-source captured insights to the right notebook (queues on auth failure, drains after re-auth). That makes NotebookLM scriptable from inside the content pipeline. The post you are reading now leaned on manual research. The next version of this pipeline can lean on a NotebookLM query inside the prompt template. Same discipline, less typing. Every shipped rail makes the next one cheaper.

The slower payoff is discovery. Three new YCAH members joined from three distinct platforms in the last month. Dev.to, Reddit /r/ClaudeAI, and TikTok. Three different surfaces, reached without me hand-writing each variant. Pipeline output, then discovery, then membership. The compounding works on the audience side too.

What this is not

This is not vibe coding. I do not trust one-shot scripts near prod. Not because someone on Twitter said so. Because I have been the person who shipped a one-shot, watched it work, and then watched it quietly stop working two weeks later for reasons I had no audit trail to understand. Front-loading the work is what makes the guardrails routine instead of heroic.

It is also not stacking Notion plus Claude plus ChatGPT plus Cursor and calling it a system. Those are fine tools. The mental model treats each one as an island. The control stack treats them as one composable system with a known read order. The intended read path is identity, state, registries, decisions, voice, scripts, memory, then the conversation. The point is not magic order. The point is that the context lives in stable files. Add a tool, you add a row in connections.md and maybe a wrapper in scripts/. You do not add a context-switch tax for yourself or the agent.

It is not theory. Every implementation claim above has a file path on my machine. Set up the same shape and you can grep your own.

What to copy first

If you are going to copy one piece, copy connections.md. Knowing what your Agent OS can reach is the cheapest unlock. You will build everything else against it.

Second: a decisions/log.md you actually keep. Append-only. One entry per non-trivial decision. The audit trail compounds faster than you think. By month two, you stop relitigating choices you already made and forgot you had made.

Third: seed Claude Code's auto-memory layer with your voice, your workflow, and your role. Once it is there, every conversation gets cheaper. You stop reintroducing yourself. The agent stops asking you the same orientation questions every Tuesday.

That is the order. Connections first, decisions second, memory third. Three files, in three days, before any new tool gets wired up. The bridge that runs my member sync was not built because I had a clever agent. It was built because the substrate was already there, and I used it. The discipline is mine. The files just stayed where the next session could find them. Boring on purpose.

Open one of those three files in your editor tomorrow morning. Write the first row. The compounding starts there.

Inside YCAH, I am doing this same work in public. The 4-file substrate, the workflow rule, the spec-first discipline, applied weekly to whatever members are shipping. Practitioner depth, not vending-machine demos.

Copilot Forgets Everything. Make It Stop.

Tue, 21 Apr 2026 13:07:54 +0000

You open a new Copilot chat and explain everything again.

Your stack. Folder structure. That “no default exports” rule.

Copilot writes code, but forgets context.

This isn’t a bug though. LLMs are stateless, every chat starts fresh.

The good part? You can fix it.

The Problem Has a Name

You’re dealing with three problems:

The Blank Slate: Every session starts from zero.
Correction Amnesia: You fix a mistake. Next session, same mistake.
Standards Drift: Your team has patterns. Copilot ignores them. Code becomes inconsistent.

Each problem has a different fix. Let's go through them one by one.

The Instructions File (Your Copilot Brief)

Create this file:

your-project/
└── .github/
    └── copilot-instructions.md

Copilot reads it at the start of every chat. No setup.

Think of it as your team’s “how we work” doc.

Example:

## Stack
- React 18, TypeScript (strict), Tailwind CSS
- Node.js + Express + Prisma + PostgreSQL
- Testing: Vitest + React Testing Library
- Package manager: pnpm only

## Rules
- Named exports only — no default exports
- No `any` types
- Every API route uses `authenticate`
- Handle nulls explicitly — no optional chaining on Prisma results
- Conventional Commits: feat(scope): message

Now everyone gets the same baseline.

Scoped Rules (Right Rules, Right Files)

One file works… until it grows.

Frontend, backend, and tests follow different rules. A single file mixes context.

Use scoped files:

.github/
├── copilot-instructions.md
└── instructions/
    ├── frontend.instructions.md
    ├── backend.instructions.md
    └── testing.instructions.md

Each file defines where it applies:

---
applyTo: "src/components/**/*.tsx"
---

## Component Rules
- Functional components only
- Props interface named `[ComponentName]Props`
- Use `cn()` for conditional classes
- No inline styles

Now Copilot gets relevant rules only.

The Memory Tool (Fix Repeated Mistakes)

Copilot has a memory tool in VS Code (preview, enabled by default).

When you correct it, make it persistent:

Remember: never use optional chaining on Prisma query results. 
Always handle null with an explicit if-check.

It stores this and applies it in future sessions.

Memory types:

User memory (all projects)

Remember I prefer async/await over .then()

Repository memory (this project)

Remember we use App Router (March 2026)
Remember UserAvatar breaks in Server Components

Session memory (current chat only)

Key habit: When you fix a repeated mistake, tell it to remember.

Check memory with Chat: Show Memory Files.

Note: Memory tool is in preview, enable via github.copilot.chat.tools.memory.enabled.

Prompt Files (Stop Repeating Yourself)

If you repeat prompts, create a prompt file:

.github/prompts/code-review.prompt.md

Use it with /code-review.

Example:

---
name: "code-review"
description: "Review staged changes"
mode: "ask"
---

Review staged changes.

Flag:
- Must Fix — bugs, auth, unsafe types
- Should Fix — standards, missing tests
- Suggestion — improvements

Reference [copilot-instructions.md](../copilot-instructions.md).

Now your team shares the same workflow.

Other useful prompts:

/new-component
/new-migration
/write-tests

The Full Picture

.github/
├── copilot-instructions.md
├── instructions/
│   ├── frontend.instructions.md
│   ├── backend.instructions.md
│   └── testing.instructions.md
└── prompts/
    ├── code-review.prompt.md
    ├── new-component.prompt.md
    └── new-migration.prompt.md

Plus memory running in the background.

Problem	Fix
Blank slate	`copilot-instructions.md`
Wrong rules	Scoped files
Repeated mistakes	Memory tool
Repeated prompts	Prompt files

Just Start With One Thing

You don’t need everything today.

Start with copilot-instructions.md. Add your stack and a few rules. Commit it. See the difference.

Then:

Add scoped files when needed
Save repeated fixes to memory
Create prompt files when repetition appears

The model won’t change. But your context can improve every week.

Everyone Was Talking About Context Engineering. Nobody Had Solved Governance.

Wed, 25 Mar 2026 09:35:27 +0000

MICA: Building a Memory Governance Schema (5 Part Series)

My LLM Kept Forgetting My Project. So I Built a Governance Schema.

The Schema Existed. The Model Had No Way to Know.

The Stake Was Governance Outside the Schema. MICA v0.1.5 Pulled It In.

The Model Already Read the README. MICA v0.1.8 Made It a Protocol.

Everyone Was Talking About Context Engineering. Nobody Had Solved Governance.

Glossary: terms used in this article

MICA (Memory Invocation & Context Archive): A governance schema for AI context management. Defines how context should be structured, trusted, scored, and handed off across sessions.
Fail-Closed Gate: An admission rule that excludes a context item if it fails a required threshold — regardless of its score on other dimensions. No exceptions. Introduced in v0.1.7.
README-as-Protocol: The pattern in which an AI session's natural behavior of reading the README first is formalized as the primary invocation mechanism. No installation required. Introduced in v0.1.8.
Invocation Protocol: The schema-level declaration of how a MICA archive reaches an AI session — and how the session confirms it was loaded. Formalized as a required field in v0.1.8.
Session Report Format: The structured opening report the model must produce at session start to confirm the archive was loaded. Required in v0.1.8.
Design Invariant Entry: A structured governance rule with identity, rule text, and severity. Replaced plain string invariants in v0.1.8.
Self-Test Policy: Machine-evaluable checks that validate the archive against the real project state — file existence, hash integrity, and README sync. Required in v0.1.8.
Playbook: The operator-facing discipline layer that sits outside the schema. The schema enforces structure; the Playbook enforces judgment.
Context Engineering: The practice of shaping what the model sees, in what order, with what boundaries, and under what assumptions — not just what you ask it, but what it actually knows at runtime.
CTX: A collection-first context packaging approach that gathers relevant workspace material and delivers it to the model. In this article, CTX represents the collection layer of context engineering — answering, “What does the AI see?”

1. What Parts 1 Through 4 Actually Established

The first four parts of this series already narrowed the problem considerably.

**Part 1 defined the failure mode.**
The issue was not that long-running AI work needed “more prompt.” The issue was that a model can only act on what it actually knows right now, and most project context systems still treat that as a document problem instead of a governance problem.
**Part 2 established the first hard boundary.**
A schema can exist, and the model can still have no reliable way to know it exists. That is the difference between a document and a constraint.
**Part 3 moved governance into the schema.**
Provenance, deviations, and semantic rules could no longer remain outside the system in READMEs, comments, or team habits. They had to become machine-readable structure.
**Part 4 made that structure operative.**
The model already treated the README as its natural entry surface. Once that behavior was declared as an invocation protocol, the schema stopped being a passive archive and became a runtime contract.

That progression defines what MICA is actually trying to solve.

It is not trying to be “better prompting.”

It is not trying to be “more retrieval.”

It is trying to answer a narrower question:

How does governed context reach the model, under declared rules, with confirmable load and auditable change?

That is the bridge into the broader landscape.

2. Context Engineering Was Never Just Prompting

One clarification matters before going further.

Context engineering is not just prompt writing.

At the broadest level, it is the practice of shaping what the model sees, in what order, with what boundaries, and under what assumptions. Prompts are one part of that. Retrieval is another. File selection, memory handoff, system instructions, and workspace state all belong to the same larger question:

What does the model actually know right now?

By that definition, MICA is part of context engineering.

Not because it retrieves context.

Not because it packs more tokens into a window.

But because it governs which context is allowed to shape the session, under what trust conditions, and with what record when those conditions are tested.

That distinction matters, because most of the field has focused on a different layer.

3. The Conversation Was Already Happening

Context engineering is not a new idea, and MICA does not claim to have invented the conversation.

The term was amplified by Andrej Karpathy and others, but the underlying practice — designing what the model sees, not just what you ask it — had already been emerging in serious AI work.

Collection-first tools already existed. CTX is a useful example of that layer: it gathers relevant workspace material and delivers it to the model without manual copy-paste. It answers an important question well:

What does the AI see?

At the same time, some of the sharper practitioner writing was already moving beyond collection alone. One such example was an OpenAI Developer Community post by Serge Liatko, “Prompt Engineering Is Dead, and Context Engineering Is Already Obsolete: Why the Future Is Automated Workflow Architecture with LLMs.”

The value of that piece was not the author's status, but the precision of the problem it named: manually maintained context eventually reaches its ceiling.

Once system state changes faster than humans can keep context aligned, the real question is no longer just how to collect context, but how to automate its ownership, maintenance, and validation as the system evolves.

That was an important move forward.

But one layer still remained underdefined.

4. The Missing Layer Was Already Visible

The same missing layer had already shown up elsewhere.

In Your Agentic Stack Has Two Layers. It Needs Three, I argued that the usual stack had matured around two strong layers:

MCP / tool calls — how the agent talks to systems
agent skills — what the agent can do

But something was still missing above both:

the layer that decides whether the agent should do it, under what constraints, and toward what end

That is the layer of intent, authority, and governance.

The same problem appears in context engineering.

A context pipeline can be excellent at retrieval and still be weak at governance. It can gather the right files, summarize the right notes, and deliver the right-looking material — and still fail to answer:

what is authoritative?
what is provisional?
what must never be violated?
what changed since last time?
how does the session prove it loaded the governed archive at all?

Those are not collection questions.

They are governance questions.

5. Where CTX Stops and MICA Begins

CTX solves the collection problem.

It answers:

What does the AI see?

That is a necessary layer. Without it, context management collapses back into manual copy-paste, repeated explanation, and fragile session startup.pro

But it does not answer the next set of questions:

Where did this context item come from, and can that claim be verified?
What happens when a file changes between sessions?
Which constraints are non-negotiable, and what is the consequence when they are violated?
Who approved the last change to the archive, and can that decision be audited?
When the session begins, how does the system confirm the archive was actually loaded?

Those are not retrieval questions.

They are governance questions.

That is the narrow but consequential difference.

CTX collects context and delivers it.

MICA governs what trust that context carries, what invariants it must not violate, what happens when it changes, and how the session proves that the governed archive was actually loaded.

One answers:

What does the AI see?

The other answers:

Under what rules does the AI operate — and what is the record when those rules are tested?

They are different layers. Neither replaces the other.

6. The Part That Was Still Open

A recurring theme in serious context-engineering discussion is that context cannot remain a hand-curated artifact forever. It has to become a function of system state.

But that still leaves one question open:

Who owns the specification for each step's input — and how is this versioned, tested, and audited as requirements shift?

MICA is a concrete, working answer to that gap.

Not the only possible answer. Not necessarily the final one. But a real one.

Its claim is not that context engineering needed to be invented.

Its claim is that context engineering still needed a governance layer with at least four properties:

machine-addressable invariants
versioned and auditable change records
self-tests against the real project state
declared invocation with confirmable session load

That is the layer MICA was built to supply.

7. What Governance Actually Means Here

Governance is an overloaded word. In this context it means something specific.

Provenance

Every context item must declare where it came from in a way that can be checked.

Auditability

Changes to the archive are recorded when they happen, not reconstructed later from memory.

Invariant enforcement

Constraints are not vague README prose. They are structured entries with identity and severity.

Self-testing

The archive is checked against the real project state, not only against its own internal shape.

Invocation confirmation

The model does not silently ignore the archive. Session start requires a structured acknowledgment that the governed archive was loaded.

None of these are abstract principles in MICA.

They are structural requirements in a running schema.

8. What This Is Not

It is worth being precise about the boundary.

MICA does not generate context automatically from the codebase. That is not its job. Collection-first systems already exist, and they are valuable. MICA governs what happens once context has been identified.

MICA does not replace human judgment. A schema can require structure, audit trail, drift response, and self-tests. It cannot eliminate operator discipline. That is why the boundary between schema and playbook matters.

MICA is also not a finished system. Parts 1 through 4 of this series were explicit about what each version got wrong, what each version corrected, and what remained unresolved.

That design history is part of the claim, not an embarrassment to it.

9. The Actual Claim

The actual claim is not that MICA solves all of context engineering.

It is this:

A small operation can already run a governed AI context system — with verifiable provenance, deviation audit trail, structured invariants, self-testing, and declared invocation — without waiting for future tooling that does not yet exist.

That claim is demonstrated by the design history already covered in this series:

v0.1.0 made scoring implementable
v0.1.5 brought governance structure into the schema
v0.1.7 made scoring fail-closed
v0.1.8 made invocation declared and confirmable
v0.1.8.1 clarified the remaining runtime ambiguities

And in practice, governance at runtime can look as concrete as this:

[SESSION READY]
Gate: PASS (self-tests: 7/7) | Track: A,B
Critical Invariants: 3/3 | Deviations: 0

If a critical check fails, the session does not proceed. That is what governance looks like when it becomes operative.

What can be said now is narrower and more solid: the gap is real, collection-first systems solve one side of it, and MICA addresses the governance side. The conversation about what comes after context engineering was already happening; MICA is one concrete answer to that part of it.

10. What Comes Next

Part 4 ended with a specific question:

Where does MICA sit in the context engineering landscape that already existed around it?

This post is the answer.

It sits inside context engineering — but not at the collection layer.

It does not compete with retrieval-first systems by trying to collect more files, pack more tokens, or automate more handoff. It begins after that layer. Its job is to govern what enters the session, what remains authoritative, what drift means, what violations matter, and how the model proves it actually loaded the governed archive at all.

That is why the answer is narrower than most people expect, and more specific than most framings allow.

MICA is not “the future of all context engineering.”
It is a governance answer to the part of context engineering that collection alone does not solve.

Part 6 will move back down from landscape to concrete operation.

It will show what MICA looks like in an actual project context: what a session opening report looks like, what a deviation log entry looks like in practice, and what happens when a self-test flags drift.

After that comes the harder question: what remains unresolved.

The series continues only where there is something concrete to specify, test, or correct.

Named decision from this post: Governance is not a layer you add after context engineering works. It is the layer that makes context engineering trustworthy — by declaring what is authoritative, recording what changes, and confirming what the AI actually loaded.

MICA is part of the Flamehaven governance-first AI systems practice. Schema, technical report, and production instance: flamehaven.space. Open-source tooling: AI-SLOP-Detector. All schema references follow the v0.1.8.1 Universal standard unless a specific earlier version is named.

MICA: Building a Memory Governance Schema (5 Part Series)

My LLM Kept Forgetting My Project. So I Built a Governance Schema.

The Schema Existed. The Model Had No Way to Know.

The Stake Was Governance Outside the Schema. MICA v0.1.5 Pulled It In.

The Model Already Read the README. MICA v0.1.8 Made It a Protocol.

Everyone Was Talking About Context Engineering. Nobody Had Solved Governance.

The Model Already Read the README. MICA v0.1.8 Made It a Protocol

Mon, 23 Mar 2026 19:43:18 +0000

MICA: Building a Memory Governance Schema (5 Part Series)

My LLM Kept Forgetting My Project. So I Built a Governance Schema.

The Schema Existed. The Model Had No Way to Know.

The Stake Was Governance Outside the Schema. MICA v0.1.5 Pulled It In.

The Model Already Read the README. MICA v0.1.8 Made It a Protocol.

Everyone Was Talking About Context Engineering. Nobody Had Solved Governance.

Glossary: terms used in this article

MICA (Memory Invocation & Context Archive): A governance schema for AI context management. Defines how context should be structured, trusted, scored, and handed off across sessions.

Fail-Closed Gate: An admission rule that excludes a context item if it fails a required threshold — regardless of its score on other dimensions. No exceptions. Introduced in v0.1.7.

README-as-Protocol: The pattern in which an AI session's natural behavior of reading the README first is formalized as the primary invocation mechanism. No installation required. Introduced in v0.1.8.

Invocation Protocol: The schema-level declaration of how a MICA archive reaches an AI session — and how the session confirms it was loaded. Formalized as a required field in v0.1.8.

Session Report Format: The structured opening report the model must produce at session start to confirm the archive was loaded. Required in v0.1.8.

Design Invariant Entry: A structured governance rule with identity, rule text, and severity. Replaced plain string invariants in v0.1.8.

Self-Test Policy: Machine-evaluable checks that validate the archive against the real project state — file existence, hash integrity, and README sync. Required in v0.1.8.

MICA: Building a Memory Governance Schema (5 Part Series)

My LLM Kept Forgetting My Project. So I Built a Governance Schema.

The Schema Existed. The Model Had No Way to Know.

The Stake Was Governance Outside the Schema. MICA v0.1.5 Pulled It In.

The Model Already Read the README. MICA v0.1.8 Made It a Protocol.

Everyone Was Talking About Context Engineering. Nobody Had Solved Governance.

1. Where Part 3 Left Off

Part 3 covered v0.1.0 through v0.1.5.

By that point, the schema had become implementable, then auditable. Provenance gained a registry. Changes gained an audit trail. Invariants gained structure.

But two things still remained missing.

Scoring was still not structurally enforced at the schema level. The formula existed, but it was still closer to convention than contract.

And invocation_protocol still did not exist. The archive could be perfectly governed — verified, logged, ruled — and the model could still begin work with no instruction to locate it.

The governance was visible. It was not yet operative.

This part covers the versions that closed both gaps — and the observation that made the harder one easier to solve than expected.

2. v0.1.7: Scoring Becomes a Contract

Since v0.0.1, scoring had been one of the structurally weakest parts of MICA.

The earliest version used hardcoded test values with no defined combination rule. Later versions introduced an implementable formula, but the formula still lived as a declared behavior rather than a fully enforced contract. A conforming archive could still be structurally valid while leaving too much scoring behavior open to interpretation.

v0.1.7 changed that in two steps.

First, scoring became a structured policy.
Second, admission became fail-closed.

That second change matters more than it first appears.

A weighted score answers:

Which item ranks higher?

A fail-closed gate answers:

Should this item be considered at all?

That is the question Part 2 identified as missing from the usual output-reliability framing.

To illustrate the pattern, here is a simplified educational example:

{
  "scoring_policy": {
    "weights": {
      "sim": 0.4,
      "trust": 0.3,
      "continuity": 0.1,
      "...": "..."
    },
    "gate_policy": {
      "trust_floor": "distilled",
      "fail_behavior": "exclude"
    }
  }
}

This is not the production specification. It is a teaching example.

The point is simple: once admission becomes fail-closed, scoring stops being "rank everything and hope the top item is good enough." It becomes a governed decision boundary.

By v0.1.7, scoring had become a contract.

But scoring was never the deepest structural gap.

The deepest gap had always been invocation — how the archive reached the model at all.

3. The Observation That Changed the Question

Before v0.1.8, invocation was framed as an installation problem.

How do you make sure the model loads the archive before starting work?
The assumed answers were plugins, tools, configuration, or external services.

But that assumption missed something simpler.

In many repository-based AI sessions, the README is already the model's first orientation point. Not because it is explicitly configured to read it, but because it is the natural entry surface for understanding a workspace.

The invocation mechanism did not need to be invented.

It needed to be declared.

That insight changed the problem.

If the README is already where an AI session begins, then the README can carry a structured session protocol:

load the archive
run session-start checks
report readiness
stop if critical governance conditions fail

A simplified educational example looks like this:

## [AI Session Protocol]

Before starting any work:

1. Load `memory/example-service.mica.json`
2. Check critical invariants
3. Run session-start self-tests
4. Report session readiness
5. Stop if any blocking condition is present

Required opening report:
- gate
- active invariants
- drift status
- track

This is the key idea behind README-as-Protocol.

The README is no longer just documentation.
It becomes the session entry layer.

README-as-Protocol is not a workaround.
It is a recognition: the invocation mechanism already existed in practice. It simply had not yet been formalized.

v0.1.8 turned that recognition into a schema-level contract.

4. v0.1.8: The Schema Reaches the Model

At this stage, the important change was not one field. It was the structural shift.

The archive no longer just described governance.
It declared how governance entered the session.

In simplified terms, v0.1.8 added five kinds of structure:

the archive declares how it reaches the model
the model must prove it loaded the archive
invariants become structured governance objects
the archive declares how drift is handled
the archive can validate itself against the real project state

The following simplified example illustrates three of those five additions:

{
  "project": {
    "name": "example-service",
    "version": "1.0.0"
  },
  "design_invariants": [
    {
      "id": "DI-001",
      "statement": "Do not introduce undeclared dependencies.",
      "severity": "critical"
    }
  ],
  "invocation_protocol": {
    "primary_pattern": "readme_protocol"
  },
  "session_report_format": {
    "trigger": "session_start",
    "required_fields": ["gate", "active_invariants", "track"]
  }
}

This example leaves out most of the real system. That is intentional.

The purpose is to show the architectural shift:

design_invariants says what must remain true
invocation_protocol says how the archive reaches the session
session_report_format says how the model proves it loaded the archive

The id makes the invariant referenceable in audit output, and severity determines how violations are handled.

Before v0.1.8, a session could begin with a perfectly governed archive existing somewhere in the repository — but with no requirement that the model actually load it.

After v0.1.8, the archive no longer merely existed.

It had a declared path into the session.

And the session was not considered ready until it reported that the archive had been loaded.

That is the moment where governance stopped being documentation and became runtime behavior.

Files change. Hashes drift. Before this layer existed, that drift could remain silent. Now the schema requires a declared response when the archive no longer matches the project it describes.

5. v0.1.8.1: Precision Patches

Once the major shift was in place, several smaller ambiguities appeared in practice.

These did not change the architecture.
They clarified how the architecture behaved.

In simplified terms, the patches did three things:

they made self-tests more explicitly machine-evaluable
they declared which runtime was responsible for running those tests
they clarified authority between invariant definitions and derived track views so drift could be detected instead of silently accumulating

These are not the kinds of changes that make headlines.

They are the kinds of changes that make a governance system stable enough to survive repeated use.

That is what patch releases are for.

6. Playbook: What the Schema Cannot Enforce

At this point, a second document became necessary: the Playbook.

The schema can enforce structure:

required fields
valid shapes
invocation declaration
opening reports
self-tests
drift behavior

But it cannot enforce operator judgment:

when to use which invocation pattern
how to update invariants safely
what counts as a complete archive
which shortcuts are acceptable
how to avoid human-caused drift

So the division became explicit.

The schema enforces structure.
The Playbook enforces judgment.

That is not a limitation. It is a design boundary.

A governance system that tries to encode all human discipline into the schema becomes brittle and unmaintainable. Some rules belong in machine-validated structure. Others belong in operator practice.

A simplified educational example makes the difference concrete.

The schema requires that invocation be declared:

{
  "invocation_protocol": {
    "primary_pattern": "readme_protocol"
  }
}

The Playbook explains how to use it correctly:

Use README-as-Protocol as the default starting mode.
Do not submit a partially completed archive to the validator as if it were final.
Treat invariant track assignment as the single source of truth.
Validate in this order: schema, invocation completeness, self-test coverage, provenance completeness, then track consistency.

The schema can require that invocation exists.
It cannot require that the operator uses it well.

README-as-Protocol works for the widest range of projects without requiring anything beyond a text file. That makes it the recommended default. But it is not the only option. More installed or infrastructure-heavy approaches may be better in some environments. The Playbook documents when the default is no longer enough — and what to do next.

7. The Distance from v0.0.1 to an Operative Schema

Part 2 named three failures in v0.0.1.

Failure 1: Scoring with no defined semantics.
The earliest version used hardcoded values with no clear combination rule or enforced model.
→ Closed in v0.1.0 (implementable formula) and v0.1.7 (structured scoring plus fail-closed admission).

Failure 2: Invariants encoded as comments.
The earliest version used plain strings where governance objects were needed.
→ Partially closed in v0.1.5. Fully closed in v0.1.8 when invariants became structured, referenceable, severity-bearing entries.

Failure 3: No path to the model.
The archive existed, but the model had no reliable way to know it existed.
→ Closed in v0.1.8 when invocation became a declared protocol and session start required proof of archive load.

That progression can be summarized simply:

The schema existed.
Then governance moved into the schema.
Then the schema reached the model.
Only then did governance become operative.

That is the real distance from v0.0.1 to this point.

8. Where This Leaves MICA

At this stage, MICA is no longer just a memory format.

It is no longer just a structured archive.

It is a runtime governance contract:

what context is allowed in
what must remain true
how the archive is loaded
how drift is handled
how readiness is reported before work begins

That is a different category of system.

9. What Comes Next

The next part of this series steps back from version history and asks a broader question:

Where does MICA sit in the context engineering landscape that already existed around it?

The answer is narrower than most people expect, and more specific than most framings allow.

Named decision from this post: An AI session already uses the README as an orientation surface. Formalizing that behavior as a schema-level invocation protocol is not a trick. It is the recognition that the mechanism already existed — and needed to be declared, not invented.

MICA: Building a Memory Governance Schema (5 Part Series)

My LLM Kept Forgetting My Project. So I Built a Governance Schema.

The Schema Existed. The Model Had No Way to Know.

The Stake Was Governance Outside the Schema. MICA v0.1.5 Pulled It In.

The Model Already Read the README. MICA v0.1.8 Made It a Protocol.

Everyone Was Talking About Context Engineering. Nobody Had Solved Governance.

The Stake Was Governance Outside the Schema. MICA v0.1.5 Pulled It In

Mon, 23 Mar 2026 08:21:51 +0000

MICA: Building a Memory Governance Schema (5 Part Series)

My LLM Kept Forgetting My Project. So I Built a Governance Schema.

The Schema Existed. The Model Had No Way to Know.

The Stake Was Governance Outside the Schema. MICA v0.1.5 Pulled It In.

The Model Already Read the README. MICA v0.1.8 Made It a Protocol.

Everyone Was Talking About Context Engineering. Nobody Had Solved Governance.

Glossary: terms used in this article

MICA (Memory Invocation & Context Archive): A governance schema for AI context management. Defines how context should be structured, trusted, scored, and handed off across sessions.

Provenance Registry: A structured, hash-anchored record of where each context item came from. Requires uri, sha256, kind, created_at, and trust_class. Formalized as a required field in v0.1.5.

Deviation Log: An auditable record of every change to a governed archive. Each entry requires before_hash, after_hash, gate, approved_by, and rollback_ready. Formalized in v0.1.5.

Semantic Validation Policy: A machine-evaluable rule set applied to context items. Each rule requires id, expression, severity, and on_fail. Replaces string invariants in v0.1.5.

Semantic Collapse: The pattern in which a JSON Schema specification is applied to an LLM as a runtime contract rather than as a validator. The LLM executes the schema semantically and produces a contract-compliant artifact. First demonstrated in v0.1.4.

Invocation: The mechanism by which a MICA archive reaches an AI session. Still absent at v0.1.5. Formalized as a required field in v0.1.8.

1. Where Part 2 Left Off

Part 2 documented three failures in v0.0.1: scoring with no defined semantics, invariants encoded as comments rather than constraints, and no path for the archive to reach the model at all.

The first two were fixable by adding structure. The third was different in kind — a schema without an enforcement path is not a governance schema at all.

This part covers v0.1.0 through v0.1.5. What the intermediate versions fixed. What experiment revealed the need for v0.1.5. And what was still missing at the end of it.

2. The Stake Nobody Pulled

There is an old story about elephants. A young elephant chained to a small stake learns it cannot move. Years later, fully grown, it still does not pull — not because the stake holds, but because the boundary became an unquestioned assumption.

In practice, what I kept seeing across LLM tooling discussions was exactly that. Technical provenance tracked inside the system, governance detail left in documents. Who approved a change, under what conditions, with what rationale — always a README, a review checklist, a comment. Never the schema. Semantic rules written as strings, described in documentation, reviewed by humans. Everyone knew the constraint. Nobody encoded it.

The stake was real. It was not immovable.

v0.1.0 through v0.1.4 did not question it.

The stake was a single assumption: governance lived outside the schema.

3. v0.1.0 to v0.1.4: More Implementable, Not Yet Inspectable

These versions addressed the first two failures from v0.0.1. In brief:

v0.1.0: Scoring became implementable — hardcoded hints replaced with an explicit weighted formula: clamp01(0.55 * sim + 0.15 * recency + 0.10 * invoke + 0.10 * trust + 0.10 * continuity). Two implementations now produce the same number for the same inputs.
v0.1.0: invoke_role semantics defined — each role got explicit score bonus, pin behavior, compile behavior, and eviction priority.
v0.1.0: Eviction became a five-phase strategy — budget overflow had a defined sequence and a failure condition.
v0.1.0: Error handling defined — eight failure modes, each with an explicit action and severity.
v0.1.4: Description updated to include "semantic enforcement" — required field count unchanged. The label was ahead of the implementation.

These versions made the schema reproducible to implement. They did not make governance inspectable. design_invariants remained a plain string array. scoring_policy.function remained a free string in the JSON Schema. provenance_registry did not exist. The assumption from Section 2 was still in place.

4. The Experiment That Revealed the Gap

In March 2026, a semantic collapse experiment was run against v0.1.4. The procedure was direct: provide the schema and session context to an LLM, instruct it to execute the schema semantically, and verify the output against all required fields.

The result was a fully contract-compliant artifact. Zero field violations. Zero type constraint violations. The scoring pipeline ran. The eviction log was correct. The audit trail was structurally preserved. The schema worked — as a semantic contract against an LLM runtime.

But the artifact also contained this:

"provenance": {
  "uri": "mica://memory/flamehaven-labs/project/identity",
  "source_kind": "memory_export",
  "trust_class": "canonical",
  "collected_at": "UNKNOWN",
  "content_hash": "sha256:project_identity_anchor"
}

"collected_at": "UNKNOWN". Every memory-tier item in the artifact carried this. The timestamp was not available. The schema had no mechanism to require it. The provenance claim could not be verified — not because the data was missing, but because the schema had no structure to anchor it.

The experiment proved the schema was executable. It also proved that a contract-compliant archive could contain provenance that was structurally present but epistemically empty.

The same experiment revealed two more gaps. Design invariants were strings — the LLM read them, interpreted them, and applied them as best it could. But there was no id to reference in audit output, no severity to determine handling, no on_fail to define consequence. And every change to the archive between sessions had no record. No before_hash. No approved_by. No rollback_ready. The archive changed silently.

The semantic collapse experiment proved the schema was implementable. It also produced a precise map of what governance was still missing.

That map became v0.1.5.

5. The Question v0.1.5 Asked

v0.1.5 did not ask "what else should we add?"

It asked: what if governance itself belongs inside the schema?

Not as a description of what enforcement should look like. As a machine-evaluable structure that enforces it.

MICA v0.1.0 through v0.1.4 had followed the same pattern common in practice — governance detail kept implicit, schema focused on structure and scoring. The experiment made the cost of that pattern visible. v0.1.5 pulled three assumptions out of documentation and forced them into machine-readable structure.

6. What v0.1.5 Pulled In

Stake 1: Provenance was a field. v0.1.5 made it a registry.

The experiment artifact had "collected_at": "UNKNOWN" on every memory item. Before v0.1.5, there was no mechanism to prevent that — or detect it.

v0.1.5 introduced provenance_registry as a required top-level structure. Each record:

"required": ["uri", "sha256", "kind", "created_at", "trust_class"]

sha256 anchored the source to a specific state. trust_class declared reliability at registration — not inferred at use. created_at was now required — not optional, not "UNKNOWN". A context item's provenance claim could now be checked against the registry. If the hash did not match, the claim was false.

Provenance had been a field on a document. v0.1.5 made it a verifiable record.

Stake 2: Changes happened. v0.1.5 made them auditable.

Between sessions, the archive changed. There was no record of what changed, when, under whose authority, or whether it could be undone.

v0.1.5 introduced deviation_log as a required field. Each entry:

"required": [
  "change_id", "timestamp_utc", "gate", "reason",
  "before_hash", "after_hash", "approved_by", "rollback_ready"
]

before_hash and after_hash meant every change left a cryptographic record. gate associated the change with a defined governance checkpoint. approved_by declared authority explicitly. rollback_ready required the system to declare whether it could undo the change before committing it.

Change history had been implicit. v0.1.5 made it a required audit trail.

Stake 3: Invariants were strings. v0.1.5 made them rules.

The experiment applied string invariants as best as the model could interpret them. There was no id to reference in audit output, no severity to triage violations, no on_fail to define consequence.

v0.1.5 introduced semantic_validation_policy with structured rules:

"required": ["id", "expression", "severity", "on_fail"]

Each rule had an id — referenceable in audit output. Each had a severity — determining how a violation was handled. Each had an on_fail — defining the consequence. A violation could now be detected, logged, and traced.

String invariants described what the system must not do. Semantic rules could detect when it did.

7. What v0.1.5 Still Did Not Have

Two things remained missing.

Scoring was still a free string at the schema level.

scoring_policy.function was still { "type": "string" } in the JSON Schema. The weighted formula from v0.1.0 was a specified convention — implementors who followed it produced the same number. But the schema could not enforce that they did. A conforming archive could contain any string in that field. The formula was real. The contract was not.

The archive still had no path to the model.

invocation_protocol did not exist in v0.1.5. The provenance registry was hash-anchored. The deviation log was auditable. The semantic rules were machine-evaluable. A session could start with a perfectly governed archive — verified, logged, ruled — and the model would begin work with no instruction to locate it.

The governance was visible. It was not yet operative.

8. What This Series Covers Next

Part 1 defined the problem.

Part 2 documented v0.0.1 — what it was and why its most fundamental failure took the longest to fix.

This part covered v0.1.0 through v0.1.5: how the schema became implementable, then auditable, and what it still could not do.

Part 4 covers v0.1.7 and v0.1.8: the fail-closed gate, the provenance enforcement boundary, and the version that finally made invocation a required field — the stake that had been in the ground since v0.0.1.

The series continues only where there is something concrete to specify, test, or correct.

MICA: Building a Memory Governance Schema (5 Part Series)

My LLM Kept Forgetting My Project. So I Built a Governance Schema.

The Schema Existed. The Model Had No Way to Know.

The Stake Was Governance Outside the Schema. MICA v0.1.5 Pulled It In.

The Model Already Read the README. MICA v0.1.8 Made It a Protocol.

Everyone Was Talking About Context Engineering. Nobody Had Solved Governance.

The Schema Existed. The Model Had No Way to Know.

Mon, 23 Mar 2026 08:21:28 +0000

MICA: Building a Memory Governance Schema (5 Part Series)

My LLM Kept Forgetting My Project. So I Built a Governance Schema.

The Schema Existed. The Model Had No Way to Know.

The Stake Was Governance Outside the Schema. MICA v0.1.5 Pulled It In.

The Model Already Read the README. MICA v0.1.8 Made It a Protocol.

Everyone Was Talking About Context Engineering. Nobody Had Solved Governance.

Glossary: terms used in this article

MICA (Memory Invocation & Context Archive): A governance schema for AI context management. Defines how context should be structured, trusted, scored, and handed off across sessions.

Session Loss: The architectural characteristic of LLMs where no information persists between independent conversations. Not a bug. A design property with real engineering consequences for long-running projects.

Trust Class: The reliability classification of a context item's source. In this series: canonical (repo truth), distilled (summarized from sessions), raw (unprocessed session output), symbolic (reference only).

Invoke Role: A governance label that defines a context item's eviction behavior. In this series: anchor (never evict), bridge (preserve across phases), hint (drop first under pressure), none (drop immediately).

Invocation: The mechanism by which a MICA archive reaches an AI session. Without explicit invocation, the archive exists but has no effect on the session. Formalized as a required field in v0.1.8.

Admission Gate: The point at which a context item is evaluated for inclusion. Decides what goes in — before output validation begins.

1. What v0.0.1 Was

Part 1 established the problem: session loss is not an inconvenience. For long-running projects, it is a structural failure. The standard responses — longer prompts, RAG, session summaries, flat memory exports — all treat context as a document to be read, not a governed structure with authority levels, eviction rules, and provenance.

v0.0.1 was the first attempt at a specification-level answer.

It proved that context could be structured. It did not prove that the structure could govern what context is allowed to shape the session. Those are different claims. v0.0.1 satisfied the first and failed the second — in three distinct ways.

Only one of those failures made the other two meaningless.

2. A Different Layer

While working through the problem, I was reading broadly. arXiv papers on memory management. Dev.to articles on LLM reliability. Community discussions about what people had tried and where it broke.

One article in particular was useful: Why Asking an LLM for JSON Isn't Enough. In that article and the discussion it generated, a clear framing had emerged:

Treat the LLM as an unreliable upstream service. Add schema, validation, retry, fallback.

The operative mental model was this:

LLM → output → validate → retry → fallback → use

This framing is correct, and useful, for what it solves: defensive parsing and output reliability. None of it addressed admission control — denying a context item before it reached the model at all.

The question I needed to answer was structurally different:

Context item → admitted? → trust level assigned → provenance checked → eviction priority set

The first asks "how do I handle what comes out?" The second asks "what goes in, and under what rules?"

MICA is not a replacement for output validation. It is the upstream governance layer that decides what is allowed to shape the session before output validation even begins.

3. Three Failures in v0.0.1

Failure 1: No defined semantics for scoring.

scoring_policy:
  relevance_inputs:
    - "query similarity"
    - "recency"
    - "invoke_role"
    - "trust_class"
    - "capsule continuity weight"
  scoring_hints:
    canonical_memory_bonus: 0.15
    continuity_bridge_bonus: 0.05
    raw_logs_penalty: 0.20
    symbolic_only_penalty: 0.10

These were hardcoded test values. They existed to confirm that the pipeline could apply differential weights at all — not to define what those weights should be.

The problem was not that the numbers were heuristic. The problem was that the heuristics had no defined semantics — no defined rule explained how they produced a score.

There was no combination rule.
No output range.
No normalization.

What canonical_memory_bonus: 0.15 meant relative to raw_logs_penalty: 0.20, how those four numbers combined into a final score, what the result represented — none of that was specified.

A conforming implementation was not possible. That means two tools claiming to implement v0.0.1 could rank the same archive differently and both still claim compliance.

Failure 2: Invariants encoded as comments, not constraints.

v0.0.1:

design_invariants:
  - "Context Broker must not generate SovDef."
  - "LawBinder must never receive raw Context objects."
  - "Only working_context may be passed to LLM-facing layers."

A plain list of strings. No id. No severity. No track. They were written as constraints, but encoded as comments. The difference matters: a constraint has enforcement. A note does not. These strings could not be machine-evaluated, could not be diff-checked against session behavior, and could not be reliably extracted by a model reading the archive.

What a machine-actionable invariant requires:

design_invariants:
  - id: INV-001
    rule: "Context Broker must not generate SovDef."
    severity: "critical"
    enforceable: true
    track: "compile-time"

Without id, an invariant cannot be referenced in audit output. Without severity, a violation cannot be triaged. Without track, enforcement has no defined point of application. v0.0.1 had none of these.

Failure 3: No path to the model.

There was no invocation_protocol. No session-start procedure. No confirmation that the archive had been loaded. The model would begin a session with no instruction to locate the archive, no way to confirm it had been read, and no defined behavior for what to do at session start.

The archive existed. The model had no reliable way to know it existed.

A new session could start, answer confidently, and never once acknowledge the archive it was supposed to be governed by.

4. Why Failure 3 Made the Others Meaningless

The three failures are not equal.

Failure 1 is a calibration problem. The formula can be fixed. The weights can be justified. That work happened in subsequent versions.
Failure 2 is a schema design problem. Fields can be added. Structure can be enforced. That work happened in the same range.
Failure 3 is different in kind. It is not a field that needs to be added. It is a requirement that the schema must define how it reaches the model at all. A context item classified as anchor with eviction_priority: 3 has no enforcement if the model never sees the archive. F

ailures 1 and 2 describe a schema that could not govern correctly. Failure 3 describes a schema that could not govern at all.

A context system does not fail only when it forgets. It also fails when it remembers without governance — and v0.0.1 could not even guarantee the second.

Every version from v0.1.0 through v0.1.7 addressed the first two failures. Scoring became implementable. Invariants gained structure. Eviction became a five-phase strategy. Error handling was defined.

The invocation problem was not formally addressed until v0.1.8, which introduced invocation_protocol as a required field. It declares how the archive reaches an AI session, what pattern is used, and what the session opening report must contain.

That is the distance between v0.0.1 and v0.1.8.

5. What This Series Covers Next

Part 1 defined the problem.

This part documented v0.0.1 — what it was, what it got wrong, and why the most fundamental failure took the longest to fix.

Part 3 covers v0.1.0 through v0.1.5: how scoring moved from hardcoded guesses to an implementable formula, what the eviction strategy revealed about context budget assumptions, and what was still missing at v0.1.5.

The series continues only where there is something concrete to specify, test, or correct.

MICA: Building a Memory Governance Schema (5 Part Series)

My LLM Kept Forgetting My Project. So I Built a Governance Schema.

The Schema Existed. The Model Had No Way to Know.

The Stake Was Governance Outside the Schema. MICA v0.1.5 Pulled It In.

The Model Already Read the README. MICA v0.1.8 Made It a Protocol.

Everyone Was Talking About Context Engineering. Nobody Had Solved Governance.

My LLM Kept Forgetting My Project. So I Built a Governance Schema.

Mon, 23 Mar 2026 08:21:07 +0000

MICA: Building a Memory Governance Schema (5 Part Series)

My LLM Kept Forgetting My Project. So I Built a Governance Schema.

The Schema Existed. The Model Had No Way to Know.

The Stake Was Governance Outside the Schema. MICA v0.1.5 Pulled It In.

The Model Already Read the README. MICA v0.1.8 Made It a Protocol.

Everyone Was Talking About Context Engineering. Nobody Had Solved Governance.

Glossary: terms used in this article

MICA (Memory Invocation & Context Archive): A governance schema for AI context management. Defines how context should be structured, trusted, scored, and handed off across sessions.

Anchor Item: A context item that cannot be dropped under any memory pressure. Eviction priority: 0. Later parts explain how this is enforced at the schema level.

Semantic Collapse: A pattern introduced in later parts of this series. A JSON Schema is applied to an LLM as a runtime contract rather than as a validator.

Fail-Closed Gate: An admission rule that excludes a context item if it fails any defined threshold. No exceptions. Formalized in v0.1.7.

1. The Problem

LLMs do not retain state between sessions. Every conversation starts from zero.

For a single task, that is manageable.

For a project maintained across dozens of sessions, it is not.

Such a project accumulates architectural decisions, non-negotiable constraints, protected files, and a decision history explaining why things are the way they are. In that setting, the lack of continuity becomes a structural failure with compounding consequences.

The failure mode is insidious. The model does not fail visibly. It produces well-formed, internally consistent output. What it cannot know is which of its inferences are wrong, because the context it received was incomplete. It cannot identify what is missing. Instead, it fills the gaps silently, drawing on training data rather than on the project's actual history.

Standard responses address parts of the problem. Longer system prompts, RAG pipelines, session summaries. None addresses the governance layer: which context items are authoritative, which are provisional, how they should be weighted against one another, and what happens when memory pressure forces eviction.

This post documents the specification I built to address that layer.

2. Where This Started

For a long time, my workaround was simple and inefficient. Copy a conversation from one AI, paste the whole thing into another, and ask the second one to analyze it. The idea was to get a fresh perspective. To avoid the first model's blind spots by bringing the work to a different context.

It rarely worked cleanly. The second model would inherit the framing, the vocabulary, even the confident wrong assumptions of the first session. It would pick up the conclusion without the reasoning errors that led to it. Then build on both. This pattern is well-documented in multi-model workflows. The receiving model anchors to the original session's assumptions rather than evaluating the content independently. Researchers studying AI review and self-critique systems have noted the same anchoring effect. Same-session review produces systematically worse error detection than fresh-session review.

So I kept looking for a better way to carry context across sessions.

At some point, I came across Claude's memory feature. Not while looking for it specifically. While exploring settings. Claude had introduced persistent memory for paid plans in October 2025, with the stated goal that users shouldn't have to re-explain their context at the start of every session. Anthropic's own description: "your first conversation feels like your hundredth." The export feature produces structured output. Categories, dates, entries, one per line.

Conceptually, this is similar to Claude's Skills system: a modular, reusable layer that carries working state between sessions without rebuilding it from scratch each time. The intent is sound.

I used it. It helped. But something was consistently off.

The output looked like this:

[2025-02-11] - user prefers concise responses
[2025-02-11] - medical AI governance pipeline must never skip the evidence gate
[2025-02-11] - currently exploring whether to add a search endpoint
[2025-02-11] - low-N prohibition is non-negotiable for clinical outputs

Four entries. Same format. Same weight. But they are not the same kind of thing. The second and fourth are hard constraints. In a medical AI context, violating them is not a quality issue. It is a safety issue. The first is a style preference. The third is an open question that may be abandoned next week. The export format has no mechanism to express that difference.

Others in the community have hit the same wall in different ways. From r/ClaudeAI:

A custom MCP memory server still caused the model to skip stored context ~40% of the time
"Notes are lossy. They capture what I thought was important, not what Claude actually found important."

The pattern is consistent. The flat format puts the entire prioritization burden on the user.

The Governance Gap

Anthropic labels the memory import feature experimental, with the explicit caveat that Claude may not always successfully incorporate imported memories. The export is a snapshot. What it cannot express is governance: which items are anchors, which are provisional, what survives memory pressure, and what the source of each item actually was.

At the same time, I had been building AI-SLOP-Detector. A static analysis tool for detecting low-quality AI-generated code. Its core premise: not all signals are equal. Some patterns are weighted more heavily. Some trigger hard blocks regardless of aggregate score. The scoring model is explicit, versioned, and auditable.

The same structure was missing from context management. A flat export has no weights, no eviction rules, no provenance, no trust hierarchy. It is a list. A governance schema is something different.

That gap is where MICA (Memory Invocation & Context Archive) started.

3. The Structural Problem with LLM Context

Language models do not retain information between sessions. This is a known architectural property, not an implementation gap. Every new conversation begins from zero.

For short, self-contained tasks, this is manageable. For long-running engineering projects, it is not. Codebases under active development. Governance systems with accumulated decision history. Architectures with non-negotiable invariants. Each creates a specific and compounding failure mode.

The failure is not that the model performs poorly. It is that the model performs well. Confidently. Using whatever context it was given. That context is almost always incomplete in ways the model cannot detect.

Consider what a project accumulates over months of development:

Type of knowledge	Survives session loss?	Consequence of loss
Current file contents	Partially (if re-provided)	Recoverable
Architecture decisions and rationale	No	Silent regression risk
Constraints that are non-negotiable	No	Violated without awareness
Solutions already tried and abandoned	No	Repeated work, repeated failures
Trust levels of different information sources	No	All context treated equally

The model cannot distinguish between a constraint that is load-bearing and one that is provisional. It does not know which decisions have downstream dependencies. It cannot identify that a suggested refactoring was already evaluated and rej

ected for a reason not present in the current context.

The result: the model fills gaps with plausible inference. Inference drawn from training data, not from project history.

4. Why the Standard Fixes Don't Fully Work

Every developer running a long project with an LLM eventually hits the wall and builds something to address it. The community has been running these experiments for a while now.

The diagram above shows the pattern. Each approach handles one or two dimensions. None handles governance.

Long system prompts are the first instinct. Write everything down, start every session with it. It works until maintaining the prompt becomes a second job. One developer described it precisely: "the scaffolding becomes the work." There is also a structural issue no token count fixes: the "lost in the middle" effect. Models attend well to the beginning and end of long contexts and degrade in between. An architecture constraint buried in paragraph 11 of a 3,000-token prompt may not receive adequate attention regardless of whether it fits in the window.
RAG pipelines handle knowledge injection well. They do not handle governance. Retrieving a paragraph about how a caching layer works is different from the model understanding that this specific caching layer cannot be modified without a deviation log entry. RAG provides facts. It does not provide the weight of facts.
Session summaries are a reasonable manual workaround and the one I used most. The problem: summarization is lossy by design.
Summaries strip the rationale behind decisions. The model gets the conclusion without the reasoning that produced it. When a new edge case appears that challenges an earlier decision, the model has no basis to evaluate whether the constraint still holds. It just follows the summary.
Flat memory exports — including Claude's own export format — do carry context across sessions. That part works. What they cannot express is priority. Which items are non-negotiable. Which are provisional. Which are stale. The burden of sorting that out falls entirely on the user, every time.

The common limitation across all four: they treat context as a document to be read. None treats it as a governed structure where different items have different trust levels, different eviction protection, and different behavior when they conflict.

5. Looking for an Answer

The question was whether anyone had already solved this at the specification level.

The research on LLM memory management is substantial. MemGPT (Packer et al., 2023) introduced the OS analogy: main context as RAM, external storage as disk. Later work extended this into hierarchical architectures and tiered storage models.

A 2025 survey (arXiv:2509.18868) maps the landscape and documents a problem the field had started to name: self-degradation. Naive "add everything" strategies cause memory inflation. Inflation leads to error propagation. The agent performs worse over time. Not better.

The direction is clear: memory needs to be tiered, decayed, and managed. Not accumulated.

What I could not find was a specification for the governance layer. Not for a multi-agent research system. For a single developer maintaining a real project across sessions.

How to express that some items are non-negotiable anchors and others are provisional notes.
How to define eviction behavior a conforming implementation must follow. How to require provenance.
How to version and audit context state the way you version and audit code.

The existing systems were engines. What was missing was a schema.

That is what v0.0.1 attempted. The first version was rough. It got several things wrong. Part 2 covers what those failures revealed.

6. What This Series Covers

That is the problem. MICA is the attempt at a specification-level answer to it.

This is Part 1. It documents the problem and the motivation.

Part 2: v0.0.1. The first schema version, what it defined, what it got wrong, and why those failures revealed exactly the problem this series is trying to solve.

The series runs as long as there is something concrete to document.

Named failure mode from this post: the governance gap. Context systems that store what you said, but not what it meant, where it came from, or how much it mattered.

MICA: Building a Memory Governance Schema (5 Part Series)

My LLM Kept Forgetting My Project. So I Built a Governance Schema.

The Schema Existed. The Model Had No Way to Know.

The Stake Was Governance Outside the Schema. MICA v0.1.5 Pulled It In.

The Model Already Read the README. MICA v0.1.8 Made It a Protocol.

Everyone Was Talking About Context Engineering. Nobody Had Solved Governance.