# Entity vault workflow

> GBrain-compatible entity dossiers with compiled truth and append-only timelines, scaffolded via starter packs and maintained through MCP write and checkpoint tools.

- Repository: sashimikun/open-knowledge
- GitHub: https://github.com/sashimikun/open-knowledge
- Human docs: https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e
- Complete Markdown: https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/llms-full.txt

## Source Files

- `docs/content/workflows/entity-vault.mdx`
- `packages/server/src/mcp/tools/workflow.ts`
- `packages/server/src/mcp/tools/discover-body.ts`
- `packages/server/src/mcp/tools/checkpoint.ts`
- `packages/server/src/mcp/tools/history.ts`
- `packages/cli/src/commands/seed.ts`
- `packages/core/src/templates/template-format.ts`

---

---
title: "Entity vault workflow"
description: "GBrain-compatible entity dossiers with compiled truth and append-only timelines, scaffolded via starter packs and maintained through MCP write and checkpoint tools."
---

The `entity-vault` starter pack scaffolds a GBrain-compatible Markdown vault of typed entity dossiers—`people/`, `companies/`, `meetings/`, `concepts/`, `originals/`, and `media/`—each with folder frontmatter, `.ok/templates/`, and a bundled pack skill. Open Knowledge is the cockpit layer: agents create and update dossiers through MCP `write` and `edit`, humans review in the editor, and `checkpoint` plus `history` capture project-wide restore points over git-backed attribution.

## Dossier model

Every durable dossier in `people/`, `companies/`, and `concepts/` splits into two zones separated by a `--- timeline ---` sentinel:

| Zone | Location | Mutation rule |
| --- | --- | --- |
| Compiled truth | Above `--- timeline ---` | Rewritable synthesis; update when evidence changes your current understanding |
| Timeline | Below `--- timeline ---` | Append-only dated bullets; never edit existing entries |

Timeline bullets use a parseable shape agents and external indexers can rely on:

```markdown
- **YYYY-MM-DD** | source | @author — evidence. Confidence: direct note.
```

Route new facts deliberately: change **compiled truth** when the synthesis shifts; append a timeline bullet when the entry is raw evidence. Meeting notes in `meetings/` and originals in `originals/` stay verbatim—agents extract entities from them into dossiers rather than rewriting the source.

<Note>
The pack id is `entity-vault` (display name **Personal CRM**). There is no `gbrain` pack alias—interop is a Markdown shape contract, not a bundled engine.
</Note>

## Open Knowledge vs optional GBrain

| Layer | Open Knowledge | Garry Tan's `gbrain` (optional) |
| --- | --- | --- |
| Markdown files | Creates, edits, reviews, templates, folder guidance | Imports/syncs as source material |
| Human correction | WYSIWYG/source editor, activity attribution, version checkpoints | Sees corrections after import/sync |
| Agent writes | MCP `write`, `edit`, `links`, `checkpoint`, `search`, `exec` | Separate GBrain MCP/skills if installed |
| Search/retrieval | Project search and link-graph tooling | DB-backed embeddings, hybrid retrieval, graph automation |
| Interop contract | Plain Markdown + Git | `gbrain import` / `gbrain sync --repo` |

Open Knowledge does not replace `gbrain`. The entity vault ships the Markdown half; `gbrain` is an optional indexing and automation layer over the same files.

## Scaffold the vault

<Steps>
<Step title="Initialize the project">

Run `ok init` if the project is not already initialized. See [Initialize a project](/initialize-project).

</Step>
<Step title="Seed the entity-vault pack">

<CodeGroup>

```bash Seed into default vault/ subfolder
ok seed --pack entity-vault
```

```bash Seed into a custom subfolder
ok seed --pack entity-vault --root my-vault -y
```

```bash Preview without writing
ok seed --pack entity-vault --dry-run
```

</CodeGroup>

The pack's `defaultSubfolder` is `vault/`. Omit `--root` on a TTY to accept the suggested subfolder; pass `-y` in non-interactive runs.

</Step>
<Step title="Verify layout and skills">

Confirm folders, root files, and templates landed. `ok seed` installs `open-knowledge-pack-entity-vault` next to the platform skill for each wired editor (Claude Code, Cursor, Codex).

</Step>
</Steps>

