---
title: Entity vault (GBrain-compatible) workflow
icon: LuBoxes
description: A GBrain-compatible Markdown workflow for people, companies, meetings, and concepts. OpenKnowledge is the cockpit/editor/review layer; Garry Tan's gbrain can import or sync the same vault for indexing and automation.
---

An **Entity vault (GBrain-compatible Markdown)** is a Markdown brain organized around typed dossiers: people, companies, meetings, concepts, originals, and media. Each durable dossier has two zones:

1. **Compiled truth** — the current synthesis, rewritten as evidence changes.
2. **Timeline** — append-only evidence bullets, dated and attributable.

OpenKnowledge scaffolds and edits that Markdown. Garry Tan's [`gbrain`](https://github.com/garrytan/gbrain), if you install it, can import/sync the same vault and add its DB-backed retrieval, graph extraction, embedding, and automation. OK does **not** replace `gbrain`; it gives GBrain-style Markdown brains a human cockpit for review, correction, attribution, and Git-visible edits.

## Who this is for

- You want a second brain that tracks **people, companies, meetings, and concepts**, not just source documents.
- You want agents to maintain dossiers while you keep final editorial control.
- You already use `gbrain` and want a visual/editor layer over the Markdown files it indexes.
- You do not use `gbrain` yet, but want a portable GBrain-compatible Markdown shape you can adopt later.

## The division of labor

| Layer | OpenKnowledge | Garry Tan's `gbrain` |
| --- | --- | --- |
| 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 | OK MCP tools (`write`, `edit`, `links`, `checkpoint`, `search`, `exec`) | GBrain MCP/skills if you choose to run them separately |
| Search/retrieval | OK project search and graph tooling | PGLite/Postgres, embeddings, hybrid retrieval, graph/index automation |
| Interop contract | Plain Markdown + Git | `gbrain import` / `gbrain sync --repo` |

## What the pack creates

Pick **Entity vault (GBrain-compatible)** in the starter-pack picker, or run:

```bash
ok seed --pack entity-vault
```

By default the pack suggests a `vault/` subfolder and creates:

```txt
your-project/
└── vault/
    ├── USER.md
    ├── SOUL.md
    ├── ACCESS_POLICY.md
    ├── HEARTBEAT.md
    ├── log.md
    ├── people/
    ├── companies/
    ├── meetings/
    ├── concepts/
    ├── originals/
    └── media/
```

Each folder includes an `.ok/frontmatter.yml` description that agents see during file listings/searches, plus templates under `.ok/templates/`.

## Markdown shape

A person dossier generated from the pack starts in a GBrain-compatible shape:

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

## Compiled truth

Co-founder and CEO of [[companies/jane-co|Jane Co]]. Met through
[[people/alex-seed-investor|Alex Seed Investor]]. Strong on cost-per-token
economics; go-to-market is still developing.

--- 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.
- **2026-05-13** | agent enrichment | @agent — Public GitHub profile confirms prior OSS profiler work. Confidence: external profile.
```

Compatibility details:

- Use document frontmatter `title:` and `type:`.
- Prefer path-qualified wikilinks where identity matters: `[[people/jane-founder|Jane Founder]]`, `[[companies/jane-co|Jane Co]]`.
- Keep the compiled-truth section rewritable.
- Separate compiled truth from the timeline with a `--- timeline ---` sentinel line.
- Keep timeline entries append-only and dated: `- **YYYY-MM-DD** | source | @author — event. Confidence: ...`.

## Worked loop: meeting → dossiers → human correction

1. Create `meetings/2026-05-12-jane-founder-coffee.md` from the meeting template.
2. Write raw notes with path-qualified links:

```markdown
---
type: meeting
title: Jane Founder coffee
date: 2026-05-12
attendees: [Jane Founder]
tags: [meeting, ai-infra]
---

## Notes

Jane runs [[companies/jane-co|Jane Co]], a stealth AI infra company focused on
[[concepts/agent-runtime-observability|agent-runtime observability]].
Introduced by [[people/alex-seed-investor|Alex Seed Investor]].

Quote: "the agent runtime is the new kernel."
```

3. Ask 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 (GBrain-compatible Markdown) templates. Append dated timeline bullets. Do not rewrite existing timeline entries.
```

4. Review the agent edits in OK. If the agent inferred something wrong, correct it in the editor.
5. Commit the Markdown changes.

The core value is the correction loop: the durable memory is not hidden in a model context window or database row. It is a file you can inspect, edit, diff, and roll back.

## Interop with Garry Tan's `gbrain`

If you also run `gbrain`, point it at the same Markdown vault after OK has written the files:

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

Recommended operating model:

- Use `gbrain import ... --no-embed` for the first bulk load when you want to avoid embedding during the scan.
- Run `gbrain embed --stale` after import or after any no-embed sync.
- Commit OK changes, then run `gbrain sync --repo ~/your-ok-vault` for incremental refresh.
- Keep OK as the place where humans inspect/correct the Markdown.
- Keep `gbrain` as the engine that indexes, searches, extracts graph/timeline data, and runs its own automation.

No file collision is required: OK writes Markdown; `gbrain` reads/imports/syncs that Markdown into its own configured storage. If you wire separate GBrain skills or cron jobs, treat that as a separate integration choice rather than something the Entity vault (GBrain-compatible Markdown) pack does by itself.

## Power-user demo path

For a GBrain-literate reviewer, the demo target is not "OK replaces GBrain." It is:

1. Open a GBrain-style Markdown vault in OK.
2. Let an agent write/update a dossier through OK MCP.
3. Watch the edit land live with attribution.
4. Correct a wrong claim by hand in OK.
5. Commit the changes.
6. Run `gbrain sync --repo <vault>`.
7. Query/search in `gbrain` and see the corrected fact.

Aha moment: **GBrain makes agent memory useful; OK makes the Markdown memory inspectable, correctable, and collaborative.**

## Routine

| Cadence | What |
| --- | --- |
| After each meeting | Drop raw notes into `meetings/<date>-<slug>.md`; link mentioned people/companies/concepts. |
| End of day | Ask an agent to create/update dossiers and append timeline bullets from new meetings. |
| Weekly | Run OK's dead-link audit; triage new entities vs typos vs intentional placeholders. |
| Monthly | Audit stale dossiers, empty timelines, and compiled truth that conflicts with recent evidence. |
| When using `gbrain` | Commit OK edits, then run `gbrain sync --repo <vault>` and `gbrain embed --stale` as needed. |

## Naming note

The pack is presented as **Entity vault (GBrain-compatible)**, not **GBrain Entity Vault**. "Entity vault" names the portable Markdown workflow OK scaffolds. "GBrain-compatible" describes the interop contract with Garry Tan's `gbrain` without claiming ownership of his project or implying OK is a replacement engine.

## Further reading

- **[Garry Tan's gbrain](https://github.com/garrytan/gbrain).** Optional engine/index/automation layer for the same Markdown vault.
- **[Karpathy LLM wiki workflow](./karpathy-llm-wiki.mdx).** Source-grounded counterpart to the entity-vault posture.
- **[Agent activity](../features/agent-activity.mdx).** How OK attributes human and agent edits.
- **[Claude Code](../integrations/claude-code.mdx)**, **[Cursor](../integrations/cursor.mdx)**, **[Codex](../integrations/codex.mdx).** MCP-capable agent hosts.
