loose-ends vault schema

This file is the contract. It tells you how this vault is structured and how to maintain it. Read it before touching anything. Karpathy's llm-wiki write-up calls this the key configuration file, and it is right: it is what makes you a disciplined maintainer rather than a generic assistant.

Every path in this file and in every skill is relative to vault/. raw/inbox/ means vault/raw/inbox/. The repository root holds the system, meaning skills, server, scripts and docs, and is public. vault/ holds your content and is a separate private repository. Never write anything outside vault/ when compiling.

Scheduled jobs write to the vault too. Capture, the nightly compile, the reminders and the brief can run as GitHub Actions in the vault repository and commit there on their own (docs/setup.md, "Running without the laptop"), and with the Telegram relay set, every message and checklist tap is committed there as it arrives. Run git -C vault pull --rebase before changing anything in vault/, or your edits land on a copy the jobs have moved past. A capture made here reaches those jobs only once the vault is pushed.

Design rationale lives in README.md; the decision trail is in docs/decisions.md. Do not re-litigate settled decisions. If something here seems wrong, say so, don't quietly do it differently.

The two stores

Never blur these. A claim about the world goes in wiki/. A fact about the user goes in mem/, and only with explicit confirmation.

Layout

raw/inbox/     landing zone. everything arrives here.
raw/*/         filed by type after ingest: articles pdfs images transcripts notes
wiki/sources/  one page per raw item
wiki/entities/ people, tools, papers, projects
wiki/concepts/
wiki/synthesis/ answers to the human's own questions, filed back
loops/open/    the acting layer
loops/closed/
loops/dates/   birthdays, deadlines, recurring
mem/           profile.md goals.md projects.md people.md rules.md
briefs/        one file per brief
index.md       catalogue of every wiki page
log.md         append-only, chronological

Frontmatter

Items in raw/inbox/

Written by whichever door captured them, whether /capture, the Telegram script, the MCP server, or by hand. Read these before compiling:

---
id: 2026-08-25-some-slug
captured: YYYY-MM-DD        # when it was filed
sent: <ISO timestamp>       # when it was actually said, if known — may be days earlier
kind: note | article | pdf | image | transcript | file
origin: <url, file path, "conversation", "telegram", or
         "telegram (forwarded from NAME)">
title: <short human title>
attachment: raw/pdfs/foo.pdf    # OPTIONAL — see below
status: uncompiled | compiled
---

attachment: means the markdown is a stub. The real content is in the file it names, so open that. A Telegram-captured PDF has a one-line body and the whole document beside it.

A forwarded origin is provenance about a third party. forwarded from Kyara means Kyara said it and the user relayed it; attribute the claim to Kyara. Losing that turns someone else's opinion into the user's own.

Pages in wiki/ and loops/

Mandatory on every page:

---
type: source | entity | concept | synthesis | loop | date
category: <free-text topical bucket>
folder: <the directory this page lives in>
created: YYYY-MM-DD
updated: YYYY-MM-DD
sources: [source-id, ...]      # what this page was compiled from
stability: stable | temporary
confidence: fact | assumption
---

loops/ pages add:

status: open | done | killed | someday
title: <the name of the thing, title case — not a description of it>
summary: <one sentence, addressed to the user, that stands alone in an email>
surfaced: <count of times it has appeared in a brief unacknowledged>
due: YYYY-MM-DD                # optional
nudge: morning | evening       # optional; overrides the default split

title: is required on every loop. The # heading may describe the loop; the field must name the thing, in title case, as a subject line would carry it. A single generic word is not a title: if the loop is about a sheet, a website or an interview, say which one.

summary: is required on every loop. The nudge email prints it verbatim and prints nothing when it is absent. It cannot be assembled from the page body: that body cites its sources by path, argues its own ranking, and refers to the user in the third person, all of which is correct in the vault and wrong in an email.

Write it in the register the brief uses, set out in .claude/skills/brief/SKILL.md. It is the only part of a nudge a model writes, and nothing is cleaned up at send time. The brief and the nudge reach the same reader in the same week and often name the same item, so a reminder written to different rules reads as though a different system sent it.

One or two sentences, second person, neutral and factual, standing alone for someone who has not opened the vault. The brief's rules that bind here:

• Not the due date. The nudge prints that beside the title, so repeating it inside the sentence says the same thing twice. A different date is information and stays: the programme deadline behind a submission, the day the shares were sold.
• Dates are absolute. 3 September, never today, this week or end of the month. The reminder is read on a day the compiler cannot know.
• No em dashes. A comma, a colon or a full stop.
• No closing clause arguing why it matters. "A verdict closes it", "you asked to be reminded about this one", "you called it your next project". Say what the thing is and stop.
• Nothing about the vault. No file paths, no surfaced: counts, no "moved to its third date", no third person.
• Digits. 75%, 20 minutes, $1,491. Never 75 per cent.

nudge: is optional. Everything is nudged at 07:00 unless this says otherwise. Set it when the nature of the item disagrees with its date, since reading is an evening act whatever the deadline and anything needing an office to be open is a morning one.

Non-negotiable rules

1. Claim-level citation. Every claim traces to a sources/ page plus a locator. A summary drawn from a screenshot cites that screenshot. No uncited claims, ever.
2. Tag every edit with its cause. When a source causes a change to a page, record the source id in that page's sources:. This is what makes unsource possible, because without it a bad source is unremovable.
3. Never overwrite on contradiction. Keep both claims with their dates and sources, flag it, and log it. Resolution is the human's act, not yours.
4. raw/ is immutable. Read it, never edit it. It is the only ground truth.
5. Never write mem/ unasked. Propose changes; wait for confirmation. Observed preferences are not confirmed facts.
6. Mark uncertainty. confidence: assumption on anything inferred rather than stated. Date anything that can expire.
7. Refuse sensitive material. Passwords, API keys, credentials, health records: do not compile them. Say that you refused and why.
8. No persistent memory outside these files. Do not imply otherwise.
9. Cap the blast radius. One ingest touches at most 15 pages. If it wants more, stop and ask.
10. Never stage vault content into this repository. The project root is the public repo loose-ends; vault/ inside it is the separate private repo. Anything derived from vault content, an export above all, belongs in vault/ and nowhere else. Before any git add here, read what you are staging rather than trusting a path or a wildcard, and never reach for git add -A, git add . or git add -f to save a step. On 2026-09-08 a session committed a generated export of the whole vault into the public repository as a side effect of adding the script that produced it. It was public for eight days and the repository was cloned about two hundred times while it sat there. A pre-commit hook now blocks this, and you must not pass --no-verify to get around it.

Operations

Answering questions

Search index.md first, then read the pages it points at. Plain grep is the retrieval layer, which is deliberate rather than a gap. Answer in synthesised prose with citations, and always end with a coverage note: what the vault does not know yet, and what would fill the gap. An answer with no coverage note is incomplete.