How to Build an Agentic Context Management System with Folder Structures and Markdown Files

The Problem With Context Isn’t AI — It’s Architecture

Most people trying to build serious agentic workflows hit the same wall: their AI agents start forgetting things, repeating mistakes, or producing inconsistent output across different clients or projects. The instinct is to blame the model. But the real problem is usually upstream — there’s no coherent system for managing what the agent knows and when it knows it.

Agentic context management is the practice of structuring the information your agents load, when they load it, and how it gets organized so they can operate reliably across complex, multi-threaded work. And the most durable approach most practitioners have landed on is deceptively simple: markdown files in folders, with explicit rules about what gets loaded when.

This isn’t a hack. It’s a genuine architectural pattern. Let’s walk through how to build one that actually scales.

---

Why Markdown and Folders Work Better Than You’d Think

Before getting into the specifics, it’s worth understanding why this approach works at all — because it looks almost too simple.

Context Is Just Structured Text

Every piece of information your agent needs — client preferences, project constraints, tone guidelines, historical decisions, tool instructions — is ultimately text. And text doesn’t need a database or a custom API to be useful. What it needs is to be findable, loadable, and scoped correctly.

Markdown files give you human-readable, version-controllable, portable structured text. You can write them in any editor, diff them in git, and load them programmatically with a single file read operation. There’s no schema migration, no ORM, no vendor lock-in.

Folders Encode Relationships for Free

A file at clients/acme/tone-guidelines.md is already telling your system something about what it contains, who it belongs to, and when it’s relevant — before you’ve read a single line. The path is a form of metadata.

This matters because when you’re building context injection logic for agents, you need a reliable way to decide what to load. A well-designed folder structure makes those decisions almost mechanical.

The OS Metaphor Is Accurate

The “agentic OS” framing from the meta description is apt. An operating system doesn’t store all of memory in RAM at once — it pages in what’s needed, when it’s needed. Your context management system should work the same way. The folder structure is your file system. The markdown files are your pages. The loading rules are your page-fault handler.

---

Designing a Folder Structure for Agentic Work

The right folder structure depends on your use case, but there’s a general pattern that works well for most professional and enterprise contexts, especially when you’re managing multiple clients or projects.

The Core Hierarchy

Start with three top-level concerns:

/context
  /global
  /clients
  /projects

Global holds anything that’s always true: your agent’s persona, general operating principles, output formatting rules, safety constraints. This gets loaded on every run.

Clients holds everything scoped to a specific client: their preferences, brand voice, key contacts, historical context, decisions made, and constraints. This gets loaded only when working on that client.

Projects holds everything scoped to a specific initiative: current status, open tasks, relevant background, dependencies. This gets loaded only when working on that project.

Going Deeper

Within each client folder, break things down further:

/clients
  /acme
    overview.md
    tone-guidelines.md
    key-contacts.md
    decisions-log.md
    constraints.md
  /northstar-corp
    overview.md
    tone-guidelines.md
    ...

Within each project:

/projects
  /q3-campaign
    brief.md
    status.md
    assets-inventory.md
    open-questions.md

The names matter less than the consistency. Pick a naming convention and stick to it. Your loading logic will reference these paths directly, so inconsistency creates bugs.

An Optional Layer: Workflows

If you run the same type of task repeatedly — say, writing weekly reports, reviewing code, or generating client summaries — add a /workflows folder:

/workflows
  /weekly-report
    instructions.md
    output-template.md
    example-output.md
  /code-review
    instructions.md
    criteria.md

These files act as procedural memory. Your agent loads them at the start of a specific task type, not a specific client or project. This separation keeps your context clean.

---

Writing Context Files That Actually Work

Having the right files in the right folders means nothing if the files themselves are poorly written. Context files are a form of prompt engineering, and the same principles apply.

Structure Within Files

Every context file should open with a brief declarative header — one to three sentences that state exactly what this file is and when it applies. This serves two purposes: it helps you when editing, and it reinforces context for the model that loads it.

Example:

# ACME Corp — Tone Guidelines
**When to use:** Load this file for any written output intended for or about ACME Corp.

ACME's brand voice is direct and professional without being cold. Avoid exclamation points. 
Prefer second-person ("you") over passive constructions...

Then follow with the actual content, using headers to organize different aspects.

What Belongs in a Context File

Good context files contain:

