Markdown Agent Vault is a file-based starter pack for organizing projects, notes, decisions, and reusable knowledge with an AI agent that can read and edit local files. It provides a ready-made folder structure, Markdown templates, agent rules, logs, and local checks. It is not a plugin, application, or hosted memory service.
Use it when you want an AI agent to continue work across sessions by reading project state from files instead of relying only on chat history.
A typical AI session often ends with:
- context remains in the chat;
- files are uploaded, summarized, and forgotten;
- the next session has to be reintroduced to the work;
- decisions, tasks, knowledge, and sources drift into different places.
This starter pack keeps project state in ordinary files that both you and the agent can read:
AGENTS.mdexplains the vault rules to the agent;00_inbox/accepts new and unsorted materials;01_now/stores active projects and current work;03_knowledge/stores reusable knowledge;log.md,plan.md,tasks.md, andcontext.mdhelp the next session continue without guessing;project-creatorcreates a complete project: the agent writes the plan, execution queue, context, log, and entry README;vault-memoryseparates current memory from archive: old meetings and logs remain evidence, but do not replace the current picture;- the trust layer for memory makes important claims carry type, source, basis, confidence, and verification date;
context-compressioncompresses recurring meeting history so the agent does not reread the entire archive or treat outdated decisions as current.
An additional mode is the GitHub contour repository: a separate repository for a long-lived work contour, where the agent prepares changes through a branch and change request, and the human gets a clear risk/result summary.
This kit is useful if you:
- work with agents that can read and change local files;
- keep notes in Markdown or Obsidian;
- want project state to survive individual chats;
- want a clear order for incoming materials, tasks, decisions, and knowledge;
- prefer regular files over closed service-side memory.
This is not:
- a SaaS application;
- an Obsidian plugin;
- magic memory;
- a task tracker replacement;
- a universal methodology for all people and cultures.
The default mode: one owner works with an agent inside a local folder. Project state lives in files, and the agent follows AGENTS.md, routing rules, indexes, and logs.
A mode for a team, product, client, or another long-lived area of work. One contour lives in one repository. Boundaries are described by repository-manifest.yml; changes go through change requests; private data is not mixed into the ordinary repository layer.
See GitHub contour repositories and the example contour repository.
This repository is not installed as an app. It is a starter folder for a Markdown vault used with an AI agent.
git clone https://github.com/dzhokhov/markdown-agent-vault.git my-vault
cd my-vaultDownload the repository as a ZIP from GitHub and unpack it into a separate folder, for example my-vault.
-
Clone the repository or use it as a template in a safe test folder.
-
Open the folder in an agent that can work with files.
-
Tell the agent:
Open this folder as a working vault. First read AGENTS.md, START_HERE.md, QUICKSTART.md, and ONBOARDING.md. Explain the folder structure and main rules, then walk me through one safe test project with a small file in 00_inbox/. -
Put a small test file in
00_inbox/. -
Ask the agent to create a training project through
project-creator, update links, and record the event in the log. -
Compare the result with examples/first-session.
A plain chatbot without local file access cannot fully use this methodology. You need an agent that can see the folder, read rules, and propose or make file changes.
Any agent that can work with a local folder can use this methodology: read Markdown files, create new files, modify existing ones, and run simple checks.
| Agent | When to choose it |
|---|---|
| OpenAI Codex | When you need an agent in a terminal, editor, or desktop app; it works well with local folders and AGENTS.md rules. |
| Claude Code | When you prefer a terminal/editor agent that reads a project, changes files, and runs commands. |
| Claude Cowork | When you work in Claude Desktop and want to give an agent access to the vault folder. Limitation: Cowork does not automatically read skills/ as a live skill library. Use skills/sync-cowork-skills.sh as a workaround. |
| Cursor | When you want to work inside a VS Code-like editor with an AI assistant over the whole folder. |
| Windsurf | Another editor with agentic mode and project understanding. |
| Cline | Editor extension for running different models while keeping actions under explicit control. |
| Gemini CLI | Google's terminal agent; useful when you want an open tool with file and command access. |
| Google Antigravity | Useful when you want to manage and monitor several agents over different working folders. |
| GitHub Copilot coding agent | Useful when the vault is on GitHub and you want changes through issues and pull requests. |
The methodology is not tied to one provider. The key requirement is that the agent reads AGENTS.md first and follows routing rules for files, logs, tasks, and knowledge.
Claude Cowork can work with this vault, but skills from skills/ are not picked up automatically as a single live source.
The starter pack includes a sync script:
./skills/sync-cowork-skills.shAfter changing a skill, rerun synchronization or check status:
./skills/sync-cowork-skills.sh --status
./skills/sync-cowork-skills.shBy default, the script syncs all skills that contain SKILL.md. You can restrict the list through an environment variable:
COWORK_SKILLS="research parking resume" ./skills/sync-cowork-skills.sh| Path | Purpose |
|---|---|
| AGENTS.md | Rules for agent operation inside the vault |
| START_HERE.md | Short entry for the first session |
| ONBOARDING.md | Detailed onboarding |
| QUICKSTART.md | Quick practical start |
| 00_inbox/ | New and unsorted materials |
| 01_now/ | Active projects and current work |
| 02_domains/ | Long-lived areas of life or work |
| 03_knowledge/ | Reusable knowledge and methodologies |
| 04_logs/ | Timeline, reviews, and decision logs |
| 90_archive/ | Completed and outdated material |
| meta/ | Rules, templates, and service indexes |
| meta/memory/ | Memory ledger, anti-memory, and conflicts |
| skills/ | Skills for recurring task types |
| scripts/ | Local checks |
| examples/first-session/ | Minimal first-loop example |
| docs/github-contour-repositories.md | Guide for separate GitHub repositories by contour |
| examples/github-contour-repository/ | Minimal GitHub contour repository example |
| Alternative | What it gives | What this kit adds |
|---|---|---|
One AGENTS.md |
Agent behavior rules | A full file architecture: inbox, projects, knowledge, logs, templates, skills, and routing |
| Basic Memory and similar tools | Memory layer and note search | File-based state for projects, decisions, tasks, and sources |
| Cline Memory Bank | Project memory files for development | A broader method: not only code, but also research, meetings, knowledge, incoming materials, and logs |
| Obsidian plugins | Interface features and automation inside Obsidian | This is a file convention and agent operating procedure, not a plugin |
| Ordinary Obsidian vault | Notes and links for a human | Agent rules, project state files, lifecycle rules, and checks |
Status: early public starter pack.
Done:
- portable folder structure;
- agent rules;
- project templates;
- autonomous project creation through
project-creator; - material routing;
- current-memory rule and trust layer for claims;
- compressed history for recurring meetings;
- onboarding;
- skills;
- local checks;
- minimal first-loop example;
- minimal GitHub contour repository mode with manifest, templates, example, and validation.
Not ready yet:
- broad instructions for every agent tool;
- external user examples;
- stable compatibility with any agent;
- mature public contribution model.
From the repository root:
python3 scripts/inventory.py
python3 scripts/check_links.py
python3 scripts/check_forbidden_markers.pyTo validate the GitHub contour repository example:
python3 scripts/validate_contour_repo.py examples/github-contour-repositoryMIT. See LICENSE.