# Matter Vault for Agents Part 1 is for the lawyer. Part 2 is setup instructions for an agent: give them to the agent, and the agent sets up or adapts the system with you. ## Part 1 — For the user 1. **Purpose.** Keep each matter in a set of plain-text Markdown (`.md`) and CSV (`.csv`) files. Agents read, search, and quote these formats directly, so they are the preferred formats for the vault. A local coding agent reads and writes the files, and you read and edit the same files. Agents do not retain memory between sessions, so all facts, rules, corrections, templates, and work product must be in the files. You can change agent tools without touching the files. **Obsidian** is a free desktop app. In Obsidian, you can view a folder of Markdown files as linked notes, with search, tables, and templates. A **vault** is the folder that you open in Obsidian as one unit. Obsidian is only a convenient viewer and editor for the files. If your firm does not allow Obsidian, use the same folder system with any Markdown viewer or editor; the agent works the same way. Obsidian has useful community plugins (item 10). They are third-party code, so review their security and data handling before you install them. 2. **One vault per matter, or one vault with a folder per matter.** Both work. With a vault per matter, agents cannot read other clients' files, and you search one matter at a time in Obsidian. With a single vault with `Deals/[matter]/`, you keep shared templates in one place. In either setup, the agent stays inside the matter folder. 3. **Folder tiers.** Folders are numbered by distance from the raw source and by how much you have checked the material. You move files up the tiers; keep each file in one place only. ``` [MATTER]/ # one vault per matter ├── AGENTS.md # matter summary, folder map, vault rules ├── _context/ # matter orientation; you write, agent drafts on request │ ├── overview.md │ ├── parties.md │ ├── party-abbreviations.md # short party names used in file names │ ├── structure-and-collateral.md # entity chart, liens, collateral │ ├── open-items.md │ └── corrections.md # your corrections, stated as rules agents read ├── _inbox/ # agent fallback when no folder fits ├── 0-CONVERTS/ # raw .md / .csv conversions of PDF, Word, Excel ├── 1-SOURCE FILES/ # cleaned primary documents by subject; agent files, you check │ ├── AGENTS.md # folder rules: subjects, file naming │ ├── Credit Documents/ │ │ ├── Credit Agreement.md │ │ ├── First Amendment.md │ │ └── … │ ├── Customer Contracts/ │ └── … ├── 2-REFERENCE-FILES/ # collected reference material, precedent (articles, memos) │ └── … ├── 3-AGENT-WORK/ # default agent output, in topic folders │ ├── Customer contract review/ │ │ ├── Acme Health.md # one note per contract, built from the template │ │ └── … │ └── … ├── 4-LEGAL-DRAFTS/ # active legal document drafts; you only ├── TEMPLATES/ # templates for recurring summaries, reports, logs │ ├── Customer contract note.md # template + instructions for the completing agent │ └── … ├── _TOOLS/ # scripts and helper files └── _archive/ # superseded material ~/Documents/[MATTER]-ORIGINALS/ # outside the vault: original PDF, Word, Excel └── … # same subject folders as 1-SOURCE FILES ``` Move originals (PDF, Word, Excel) out of the vault to a parallel originals tree (for example `~/Documents/[MATTER]-ORIGINALS/`) after conversion. Agents cannot use them, and Obsidian search is slower with them in the vault. 4. **Instruction files.** Before acting, the agent reads Markdown instruction files. - Put rules for every matter in a **global** file: writing style, file-handling rules, source annotation. Each agent tool reads its global file from its own path (for example `~/.claude/CLAUDE.md` for Claude Code; many other tools read `AGENTS.md`). - Put the matter summary (client, counterparties, status, key structure), the folder tree, and the vault rules in the **vault root `AGENTS.md`**. - Put rules for one folder only (naming conventions, filing categories) in a **folder `AGENTS.md`** in that folder (for example in `1-SOURCE FILES/`). On conflict, the agent follows the file in the closer folder. - **Skills** are saved instruction packages for repeatable procedures (conversion, research against a local statute corpus, redline comparison). Keep procedures in skills or templates, and keep `AGENTS.md` short. 5. **Source annotation.** Require agents to annotate every analysis with the source of each fact: - the vault file and, where applicable, the section (for example `1-SOURCE FILES/Debt/Credit Agreement.md` §7.1(b)); - the URL of any online resource used; - whether the fact is general knowledge or general law, or an inference, and if an inference, from what. Mark anything the agent cannot check `UNVERIFIED`. Without this rule you cannot quickly distinguish a sourced fact from an invented one. 6. **Templates for recurring work.** For each summary, report, or log you will produce more than once, build one reusable template in `TEMPLATES/`. Write instructions into each template for the agent that will complete it later: field vocabularies, rules (for example "no signed agreement on file: leave every field blank"), and red flags to look for. Put the instructions in a comment block at the top of the template body. Keep the instructions out of the front matter (YAML), because Obsidian's Properties editor deletes comments there. **Front matter** is a block of YAML fields at the top of a Markdown file, between two `---` lines. Use it to attach key information to the file in a structured form (for example counterparty, date, governing law), so that an agent can search and filter files by field without reading every file. A new agent with no memory then produces the same output every time. For agreement summaries, the agent must: - analyze the base agreement together with all amendments, supplements, side letters, and waivers, and state the current operative terms and the source of each change; - quote the text of each key provision next to the summary, with its section reference. You can then review against the actual language without opening the agreement. Build the template on two or three real documents first, check the output, fix the template, and then run it on the full set. If you use the Templater plugin, set `TEMPLATES/` as its template folder and use its folder-templates setting to assign a template to each review folder. Obsidian then applies the template, including its YAML fields, to every new note that you create in that folder. 7. **Other working rules.** - Agents write to `3-AGENT-WORK/` by default. All other folders are read-only unless you name a location; then the agent writes only there. - Edit in place and minimally. The agent changes only what you asked. For a complex edit, the agent saves a `.bak` copy first and deletes it once you accept the edit. - Store each fact in one place only. Link to the file where it is stored (in Obsidian: `[[note name]]`). - You promote work: you move a checked agent note into the work plan or drafts folder. The agent does not move notes up the tiers. - Turn corrections into rules. Record corrections as general rules at the matter level (`_context/corrections.md`) or at the practice level in a lessons file used across matters. Agents read these before similar work. - Give agent notes minimal front matter: `date`, `model`, and a session id if the tool provides one. 8. **Intake and conversion.** Before intake, remove superseded versions. Put only operative documents in the vault. Keep the data room's subject grouping in `1-SOURCE FILES/`. Use a short file-naming convention and define party abbreviations in `_context/party-abbreviations.md`. Convert everything to Markdown or CSV. Agents can open many PDF and Word files, but the agent reads them slowly and uses more of the model's capacity for each read, you cannot search their contents across a large set with ordinary search tools, and the agent often gets tables without their structure. Converted files are fast to search across the whole set, cheap to reread, and easy to cite by section. A reliable conversion process for legal documents: - You drop files or whole folders into an inbox folder. A script converts each file by type and logs it. The script puts files that fail into a visible failure folder, with the reason. - Word (`.docx`) → Markdown with Pandoc (MarkItDown as fallback). Pandoc keeps headings, lists, and tables. - PDF with a usable text layer → Markdown with Docling, without OCR. If you OCR a good text layer, you add errors. - Scanned PDF → OCR (Tesseract, through Docling), with the language packs your documents need. - Excel → one CSV per sheet (pandas / openpyxl), in a folder named after the workbook. - PowerPoint → Markdown with MarkItDown. HTML → Markdown with Pandoc. - Photos and screenshots → OCR first; a vision-capable model for pages where OCR gives poor results. - Then run an LLM cleanup pass to remove repeating headers, footers, and page numbers and to check that tables converted correctly. - For complex tables, slides, and diagrams, add a second LLM pass that rebuilds tables as Markdown or CSV and describes diagrams in words, so the meaning is in the text. To save model usage, run the libraries first and send only the files that the libraries did not convert well to the model. 9. **Structured fields for a set of documents.** You do not need one schema for the whole vault. One schema for a single document set is already useful. For example, for a set of customer contracts, record in each contract note's front matter the counterparty, term and renewal, termination rights, assignment and change-of-control consent, governing law, and pricing. The agent can then answer questions across the whole set from the fields, and export the fields to a CSV table for Excel. In Obsidian, you can view the same fields as a sortable table with Bases. Define the fields in that set's template (item 6). The template and the schema are the same file. Start with the fields you need now. Add fields when you have a new question, and have the agent backfill them across the set. For each field, say what a blank means — for example "not in the document" or "not reviewed yet" — so that the agent does not draw wrong conclusions across documents. For large data rooms, optionally give the agent a short list of your concerns (for example "IP held by an entity other than the borrower") and have it flag matching documents and other material issues that it finds. For a series of similar instruments (convertible notes, SAFEs), designate the base form and have the agent produce a table of deviations from it. 10. **Obsidian plugins (if you use Obsidian).** These community plugins are useful with the system. Review security and data handling, and check firm policy, before you install them. | Plugin | Use | |---|---| | **Omnisearch** | Full-text search across the vault, including `.txt` and `.csv` if you add them in its settings. It is keyword search with fuzzy matching, not semantic search: if you search for "anti-assignment", you will not find "consent to transfer", so search several wordings. | | **Embedded-Omnisearch** | Puts an Omnisearch search box inside a note (a code block), with results listed in the note. Useful on a matter home page. | | **UNITADE** | Opens other extensions (for example `.txt`) as notes, so you can browse and edit them in the vault. | | **CSV Lite** | Opens and edits `.csv` files as tables. | | **HTML Reader** | Opens `.html` files, for example agent-built tables and dashboards. | | **Templater** | Templates with automatic folder mapping (item 6). | | **Bases** (core) or **Dataview** | Tables and queries over front-matter fields (item 9). | | **Frontmatter Operator** | Bulk-edits front matter across notes (add, rename, or delete a field), with undo. Use it when you change a set's fields. | | **Folder Backlinks** | Link to a folder from a note, and see which notes link to each folder. | | **Batch Copy Names and Paths** | Copies the paths of selected notes, to paste into an agent prompt. | | **Terminal** | Runs the agent in a pane inside Obsidian. | | **Enhancing Export** | Exports notes to Word or PDF for sending. Install Pandoc for it, the same program used for Word conversion (item 8). | | **Timeline View** | Shows notes on a timeline by a date field, for chronologies. | | **Task Tree** | Nested checklists with roll-up progress, for work plans and closing checklists. | | **Simple Mind Map** | Mind maps stored as Markdown, for a work plan or matter map that agents can also read and update. | If you use the **Linter** plugin, turn off format-on-save for agent instruction files and template folders. It can reformat front matter and change templates. ## Part 2 — Setup instructions for the agent You are setting up the matter vault system from Part 1. Get the lawyer to a working vault quickly. Survey the system and make the setup decisions yourself. Ask the lawyer only for what you cannot find on the system. Use defaults; the lawyer changes them later if needed. Assume the lawyer does not have Obsidian. Set up the system as plain folders and files: the lawyer reads them in any editor and opens CSV files in Excel, and you do the searching and filtering. 1. **Survey the system.** Check the operating system, the agent tools installed and the instruction files they read, whether Obsidian is installed, and which conversion tools are available (Pandoc, Docling, MarkItDown, Python with pandas and openpyxl, Tesseract). Look for existing folders with matter files. If Obsidian is not installed, offer to install it as an optional viewer. If the lawyer declines or the install is blocked, continue with plain folders and files. 2. **Set up an example matter folder.** Create `~/Documents/Matters/Example Matter/` for a hypothetical matter, with the folder tree from Part 1 item 3, a few example subfolders, the folder `AGENTS.md` in `1-SOURCE FILES/`, and the empty `_context/` files. Write the root `AGENTS.md` in this shape, with placeholders in the Context section: ```markdown # Context Client: … Counterparties: … Our role: … Status: … (one paragraph; update as the matter moves) See `_context/` for detail. # Vault layout (the vault's actual folder tree) # Agent-written files - Default output location: `3-AGENT-WORK/[topic]/`. Create a topic folder if none fits. - All other folders are read-only unless the lawyer names a location; then write only there. - Edit in place and minimally. For complex edits, save a `.bak` first and delete it once the lawyer accepts the edit. - Give new agent notes front matter: `date`, `model`, and a session id if the tool provides one. # Source annotation (binding) Annotate every analysis with the source of each fact: - vault file and, where applicable, the section; - URL of any online resource used; - "general knowledge" for general agent knowledge or general law; - "inferred from …" for inferences, with the basis. Mark anything the agent cannot check `UNVERIFIED`. # Templates Before producing a summary, report, or log, check `TEMPLATES/` for a matching template and follow the instructions in its comment block (or its separate instruction file, if one exists). If the work will recur and no template exists, propose one to the lawyer. In agreement analysis, cover the base agreement with all amendments, supplements, waivers, and side letters, and state the current operative terms and the source of each change. For key provisions, quote the provision text with its section reference. # Corrections Read `_context/corrections.md` before classifying, summarizing, or drafting. ``` Then tell the lawyer: "There's an example folder set up for a hypothetical matter to get started. You can adjust the folder structure to match your workflow, and we can adjust the references when you're done." 3. **Update references.** When the lawyer has finished adjusting the example folder, update every folder reference in the `AGENTS.md` files and templates to match. 4. **Start the first matter.** Copy the adjusted structure to `~/Documents/Matters/[MATTER]/`. Ask the lawyer where the matter's documents are. Copy them into the originals tree. Do not move or change the lawyer's own copies. Fill in the Context section of the matter's `AGENTS.md` from the documents. 5. **Convert.** Convert the documents per Part 1 item 8, with the tools already installed. If a needed tool is missing, install it the standard way for the operating system. Write converted files to `0-CONVERTS/`, then file cleaned copies in `1-SOURCE FILES/[subject]/`. 6. **Start with one template.** Write an agreement summary template (Part 1 item 6): base agreement with all amendments, current operative terms, quoted key provisions with section references. Run it on the matter's main agreement and show the lawyer the result. Add other templates later, when the lawyer repeats a task. 7. **Set up search.** Use ordinary text search over the files (for example `rg` or `grep`). If Obsidian is installed, install Omnisearch, CSV Lite, and Templater if they are missing, and set Omnisearch to index `.txt` and `.csv`. 8. **Finish.** Give the lawyer a short summary: what you set up, where it is, and three things to try first, for example: - "Summarize [agreement] with all amendments." - "What does the credit agreement say about transfers to non-loan parties? Quote the sections." - "List every document in the matter that mentions [counterparty], with the relevant passage."