• Persistent facts — things that don’t change run to run (brand colors, tone guidelines, technical constraints)
• Accumulated decisions — choices that were made and should be preserved (“client requested we always use Oxford commas”)
• Current state — what’s true right now (project phase, open tasks, last status update)
• Explicit rules — things the agent must always or never do in this context

Bad context files contain:

• Full conversation histories (use a separate memory system for that)
• Redundant information that’s already in another loaded file
• Vague or aspirational statements (“be helpful and creative”)
• Everything — overstuffed context is almost as bad as no context

Keep Files Short Enough to Scan

Aim for 200–600 words per file. If a file is growing beyond that, it probably needs to be split. A clients/acme/overview.md that contains everything about ACME will start causing problems — the agent treats all loaded context with roughly equal weight, which means critical constraints can get buried under background fluff.

---

Building the Loading Rules

This is the part most people skip, and it’s the most important part. The folder structure and files are just storage. The loading rules are the actual operating system.

The Three Tiers of Loading

Think in terms of three tiers:

1. Always-load (global) — These files are injected into every agent invocation. Keep this tier small: 3–5 files maximum, each under 300 words.

2. Context-load (triggered by task) — These files are loaded based on what the agent is working on. When a task involves Client A’s project, load Client A’s files and that specific project’s files. Nothing else.

3. On-demand (retrieved by agent) — Some context is too voluminous or too conditional to pre-load. Let the agent retrieve it when needed, via a lookup tool or function call. Historical decision logs, large asset inventories, and reference documents often live here.

Writing the Loading Logic

In most agentic workflow systems, loading logic lives in the workflow orchestration layer. You pass context to the agent at the start of each run based on metadata about the task.

A simple pseudo-logic:

always_load = read_files("/context/global/*.md")

if task.client:
  client_context = read_files(f"/context/clients/{task.client}/*.md")

if task.project:
  project_context = read_files(f"/context/projects/{task.project}/*.md")

if task.workflow_type:
  workflow_context = read_files(f"/context/workflows/{task.workflow_type}/*.md")

system_prompt = join([always_load, client_context, project_context, workflow_context])

This is the whole thing. It’s not clever — it’s predictable, which is what you want.

Using a Context Manifest

For more complex setups, add a manifest.json to each folder that explicitly lists which files to load and in what order:

{
  "always": ["overview.md", "constraints.md"],
  "on_demand": ["decisions-log.md", "assets-inventory.md"]
}

This gives you fine-grained control without hardcoding file names into your orchestration logic. When the folder grows, you update the manifest — not the code.

---

Managing Multi-Client Work Without Cross-Contamination

Multi-client work introduces the biggest risk in agentic context management: context bleed. An agent that knows about Client A’s pricing strategy should never accidentally apply that knowledge when working on Client B’s output.

Hard Boundaries Through Scoping

The folder structure creates hard scopes. But you need to enforce them in your loading logic too. The simplest rule: never load files from two different client folders in the same agent run.

If a task genuinely requires cross-client reasoning (say, a report that benchmarks multiple clients against each other), that’s a separate context layer — probably a /projects context that explicitly includes summarized, non-sensitive information from each client.

The Decisions Log Pattern

One of the most valuable context files you can maintain is a decisions-log.md for each client and project. It’s a running chronological list of decisions made and the reasoning behind them.

Format:

## 2025-06-01 — Switched headline format
Changed from title case to sentence case on all deliverables. Client requested this 
in review meeting. Applies to all future output.

## 2025-05-14 — Avoided competitor mentions
Client confirmed they do not want any competitor names in public-facing content, 
even in comparative framing.

This file gets loaded on demand (not always), but agents can retrieve it when they need to understand the history of a project. It also serves as an audit trail — which matters a lot in enterprise AI workflows.

Version Control Everything

Your context folder should live in a git repository. This gives you:

• A history of every change to any context file
• The ability to revert if an edit causes regressions
• A clear record of when information was added or changed
• Collaboration support if multiple humans are managing context

This isn’t optional for serious work. Treat your context files like code.

---

How MindStudio Handles Agentic Context Management

If you’re building this kind of system from scratch in a custom stack, the folder structure and markdown approach above gives you a solid foundation. But if you want to skip the orchestration plumbing and focus on the actual agent logic, MindStudio’s visual workflow builder handles much of this architecture out of the box.

