Connect

What is GRAPH.md?

The document assistants read before writing into your graph, so everything they write follows the same rules.

Every graph has its own way of being written: what counts as one concept, which way a relation points, which topics already exist. Usually that lives in someone's head, where an assistant cannot read it.

GRAPH.md writes those rules down as plain text that both you and an assistant can read and edit. It sits next to files you may already know:

What it gives you

An assistant calls vinc_conventions before its first write in a session and reads GRAPH.md. Every note it writes then follows the same rules: the same node kinds, the same size of concept, the same relation names, the topics you already have. Without it, each session guesses, and you end up with one idea under two names and relations nobody else uses.

Two parts of the file

In the app, the generated region is shown as the read-only Copied part. Each prose heading carries a tag that says how much you can change it: [schema-fixed] is set by Vinc and works this way whatever the file says, [this graph decides] is your own house rule, and [varies by topic] holds examples that differ by field.

Example

A shortened GRAPH.md. The full template has a few more sections and runs to 75 lines.

# GRAPH.md
<!-- vinc-graph-md: 1 · built 2026-10-01 · the store is canonical, this file is a view of it -->

## What this is [this graph decides]
The house style for writing into this knowledge graph. Read it before your first write
in a session. Judging meaning is your job. This file only fixes the conventions.

## Read before you write [this graph decides]
Search first (vinc_search), reuse the ids you get back, and prefer attaching to an
existing concept over creating a near duplicate.

## Node kinds [schema-fixed]
- Concept: one reusable idea. If it will not be reused, do not create it.
- Episode: something that happened (a session, an event). It is tied to a time.
- Decision: what you chose at a point in time, and why. Tie it with `about`.

## How big is one concept [varies by topic]
GOOD "Optimistic concurrency control": reusable, self standing, one idea.
BAD "Database stuff": several ideas in a bag. Split it.

## Relations [schema-fixed]
- relates_to: loose association. Undirected.
- prerequisite_of: A comes before B. The direction carries the meaning.

## Documents [schema-fixed]
Source text goes in through vinc_doc_put and the store keeps the canonical copy.

<!-- vinc:generated start · ... -->
## Domains in this graph
vinc/design (84) · vinc/engineering (212) · vinc/agent (23)

## Ratified vocabulary
node types: playbook
edge types: supersedes
<!-- vinc:generated end -->

## Do not [this graph decides]
- Do not ratify your own proposal. A person does that.
- Do not create a node for something you did not search for first.

Where it lives

• In the graph itself, one per owner. Your personal graph and each team have their own.
• The local graph and the account graph each keep their own. Sync does not carry it across.
• It does not appear in the document list or in document counts.