Plainspace

A plain-text format for giving an AI agent durable knowledge and multi-step workflows as a folder of markdown files — readable by humans, but written for agents first.

No framework. No schema registry. No required tooling. If you can cat a file you can read it; if you can git clone a repo you can ship it.

Plainspace merges two prior ideas and adds one:

• Knowledge as files — from the Open Knowledge Format (OKF): a directory of markdown + YAML frontmatter, self-describing, permissive to consume.
• Workflows as folders — from Interpretable Context Methodology (ICM): numbered stage folders, each loading only the context it needs, with a human review gate between stages.
• Agent-first authoring (the addition) — every machine-actionable fact lives in structured form so an agent can act from frontmatter + tables alone, while human-only explanation is segregated (not deleted) so you can still review and debug.

Not the same thing as AGENTS.md. That standard tells a coding agent how to behave in a repo (build, test, conventions). Plainspace is the agent's knowledge + workflow store — a different concern. The two compose fine: keep your AGENTS.md at the repo root, keep your Plainspace workspace in a folder.

Why

Most "agent-readable" markdown is really written for humans: narration, transitions, restating. An agent pays tokens to read all of it. Plainspace flips the default — the agent reads frontmatter → structured blocks → stop, and anything that exists only for a person sits at the bottom under a # Notes heading the agent skips. You keep observability; the agent stops paying for it on the hot path.

But note the trap Plainspace is built to avoid: the biggest token cost is loading what you don't need, not verbosity. So the format's first rule is load less (read the map, open one file), and it explicitly forbids compressing prose into a cipher — LLMs decompress invented shorthand at the cost of reasoning and accuracy. Density here means cutting narration, not cutting language.

How much does load less actually save? A reproducible benchmark (bench/) answers the same 40 questions three ways over the same corpus (tokens ≈ chars/4):

strategy	avg tokens/query	accuracy
naive tree-crawl	1876	100%
index-first (read the map, open one file)	644	100%
rung-2 FTS (psindex search)	73	100%

Same answers, ~26× fewer tokens — and the gap widens with corpus size (crawl scales with the whole tree, index-first with the map, search with the query). Run it yourself: python3 bench/bench.py.

What's in here

plainspace/
├── SKILL.md                       # The format spec + the protocol an agent follows.
├── MEMORY.md                      # Optional profile: long-term memory (capture→consolidate→recall→forget).
├── SETUP.md                       # One-time, agent-executable setup (optional harness hooks). Ask-first.
├── PATTERNS.md                    # Optional conventions (stage-state offload). Not required.
├── BOOTSTRAP.md                   # Drop-in bootstrap to point any agent at a workspace.
├── CHANGELOG.md  CONTRIBUTING.md  LICENSE
├── tools/
│   ├── psindex.py                 # rung 2: SQLite FTS index, stdlib only (build/search/map/stats/check).
│   ├── pssearch3.py               # rung 3: hybrid BM25+embeddings, optional backend, falls back to FTS.
│   └── test_psindex.py            # stdlib unittest suite.
├── bench/                         # reproducible token benchmark.
├── design/scoring.md              # design note (proposal): per-fact scoring with decay.
└── examples/
    ├── sample-workspace/          # A complete, generic worked example.
    │   ├── index.md               #   the map — read first
    │   ├── log.md
    │   ├── knowledge/             #   concepts (durable knowledge / "factory")
    │   │   ├── style-guide.md     #     audience: both
    │   │   └── glossary.md        #     audience: agent
    │   ├── 01_collect/            #   a pipeline stage
    │   │   ├── _stage.md          #     contract: inputs / process / outputs
    │   │   └── output/            #     per-run artifacts ("product")
    │   └── 02_draft/
    │       ├── _stage.md
    │       └── output/
    └── memory-workspace/          # Worked example of the Memory profile.
        ├── index.md               #   map + "# Core" always-loaded block
        ├── inbox/                 #   cheap captures
        ├── knowledge/             #   consolidated facts (status/source/confidence)
        ├── archive/               #   superseded facts — excluded from recall
        └── 90_consolidate/        #   recurring maintenance stage

Quickstart

1. Read SKILL.md — it's the whole spec, ~1 page, and it practices what it preaches.
2. Open examples/sample-workspace/index.md and follow the links. That's exactly how an agent traverses it.
3. Copy examples/sample-workspace/ somewhere and start editing. Replace the example concepts and stages with your own.

Long-term memory (optional profile)

MEMORY.md turns a workspace into an agent's long-term memory by adding the missing lifecycle: capture (zero-ceremony inbox/) → consolidate (a recurring stage promotes captures into knowledge/, supersedes contradictions) → recall (a 3-rung ladder: maps → grep/FTS via tools/psindex.py → semantic) → forget (archive/, excluded from recall). Files stay the source of truth — every index is derived and disposable. Behavior is identical at 10 files and at 50,000; only the substrate under the ladder changes. See examples/memory-workspace/.

The "no required tooling" promise holds: rung 1 (maps + grep) needs nothing, and everything else — the index script, a scheduler for consolidation, the git audit trail, harness hooks (SETUP.md) — is an opt-in accelerator. Skip them all and the workspace still works; you only lose determinism, never data.

Use it with your agent

Plainspace is conventions, not code. It's deliberately agent- and provider-agnostic — it works with any agent on any inference backend that can read files: Claude, Codex, Hermes, OpenClaw, GPT, open-weight models, an n8n/LangChain pipeline, whatever. Nothing here assumes a specific model or vendor.

• In a skill-aware system (e.g. Claude Code, or any agent that loads skill files): drop SKILL.md in as a skill. It triggers on knowledge/workflow tasks.
• Anywhere else: paste the contents of BOOTSTRAP.md into your agent's system prompt and point it at the workspace folder.

Adapt it to your structure

The format is minimally opinionated. To fit your domain you only need to:

• Invent your own type values (Supplier, API, Runbook, Customer…). They aren't registered anywhere; consumers tolerate unknown ones.
• Organize knowledge/ however your domain wants — subfolders are free.
• Add as many numbered stages as your workflow has, or drop the stages entirely if you only need a knowledge base.
• Add any extra frontmatter fields you like; conformant consumers preserve unknown keys.

A workspace is conformant if every non-reserved .md has parseable frontmatter with a non-empty type. Everything else is soft guidance.

Attribution & license

Plainspace is an independent synthesis. It builds on the ideas of OKF (Apache-2.0, Google Cloud) and ICM (MIT, Van Clief & McDermott) without copying their text. Credit to both.

This project is released under the MIT License © 2026 Dorunaitsu. Fork it, rename the format, change the conventions — keep the notice and that's the only ask.