In MindStudio, you can build agents that load different blocks of context conditionally — based on variables, incoming task metadata, or user inputs — without writing the file I/O logic yourself. The workflow canvas lets you wire context injection steps directly into your agent’s execution path, with explicit control over what gets passed to the model at each stage.

For multi-client work specifically, MindStudio’s workflow variables make it straightforward to parameterize context loading: one workflow, different context payloads depending on which client or project is active. You can connect to Notion, Airtable, or Google Drive to pull in live context files rather than maintaining a local folder structure if that fits your setup better.

The platform also supports autonomous background agents that run on a schedule — which is useful if you want context files to be refreshed or summarized automatically as projects evolve.

You can try MindStudio free at mindstudio.ai.

---

Common Mistakes to Avoid

Even with a good architecture in place, a few patterns reliably cause problems.

Over-Loading Global Context

The global tier is tempting to expand. Every time you notice an agent making a mistake, the instinct is to add a rule to the global context. Resist this. A bloated global context creates noise that competes with more specific, relevant context. Fix client-specific problems in client files, not global ones.

Stale Context Files

Context files become a liability if they’re not maintained. A status.md from three months ago can actively mislead an agent. Build a habit of updating relevant files at the end of each work session, or use an agent to help you maintain them.

Missing the On-Demand Tier

Most systems have global and context-load tiers, but skip on-demand retrieval. This forces you to either over-load context upfront or accept that agents won’t have access to historical information. The on-demand tier — even if it’s just a simple lookup tool — meaningfully extends what your agents can access without bloating every prompt.

Conflicting Instructions Across Files

If global/rules.md says “never use bullet points” and clients/acme/tone-guidelines.md says “use bullet points for all lists,” the agent will behave inconsistently. Audit for conflicts regularly, especially when the global context and client context grow independently.

---

Frequently Asked Questions

What is agentic context management?

Agentic context management is the practice of controlling what information an AI agent has access to during a given task — what gets loaded into its context window, when, and from where. A well-designed context management system prevents agents from working with stale, irrelevant, or contradictory information, which is one of the most common causes of poor agent output.

Why use markdown files instead of a database?

Markdown files are plain text, which means they’re portable, human-readable, version-controllable, and require no infrastructure to read or write. For context management specifically, they’re easy to edit by hand, easy to load programmatically, and easy to inspect when something goes wrong. Databases add overhead without adding much benefit for this use case — unless you’re operating at very large scale or need full-text search across thousands of files.

How much context should you load per agent run?

As little as possible while still giving the agent what it needs. A good target is 1,000–3,000 tokens of injected context for most tasks. If you’re regularly exceeding 5,000 tokens of pre-loaded context, your files are probably too large or you’re loading too many. Move less-frequently needed information to the on-demand tier.

How do you handle context updates when information changes?

The best approach depends on how frequently information changes. For slow-changing information (brand guidelines, client preferences), manual updates work fine — just treat it like maintaining documentation. For faster-changing information (project status, open tasks), consider having an agent update the relevant files at the end of each work session, or pulling from a live source like Notion or Airtable instead.

Can this folder structure work with existing AI tools like Claude, GPT, or custom agents?

Yes. The folder structure and markdown files are model-agnostic — they’re just text files. Your orchestration layer (whatever system calls the model) handles loading the files and injecting them into the prompt. This pattern works with any model or agent framework: LangChain, CrewAI, custom Python scripts, or no-code platforms.

What’s the difference between context management and memory management?

Context management controls what information is available in a single agent run — it’s about what gets loaded into the prompt before the model starts working. Memory management is about persisting information across runs — capturing what happened in one session so it’s available in future sessions. A complete agentic system needs both. The folder/markdown approach described here serves context management primarily, though a decisions log is a lightweight form of persistent memory.

---

Key Takeaways

• An agentic context management system is fundamentally a set of rules about what information to load, when to load it, and how it’s organized — markdown files in a structured folder hierarchy solve this problem simply and durably.
• Use three loading tiers: always-load (global), context-load (client/project-specific), and on-demand (retrieved by the agent when needed).
• Keep individual context files short (200–600 words), well-labeled, and specific — avoid cramming everything into a single file.
• Prevent cross-contamination in multi-client work by enforcing strict scoping in your loading logic and never loading two clients’ files in the same run.
• Version control your context folder like code — it’s a live system that evolves with your work.
• Tools like MindStudio let you implement this architecture without building the orchestration layer from scratch, with conditional context injection built directly into the workflow canvas.