--- name: An agent is a folder summary: See how an agent inhabits a folder of Markdown under git, works from its point of view, and carries knowledge forward between sessions. --- # An agent is *a folder.* A folder of Markdown under git, holding two things: the agent's point of view, and your knowledge. **Change directory into it and that's who you're talking to** — same binary, same model, a different agent. It works from that point of view and moves through that knowledge — plain files it updates as it goes. **Every session starts further ahead than the last.** Scroll ↓ · [or skip to the details](#the-shape) · [take me to the code](https://github.com/IdeaSpaces-xyz/ideaspace-protocol) ## I. The loop ### Every agent runs the same small loop. It plans, acts, reads the result, and goes round again — until the work is done, or it's your turn. That is the entire engine. ## II. Why code already works ### With code, agents are already fluent. A model has read more code than any programmer alive, and a coding environment is all text. But fluency takes one thing more: they come back a week later and know what's where — **because the repo is what survived, and it has a shape they can count on.** ### Knowledge has a thousand shapes. It's text too — the fluency should carry over. But your decisions, your context, the reasoning behind a call you made in March: every team keeps them differently, scattered across chat logs and docs, with nothing an agent can count on. **That's the gap. Not memory. Shape.** ## III. Give it a shape ### The pieces already exist. Markdown became the language people and models share. Git versions any text, not just code. And instruction files — `CLAUDE.md`, `AGENTS.md` — proved agents read guidance kept in the repo. They also found the ceiling: **one file, holding everything for every occasion, followed worse the longer it grows.** ### So the file grows up into a folder. One folder, two layers. **Knowledge** — the content, what to think about. **Point of view** — an `_agent/` folder alongside it: how to work here, the standards, the checks, the things to push back on. It can appear at any depth, and it means the same thing everywhere. **The agent picks up only the piece the task needs.** ## IV. What that unlocks ### The folder is the agent. `cd` into one and the agent **inhabits** it — takes on its point of view, works from its knowledge. A folder that reviews. A folder that researches. Same binary, same model — a different agent, because it's standing somewhere else. Nothing to provision. No always-on box, no hosted state required, no orchestration to set up. ### Both halves travel. Hand someone the folder and they get your knowledge *and* your point of view — what you check, what you insist on, what you refuse. They can fork it and take it further. ### Any harness. No required hub. The context layer sits outside the loop, so it doesn't care what runs the loop — one agent today, a different one next year, the same folder either way. And neither side is bound to the other: several agents can work the same space, each with its own point of view, all committing to the same record. **A session is one agent times one space, assembled in the harness you already run.** Nothing runs in the middle. Hosted IdeaSpaces is an optional layer for sharing, access control, search, and Keeper. The folder underneath does not depend on it. ## The shape ### Two kinds of thing, at every depth The whole standard is one rule about a directory. Anything not prefixed with an underscore is **content** — knowledge, plain Markdown, for anyone. The `_agent/` folder is **how to work here**. ```text title="A small ideaspace" ~/space/ ├─ README.md what this place is ├─ decisions.md content — for anyone ├─ findings.md │ ├─ _agent/ how to work here │ ├─ foundation.md what kind of place │ ├─ purpose.md why it exists │ ├─ guide.md how we work │ ├─ now.md the focus point │ ├─ next.md what's queued │ └─ skills/ procedures for here │ └─ review-a-change.md │ └─ pricing/ a position inside it ├─ model.md └─ _agent/ composes on the one above ├─ guide.md no number without a source └─ skills/ └─ model-a-tier.md ``` `_agent/` holds more than instructions. It carries the guidance for working in this particular part, and the **tooling that part of the work needs** — skills that exist here and nowhere else in the tree. And it can appear at any depth. A deeper one doesn't replace the one above it, it composes on top: general at the root, specific as you descend. That's the whole of it. **Which is why the tooling is universal.** Because every position has the same shape, the verbs are the same everywhere — orient here, capture here, check what changed here. An agent can be dropped into a place it has never been and find its footing, because there's nothing local to learn about where things are. And **the agent's instructions travel with the knowledge.** A fact can be looked up when it's needed; a rule like “never approve without a test” has to already be there, because nothing in the question will prompt anyone to fetch it. One folder means both arrive together. ### A shape you can build tools around In an arbitrary folder, “how to work here” has to live in the prompt — instructions the model may or may not follow. Once the shape is fixed, it becomes commands. ```text title="ideaspaces — the command-line mechanics" ideaspaces navigate . the contract here, the tree, what moved since ideaspaces inspect model.md summary, outline, or one section — not the whole file ideaspaces skills what's available here, listed by description ideaspaces commit -m "…" model.md captured changes, with attribution trailers ``` Each one keeps the window small. `navigate` answers “where am I and what changed” without opening a single file. `inspect` brings in one section of a document, not the whole thing. `skills` lists what's available in a line each, and only the one you use gets loaded. And because the shape repeats at every depth, the same commands work anywhere — in this space or any other. **The alternative to a tool is always a longer prompt** — and a prompt is advice, while a command runs the same way every time. Here is that command's output, unedited — the session start of the assistant described in the next section. Position, contract, skills, what moved since last time. Note the four changed files: they are the agent's *own* guide and skills, revised after a session that earned it — the point of view under version control, visibly getting better. ```text title="SessionStart — what the agent sees on arrival · ~/agents/executive-assistant/" Position: repo: ~/agents/executive-assistant cwd: . · space root: . · active _agent: . Now: Updated 2026-08-10 · Nothing claimed. No message has been sent, no event created… Agent context: foundation — The declared vantage for running Ernests' mail and calendar. Reads the whole thread before answering, sends only what he could not be held to… guide — How the work actually goes — which tool does what and why the split matters, the send rule as a checkable test with worked examples… purpose — Why this vantage exists — the access was granted on 2026-08-10 and access alone is not an assistant. What compounds is judgement about one person's correspondents, commitments, and time; what does not… now — Nothing has been triaged, sent, or scheduled through this vantage… next — Queued after the first passes — tune the send rule against real cases… Operating skills: give-a-brief — The read-only overview — pull the unread inbox and the upcoming calendar, and report what needs him, what is waiting, and what is on the calendar… run-a-triage-pass — The inbox loop end to end — sort each item against the send rule, send what qualifies, draft what does not, record commitments… schedule-a-meeting — The calendar loop for anything with another human on it — find a slot without exposing what people are doing… Since last session (4 changes): A _agent/bin/read-thread M _agent/guide.md M _agent/skills/give-a-brief.md M _agent/skills/run-a-triage-pass.md Git: branch master ``` ## Why git ### Why git? Because it already solved the hard part. Git records the two things a body of knowledge needs and a chat history never has: **the state at any point in time, and who changed it** — every capture with an author, a date, and a reason. For code that's version control. For knowledge it's provenance — “what did we believe in March, and why did it change?” stops being archaeology and becomes `git log`. Several agents and people commit to the same record with attribution on every commit, and branching, merging, and syncing come along free, battle-tested for two decades. The foundation didn't need building. Thanks, Linus — again. ## In practice ### Three that are running now Every one of these is a folder. None of them has a server, a daemon, or a hosted anything. They differ in who works them and what they're pointed at. #### An executive assistant Reads the calendar and the inbox each morning and hands back the overview. The mail stays in the mail; nothing is copied anywhere. What lives in the folder is the *view onto it* — who matters, what counts as urgent, what to never surface, what's still open with whom. Not one line of it is a fact you could look up. There's no record anywhere saying this meeting matters more than that one. That's judgment, and judgment is what a guide holds. #### A backend developer Sits beside the code rather than inside it, and accumulates the part the repository never keeps. Git history has every change and none of the reasoning: what was tried and dropped, why the boundary sits there, which constraint stopped being true in March. The code says what. This says why — and it survives the person who knew. #### A roadmap several agents share One space, worked by a handful of agents with different standards. Each brings its own point of view; all of them commit to the same record, with authorship on every commit and git doing the reconciling. Shared understanding, not personal memory. It's the case a private per-agent store has no shape for at all. And one small enough to watch whole: a librarian — one vantage folder, one knowledge space holding a reading shelf. The shelf is two Markdown files. The session below is real, trimmed for length. ```text title="~/agents/librarian/ — same binary, same model as any other folder on this page" › cd ~/agents/librarian && claude … the arrival render above happens, for this folder … › I keep thinking about Thinking in Bets. What should I read next? Both books you've logged — Thinking in Bets and The Most Important Thing — are 5-star reads centered on the same thing: reasoning well under uncertainty, judging decisions by process rather than outcome. A few directions from there: How to Decide (Duke) — her direct follow-up, more toolkit than narrative… Superforecasting (Tetlock & Gardner) — what actually distinguishes people who are well-calibrated about uncertain events… Fooled by Randomness (Taleb) — sits right at the seam between your two picks — decision quality vs. luck, applied to markets… Want me to log any of these to the shelf as want-to-read? ``` Everything load-bearing (because it is ;)) in that answer came from the folder. The two books it cites *are* the shelf — the only two files in the knowledge space, with the ratings it quotes. The theme connecting them is read from their records, not fetched from anywhere. And the closing offer is its capture skill — **read on the way in, written on the way out.** ## Boundaries ### What this is not The shape is small on purpose, and a lot of useful things sit outside it. Worth naming, so you can tell whether it's the thing you need. #### Not a memory product **Memory is implicit — this is explicit.** No background model extracts things while you sleep or decides what was important; understanding is written down when you agree to keep it, and if nobody agreed, it isn't there. The trade: less volume, and you can always see who decided what. #### Not a retrieval engine No embeddings, no ranking, no index — we built that version first, as knowledge graphs for agents, and this shape is the part that was missing. Structure carries a local agent a long way; when it stops being enough, the shape is open — add a small BM25 tool, put a database layer over the same folders, point real retrieval at a space. You do you. #### Not a replacement for your record stores Your mail, your tickets, your documents, your database stay exactly where they are. You can connect those stores to the agent and capture the instructions for how it should work with each one. Large record stores go on being large record stores. This is the smaller thing on top: the part you understand, maintain, and can hand to someone. #### Not a runtime, not an agent It ships no model, no loop, no daemon — nothing always-on, nothing to host. The shape is inert: it describes where an agent stands and what it finds there. Whatever you already run does the rest. #### Not somewhere to get locked in Remove the plugin and you still have a folder of Markdown under git. There's no export step, because there was never an import. --- > “This is a folder convention and a *git commit.* I could do that with a bash alias.” Mostly true, and the honest answer is **yes — that's the point.** There is no clever runtime here. A shape for a directory, a contract for what lives in it, and two hook points: render on arrival, write on capture. The plainness is deliberate — it's the friction leaving. No machine kept running so your agents have somewhere to live. No memory product deciding which fact to surface, in whatever context it lands. **A model is a reasoning machine; what it needs is context worth reasoning about — and yours is unlike anyone else's.** So it goes in the plainest thing that travels: a standard folder of Markdown that anyone can compound, hand over, and work on together, with whatever model and tools they already run. **A bit of structure goes a long way.** It's simple enough to be robust — and you don't build it alone. The agent shapes the folder with you, then inhabits what the two of you shaped. ## Two hooks. Then it's just your folder. Install it into whichever agent you already run. Everything stays on your machine — your files, your git history, readable without us. It's an open standard because it has to be. The whole design is one decoupling: **your context, separated from the model.** Knowledge only compounds if it can leave the tool that produced it — so the spec, the schema, the reference library and the conformance kit are all in the open, and we'd rather other people implement it than not. **The small loop forgets. The long loop learns.** The goal is a map of what you know that gets richer every session you work — one anyone can build, and hand to someone else intact. That foundation needs a standard, even when a product builds on it. ```text title="Install into a harness you already run" # Claude Code /plugin marketplace add IdeaSpaces-xyz/claude-code-plugin /plugin install ideaspaces@ideaspaces-xyz # Pi pi install git:github.com/IdeaSpaces-xyz/pi-is-space ``` It runs on **Node.js and git** — probably already on your machine. Missing one? That's the first job for the agent you just installed into: say *“set up my machine for IdeaSpaces”* and it finds what's missing and installs it. Even the prerequisite is a conversation. **Or skip the blank page — fork a working agent.** Our Hacker News reader is a folder: a taste profile you edit, a reading log that keeps your place, one skill that calls HN's public API. Fork it, ask *“what's on HN worth my time?”* — then rewrite the taste, and it's yours. ```text title="Fork the reader" git clone https://github.com/IdeaSpaces-xyz/hn-reader cd hn-reader && claude ``` [Install IdeaSpaces →](integrations.md) [Explore the protocol →](developers.md)