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.

    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.

    PluginUse
    OmnisearchFull-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-OmnisearchPuts an Omnisearch search box inside a note (a code block), with results listed in the note. Useful on a matter home page.
    UNITADEOpens other extensions (for example .txt) as notes, so you can browse and edit them in the vault.
    CSV LiteOpens and edits .csv files as tables.
    HTML ReaderOpens .html files, for example agent-built tables and dashboards.
    TemplaterTemplates with automatic folder mapping (item 6).
    Bases (core) or DataviewTables and queries over front-matter fields (item 9).
    Frontmatter OperatorBulk-edits front matter across notes (add, rename, or delete a field), with undo. Use it when you change a set's fields.
    Folder BacklinksLink to a folder from a note, and see which notes link to each folder.
    Batch Copy Names and PathsCopies the paths of selected notes, to paste into an agent prompt.
    TerminalRuns the agent in a pane inside Obsidian.
    Enhancing ExportExports notes to Word or PDF for sending. Install Pandoc for it, the same program used for Word conversion (item 8).
    Timeline ViewShows notes on a timeline by a date field, for chronologies.
    Task TreeNested checklists with roll-up progress, for work plans and closing checklists.
    Simple Mind MapMind 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:

    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."

Markdown: guide.md · For agents: llms.txt