:::files
your-project/
└── vault/                          # defaultSubfolder: vault
    ├── USER.md                     # user profile for briefings
    ├── SOUL.md                     # agent persona / values
    ├── ACCESS_POLICY.md            # 4-tier privacy model
    ├── HEARTBEAT.md                # operational cadence
    ├── log.md                      # append-only work log
    ├── people/
    │   └── .ok/
    │       ├── frontmatter.yml
    │       └── templates/person.md
    ├── companies/
    ├── meetings/
    ├── concepts/
    ├── originals/
    └── media/
:::

Each typed folder carries `.ok/frontmatter.yml` (visible in `exec` listings) and a starter template under `.ok/templates/`. Template resolution walks up the folder tree; see [Folders and templates](/folders-and-templates).

## Document shape

A person dossier instantiated from the `person` template follows this structure:

```markdown
---
type: person
title: Jane Founder
created: 2026-05-12
author: mike
tags: [person]
---

## Compiled truth

Co-founder and CEO of [[companies/jane-co|Jane Co]]. Met through
[[people/alex-seed-investor|Alex Seed Investor]].

--- timeline ---

## Timeline

- **2026-05-12** | [[meetings/2026-05-12-jane-founder-coffee|coffee meeting]] | @mike — Jane described Jane Co's agent-runtime observability wedge. Confidence: direct note.
```

Compatibility rules:

- Document frontmatter carries `title:` and `type:` (`person`, `company`, `concept`, `meeting`, `original`, `transcript`).
- Prefer path-qualified wikilinks when entity identity matters: `[[people/jane-founder|Jane Founder]]`, `[[companies/jane-co|Jane Co]]`.
- Meeting filenames follow `YYYY-MM-DD-<slug>.md`; frontmatter includes `date` and `attendees:` aligned with `people/` dossier slugs.
- Keep `--- timeline ---` as the explicit separator between compiled truth and timeline.

## Create and update dossiers

MCP document writes require a running Hocuspocus server (`ok start`). Instantiate from a folder template:

<RequestExample>

```json
write({
  document: {
    path: "people/jane-founder",
    template: "person",
    summary: "Stub Jane Founder dossier"
  }
})
```

</RequestExample>

<ParamField body="document.path" type="string" required>
Relative path without extension. Parent folder determines which templates are available.
</ParamField>

<ParamField body="document.template" type="string">
Template name from the parent folder's `templates_available` menu (e.g. `person`, `company`, `meeting`). Mutually exclusive with `content`. Substitutes `{{date}}` and `{{user}}` at instantiation.
</ParamField>

<ParamField body="document.position" type="string">
`replace` (default for new docs), `append`, or `prepend`. Required when the document already exists.
</ParamField>

<ParamField body="summary" type="string">
Optional one-line label (≤80 chars) persisted to git history and visible on the document timeline. Avoid secrets or PII.
</ParamField>

For targeted changes on existing dossiers, use `edit({ document: { path, find, replace } })` to rewrite compiled truth or `write({ document: { path, content, position: "append" } })` to append timeline bullets without replacing the file.

<Warning>
`edit` body find/replace operates on document body only. To patch frontmatter keys, use `edit({ document: { path, frontmatter } })`.
</Warning>

## Meeting → dossier extraction loop

<Steps>
<Step title="Capture the meeting">

```json
write({
  document: {
    path: "meetings/2026-05-12-jane-founder-coffee",
    template: "meeting"
  }
})
```

Fill raw notes with path-qualified links to mentioned people, companies, and concepts.

</Step>
<Step title="Extract entities">

Prompt your MCP-capable agent:

```txt
From meetings/2026-05-12-jane-founder-coffee.md, create or update the
referenced person, company, and concept dossiers using the entity-vault
templates. Append dated timeline bullets. Do not rewrite existing timeline
entries or the meeting note.
```

The pack skill routes: stub missing dossiers, append timeline bullets citing the meeting link, update compiled truth only when synthesis changes.

</Step>
<Step title="Review and checkpoint">

Review agent edits in the editor. Before a large batch of dossier updates, save a restore point:

<RequestExample>

```json
checkpoint({ summary: "Post-meeting dossier extraction" })
```

</RequestExample>

<ResponseExample>

```json
{
  "version": "a1b2c3d4e5f6789012345678901234567890abcd",
  "previewUrl": null
}
```

</ResponseExample>

List checkpoints and per-document history with `history({ document: "people/jane-founder", kind: "checkpoint" })`. Restore a single document with `restore_version({ document, version })` using the 40-char SHA from `history`.

