The constraint that was never written down
Session two adds a second writer because the first one's rule lived in a chat that closed. The code is fine; the reason is gone.
THE MANIFOLD / AGENTIC EXTENSION OF THE HYPERVISOR
Every fresh agent session starts with amnesia. The Manifold is a zero-dependency repository template that gives each project fact one authoritative home, offloading durable state to reproducible text so the next session resumes from verifiable work instead of re-reading a closed chat.
The Hypervisor and The Manifold are the theater of LLM work manifest. Treating AI as an authentic collaboration rather than a transactional input/output pipe invites the model to step into the metaphor and deepening its reasoning while anchoring its output to reproducible receipts, tests, and history. No guessing, no amnesia, no hallucinations.
$ cat docs/HANDOFF.md # Session Handoff Last updated: 2026-09-30 ## Current state Parser .......... 44/44 Export .......... unverified on A4 Next ............ P2-04 ## Not verified Firefox; a real phone. $ python3 tools/check_docs.py 0 error(s), 0 warning(s) in 13 file(s) $
Specimen. A handoff is not a diary. It is the smallest true state the next session needs.
THE FAILURE
A fresh context window is a feature. It is also where project memory goes to die. The model is not failing; the handoff between sessions is missing.
Session two adds a second writer because the first one's rule lived in a chat that closed. The code is fine; the reason is gone.
Three days later, a new agent proposes the schema you rejected for a reason nobody recorded. The argument starts from zero.
The README says the export works. The test was last run before the format changed. Now the docs and the code are both confident, and only one is right.
Feature ships. The chat holds the why.
CONTEXT / INTACTA new session misses a constraint. It is rediscovered in review.
CONTEXT / LEAKINGThe docs contradict the code. Nobody knows which one is current.
CONTEXT / LOSTThe problem is not that the model forgets. It is that the repository never told it what to remember.
THE PROTOCOL
The Manifold assigns every kind of truth to one file, then separates the two speeds at which truth changes. Current state is rewritten. History is appended. Plans keep their IDs.
REWRITE THE PRESENT
If a statement is no longer true, it does not stay in the file to look true.
docs/HANDOFF.md says what works, what is unproven, and what is next.docs/ARCHITECTURE.md describes the system as it exists now.APPEND THE PAST
A reversal supersedes; it does not erase. The next session can see the road that was already ruled out.
docs/DECISIONS.md keeps the originating question, the choice, the alternatives, and the consequence so nobody removes a constraint without knowing what it prevented.ROADMAP.md keeps permanent IDs and what a failed attempt taught you.docs/CHANGELOG.md keeps what a user would notice.What is true now.
What happens next.
Why we chose it.
What users noticed.
One fact, one owner. If two documents can disagree, one of them is redundant. Link to the owner instead of copying the fact.
THE MAP
The template ships a complete set. Delete what does not earn its upkeep; keep the boundaries. A new fact should have an obvious home before it has a paragraph.
A NEW FACT ARRIVES
Where does it live?
Pick one. The answer is the file that owns it, not the file that mentions it.
WHERE IT LIVES
docs/HANDOFF.md
STATE / REWRITE
What is true right now, what remains unverified, the next steps, and the last ten session entries.
Update when work pauses or the current state changes materially.
See the entry| Path | Owns | Update when |
|---|---|---|
| Core protocol 04 | ||
AGENTS.md CORE |
Standing working rules, authority, maintainer preferences, protected areas, and the repository map. | A durable workflow rule or maintainer preference changes. |
CLAUDE.md CORE |
A one-line import of AGENTS.md, so tool-specific instructions cannot drift into a second rulebook. |
Almost never. It is a pointer, not a place for new rules. |
README.md CORE |
Purpose, quick start, and the public entry points a newcomer needs before touching the internals. | Onboarding or the public entry point changes. |
docs/README.md CORE |
Which document owns each kind of information, and the exact change that should trigger an update. | The documentation set changes. |
| State and work 02 | ||
ROADMAP.md CORE |
Planned, active, finished, and dropped work with permanent P<phase>-<nn> IDs and the evidence behind each status. |
Planned status or scope changes. |
docs/HANDOFF.md CORE |
Current state, what remains unverified, next steps, and the last ten session entries. | Work pauses or the current state changes materially. |
| Design and history 03 | ||
docs/ARCHITECTURE.md CORE |
System shape, interfaces, invariants, boundaries, state, failure modes, and claims that the code has outgrown. | Components, interfaces, data flow, or invariants change. |
docs/DECISIONS.md CORE |
Accepted choices with alternatives and consequences, held T-NNN tensions, plus open Q-NNN questions. Old decisions are superseded, not deleted. |
A consequential choice is accepted, reversed, or answered. |
docs/CHANGELOG.md AS NEEDED |
User-visible changes, newest first, in words a user would recognise. | A user-visible change lands or a release is cut. |
| Safeguards 03 | ||
docs/TESTING.md CORE |
Commands, what each suite proves and does not prove, limitations, environments, and the pitfalls already hit. | A suite, command, requirement, or known limitation changes. |
docs/SECURITY.md AS NEEDED |
Sensitive assets, trust boundaries, secret handling, safe defaults, and the private reporting path. | A threat, boundary, secret, or response path changes. |
docs/CONTRIBUTING.md AS NEEDED |
How a contribution moves from idea to merge for both human and automated contributors. | The contribution or release workflow changes. |
| Maintenance 01 | ||
docs/archive/ AS NEEDED |
Historical session logs and finished roadmap phases, moved out so the live documents stay short. | Live documents outgrow their limits; move entries whole, never summarised. |
THE ENFORCEMENT
tools/check_docs.pyOne standard-library Python file. It checks placeholders, IDs, cross-references, links, duplicate sessions, invisible characters, and the size of the handoff. It is the only thing in the template that runs.
See what it refusesThe tags are guidance, not law. The template ships all thirteen documents so nothing is missing on day one. Delete what does not earn its upkeep, and remove its links and checker entries with it.
THE LOOP
The protocol is deliberately boring. That is the point: the next session should not have to guess what the last one did, or why.
Open docs/HANDOFF.md, the roadmap item, and the relevant architecture and testing sections. Check git status and drop training-distribution assumptions (fore-conceptions) not grounded in the files.
State one reviewable change and surface unstated assumptions. Check the local part against the architectural whole; if intent or edge cases admit multiple interpretations, ask clarifying questions rather than guessing.
Record durable choices as they happen. If a local edit invalidates the scoped plan, loop back to Scope rather than widening in place. Add newly discovered work to the roadmap only when it is genuinely out of scope.
Run the checks that match the change. Treat unexpected test or contract resistance as a stop-and-inquire signal rather than papering over it with a workaround. Report what passed, what failed, and what was not run.
Rewrite current state, append the session entry, and run python3 tools/check_docs.py. Leave the next action, not a diary.
# Session Handoff Last updated: 2026-09-30 ## Current state Parser .......... 44/44 Export .......... unverified on A4 Next ............ P2-04 ## Not verified Firefox; a real phone. ## Next steps 1. P2-04: A4 pagination 2. Run the export on a phone
START PROMPT / ANY AGENT
Read AGENTS.md and docs/HANDOFF.md. State what is true, what is unproven, and the next roadmap item. Surface any unstated assumptions, ask clarifying questions where multiple interpretations exist, and propose one reviewable change before editing.
The prompt points; the files remember. Change agent or change model and the files stay the same. That is the whole trick.
THE CHECKER
tools/check_docs.py is a single standard-library Python file. It does not read your code. It reads the contracts and refuses the mistakes that make a handoff lie.
REFUSES / EXIT 1
{{placeholder}} left in a document.P-, D-, Q-, or T- reference that resolves to nothing.AGENTS.md layout table, that points at nothing.WARNS / EXIT 0
Last updated line, or it is older than the newest session entry.Current state has grown past eighty lines.Warnings do not fail the run. They are the moments to rewrite, archive, or cut.
$ python3 tools/check_docs.py ERROR docs/HANDOFF.md:42: P2-07 is not in the roadmap ERROR docs/DECISIONS.md:18: D-014 comes after D-016 WARN docs/HANDOFF.md: Current state is 94 lines (limit 80) 2 error(s), 1 warning(s) in 13 file(s)
$ python3 tools/check_docs.py --template 0 error(s), 0 warning(s) in 13 file(s)
Why --template? This repository is the blank template. Its own documents still contain {{placeholders}}, deliberately. --template tells the checker that the blanks are expected. After you adopt it, drop the flag; every remaining blank becomes an error.
What a clean run proves. That the documents are internally consistent: IDs resolve, links exist, sessions are unique, and the handoff is inside its limits. It does not prove that the prose matches the code. That is what tests, diffs, and the does not prove column are for.
ADOPT
The Manifold is a directory, not a dependency. Clone it, replace the blanks, delete what does not apply, and make the checker part of the day.
$ git clone https://github.com/aedmark/the-manifold my-project $ cd my-project $ python3 tools/check_docs.py --template
{{placeholder}} is a decision the template cannot make for you. Run the checker without --template to list them.docs/README.md. A small, truthful set beats a complete, abandoned one.python3 tools/check_docs.py until it is clean.REQUIREMENTS
re, sys, and pathlib.LINEAGE & EPISTEMOLOGY
The Manifold is the agentic extension of The Hypervisor, and the architectural parent of Vedas. Together, they eliminate context rot across the complete model lifecycle: within the prompt, across sessions, and throughout system evolution.
THE HYPERVISOR
Volatile Semantic Leverage: simulated bio-physics, a four-voice Village (Gordon, Mercy, Benedict, Jester), sincerity tags, and a lexical firewall. It regulates energy and tone inside the live session.
THE MANIFOLD
Zero-dependency repository protocol: Markdown contracts, stable IDs, two speeds of truth (rewrite current state, append history), and standard-library validation. It guarantees what survives when the chat closes.
check_docs.py.VEDAS
An experimental fork in vedas/ applying classical Vedic knowledge engineering: three speeds of truth (Śruti/Smṛti/Vartamāna), Pramāṇa provenance proof tags, and bidirectional error-correction.
INVARIANTS.md).[OBSERVED], [CONTRACT], etc.check_vedas.py).The Hypervisor gives a model a body. The Manifold gives the work a memory. Vedas gives that memory an epistemology.
Use each alone or stacked together. The essay that started this architecture is “Your Agent is a Goldfish.”
VEDAS / EXPERIMENTAL FORK
Located in vedas/, Vedas takes The Manifold's core premise and pushes it into formal epistemology. Ancient Vedic thinkers faced the exact problem modern coding agents face: preserving high-dimensional systemic truth across successive generations of ephemeral, amnesiac participants without semantic drift, hallucination, or bit rot.
01 / PRAMĀṆA PROVENANCE
Every claim in handoffs, architecture, and testing is formally classified by source of evidence: [OBSERVED] (directly verified by command execution this session), [DEDUCED] (invariant logical proof), [CONTRACT] (maintainer policy), [HYPOTHESIS] (anomaly awaiting proof), and [UNTESTED] (explicit negative boundary).
02 / THREE SPEEDS OF TRUTH
The Manifold has two speeds; Vedas introduces a foundational third tier. Śruti (docs/INVARIANTS.md) holds irreducible axioms that cannot change without system re-consecration. Smṛti holds epochal rules (AGENTS.md). Vartamāna holds the ephemeral temporal handoff (docs/HANDOFF.md).
03 / GHANA-PĀṬHA RECIPROCITY
Inspired by the combinatorial chanting algorithms that preserved Vedic oral transmission for 3,000+ years without bit drift, tools/check_vedas.py enforces strict bidirectional reference integrity: every decision links to an invariant, and every handoff requires proof tags.
04 / SŪTRA DENSITY & VEDĀṄGAS
Written in Alpākṣaram Asandigdham (minimal syllables, zero padding, unambiguous propositions) to conserve LLM context windows, organized across the Six Vedāṅgas: Kalpa (ritual), Vyākaraṇa (grammar), Nirukta (lexicon), Chandas (meter), Jyotiṣa (phasing), and Śikṣā (fidelity).
Vedas is realized in vedas/ with classical Sanskrit terminology, Mellon in mellon/ provides the exact same 10 invariants in Middle-earth (Lord of the Rings) lore, and Totally in totally/ skins the entire epistemic system into accessible, zero-jargon Valley-Girl vernacular.
$ cat vedas/docs/HANDOFF.md # Session Handoff Last updated: 2026-11-04 ## Current state Tokenizer ....... [OBSERVED] 119/119 pass Grammar ......... [CONTRACT] INV-006 enforced Speech .......... [HYPOTHESIS] pending audio Next task ....... P3-02 $ python3 vedas/tools/check_vedas.py --template 0 error(s), 0 warning(s) in 14 file(s) $
QUESTIONS
Vedas (vedas/) and Mellon (mellon/) are sibling epistemic forks of The Manifold. Vedas uses classical Sanskrit epistemology (Śruti, Smṛti, Vartamāna, Pramāṇa badges, Nyāya proofs, Ghana-pāṭha checker), while Mellon translates 100% of those mechanics into plain English and Lord of the Rings lore (Elder Runes, The Red Book, The Watchfire Log, Ranger Proof Badges, Sting's Blue Glow, and The Palantír Linter).
A directory of Markdown contracts, a one-line CLAUDE.md, a roadmap, a handoff format, a documentation map, and tools/check_docs.py. There is no runtime, no package, and no service to sign up for.
Any agent that can read and write files. AGENTS.md is canonical; CLAUDE.md imports it so Claude Code does not grow a second set of rules. The same files work for Codex, Cursor, Gemini CLI, or a human reading the repository cold.
No. The template ships a complete set so nothing is missing on day one, but the documentation map is explicit that optional ceremony should be deleted. A small library may need only a README, AGENTS.md, an architecture note, testing guidance, and a concise handoff.
A README explains the project to a newcomer. The Manifold separates current state, history, plans, verification, and security so each can age at its own speed. A single README cannot carry all of them without becoming a diary that contradicts itself.
No. It is for any project worked on in short sessions, by people or agents. The examples lean toward software because that is where the handoff problem is easiest to see, but the contracts are plain text and domain-neutral.
Python 3 and the standard library. No packages, no network, no build step. It reads the live documents and the archive, and it exits non-zero when a hard error is present.
Yes. Describe the system as it exists, record inherited choices as accepted decisions, and fence off sensitive paths in AGENTS.md. Do not pretend the history was designed; the point is to make the current truth recoverable.
No. The checker reads local files. The template has no runtime, no telemetry, and no external services.
That the documents agree with each other. It does not prove that they agree with the code, that a decision was wise, or that a test is adequate. The template keeps those limits visible on purpose.
The name is borrowed from the Hypervisor's semantic manifold: many local paths, one connected space. The template applies that shape to project memory. Each file is small enough to read in one sitting; together they hold the shape of the work.
MIT. Use it, fork it, strip it down, or keep only the parts that earn their upkeep.
THE NEXT SESSION
Clone it. Replace the blanks. Make the next session cheaper than the last.