</Step>
<Step title="Commit">

Commit Markdown changes to git. The correction loop depends on inspectable, diffable files—not hidden model context.

</Step>
</Steps>

## Link graph maintenance

Entity vaults depend on path-qualified links between dossiers. Use MCP `links` for audits (requires the collaboration server):

| `links` kind | Use in vault maintenance |
| --- | --- |
| `dead` | Find broken wikilinks; fix or remove (monthly cadence in `HEARTBEAT.md`) |
| `orphans` | Surface disconnected dossiers for adoption or intentional standalone marking |
| `hubs` | Identify highly linked concept or person pages |
| `suggest` | Detect prose mentions missing link syntax |

Run combined audits: `links({ kind: ["dead", "orphans"] })`.

## Optional GBrain interop

If you also run [Garry Tan's gbrain](https://github.com/garrytan/gbrain), point it at the same vault after Open Knowledge writes files:

```bash
gbrain import ~/your-ok-vault --no-embed
gbrain embed --stale
gbrain sync --repo ~/your-ok-vault
```

Recommended model:

- Use `gbrain import ... --no-embed` for the first bulk load.
- Run `gbrain embed --stale` after import or no-embed sync.
- Commit OK edits, then `gbrain sync --repo` for incremental refresh.
- Keep OK as the human inspection and correction surface; keep `gbrain` as the indexing and automation engine.

Root files `USER.md`, `SOUL.md`, `ACCESS_POLICY.md`, and `HEARTBEAT.md` align with GBrain-style agent workflows but are useful even without `gbrain` installed.

## Operational cadence

| Cadence | Action |
| --- | --- |
| After each meeting | Drop raw notes into `meetings/<date>-<slug>.md`; link mentioned entities |
| End of day | Agent extracts entities; append timeline bullets to referenced dossiers |
| Weekly | `links({ kind: "dead" })`; triage orphans vs new entities vs typos |
| Monthly | Audit stale dossiers, empty timelines, compiled truth conflicting with recent evidence |
| Before large agent batches | `checkpoint({ summary: "…" })` for a project-wide restore point |
| With `gbrain` | Commit OK edits, then `gbrain sync --repo` and `gbrain embed --stale` |

Append one dated entry to `log.md` per agent turn that creates or restructures vault content. Reference touched docs as markdown links so backlinks surface in `links({ kind: "backlinks" })`.

## Troubleshooting

<AccordionGroup>
<Accordion title="write fails: Hocuspocus server is not running">

Document creation and replacement route through the collaboration server. Start it with `ok start` before MCP writes. Server-free reads (`exec`, `search` in some modes) still work; see [Collaboration server](/collaboration-server).

</Accordion>
<Accordion title="template not found for folder">

Templates resolve by walking up from the document's parent folder. Run `exec("ls people")` to see `templates_available`. Ensure seed completed and the path matches the folder where the template lives.

</Accordion>
<Accordion title="Agent rewrote timeline entries">

Reinforce the pack skill rule: timeline is append-only. Use `history` + `restore_version` to roll back a dossier, or hand-correct in the editor. Checkpoints capture project-wide state before large extractions.

</Accordion>
<Accordion title="Dead links after stubbing entities">

Run `links({ kind: "dead" })`. Triage into new dossier stubs (agent `write` with template), typo fixes (`edit`), or link removal. The monthly heartbeat in `HEARTBEAT.md` expects this audit.

</Accordion>
</AccordionGroup>

## Related pages

<CardGroup>
<Card title="Karpathy LLM wiki workflow" href="/karpathy-llm-wiki">
Source-grounded counterpart when you need ingest/research/consolidate over external sources instead of entity dossiers.
</Card>
<Card title="Folders and templates" href="/folders-and-templates">
Folder frontmatter, template resolution, and `write({ document: { template } })` instantiation semantics.
</Card>
<Card title="MCP tools reference" href="/mcp-tools-reference">
Full signatures for `write`, `edit`, `checkpoint`, `history`, `links`, and `restore_version`.
</Card>
<Card title="Wire agent editors" href="/wire-agent-editors">
Connect MCP-capable agents and verify the `exec` tool against your seeded vault.
</Card>
<Card title="Editor workflows" href="/editor-workflows">
Review agent dossier edits, timeline panel, and human correction in the web editor.
</Card>
</CardGroup>