diff --git a/.changeset/entity-vault-gbrain-compatible-rename.md b/.changeset/entity-vault-gbrain-compatible-rename.md new file mode 100644 index 00000000..dcba9f91 --- /dev/null +++ b/.changeset/entity-vault-gbrain-compatible-rename.md @@ -0,0 +1,9 @@ +--- +"@inkeep/open-knowledge": patch +"@inkeep/open-knowledge-core": patch +"@inkeep/open-knowledge-server": patch +"@inkeep/open-knowledge-app": patch +"@inkeep/open-knowledge-desktop": patch +--- + +Rename the `gbrain` starter pack to **Entity vault (GBrain-compatible)** and reposition it as a human cockpit for GBrain-style Markdown brains rather than a GBrain reimplementation. This is a breaking pre-release rename: the canonical pack ID is now `entity-vault` with no `gbrain` alias, so `ok seed --pack gbrain` no longer resolves — use `ok seed --pack entity-vault`. The pack picker, seed dialog, toast, and CLI list now show "Entity vault (GBrain-compatible)". Generated dossier templates are tightened for GBrain-compatible parsing — document-level `title:` frontmatter, an explicit `--- timeline ---` sentinel, and parseable `- **YYYY-MM-DD** | source | @author — … Confidence: …` timeline bullets with path-qualified `[[folder/slug|Label]]` links. The workflow doc moved from `/workflows/gbrain` to `/workflows/entity-vault`. OK edits and reviews the Markdown; Garry Tan's `gbrain`, if installed, can still import/sync the same vault — interop is Markdown + Git, with no deep integration implied. diff --git a/.changeset/fix-cli-repository-url-provenance.md b/.changeset/fix-cli-repository-url-provenance.md new file mode 100644 index 00000000..06b80434 --- /dev/null +++ b/.changeset/fix-cli-repository-url-provenance.md @@ -0,0 +1,5 @@ +--- +"@inkeep/open-knowledge": patch +--- + +Restore the `repository` field on the published CLI package, pointing at `inkeep/open-knowledge`. It was dropped when the mirror was re-pointed off `open-knowledge-legacy`, which left npm Trusted Publishing unable to verify provenance and failed every release publish with `E422 ... "repository.url" is ""`. diff --git a/docs/content/reference/core-concepts.md b/docs/content/reference/core-concepts.md index 473c4bd5..461764c4 100644 --- a/docs/content/reference/core-concepts.md +++ b/docs/content/reference/core-concepts.md @@ -72,7 +72,7 @@ Agents use these to repair and densify the graph as they work, instead of lettin ### Closed-loop grounding -Every factual claim should trace back to a source **inside** the knowledge base. External material is pulled in and cited locally rather than linked off to the open web, so the knowledge base stays self-contained and auditable. This is the backbone of the source-grounded workflows: see [Karpathy's LLM wiki workflow](../workflows/karpathy-llm-wiki.mdx) and the [Gbrain workflow](../workflows/gbrain.mdx). +Every factual claim should trace back to a source **inside** the knowledge base. External material is pulled in and cited locally rather than linked off to the open web, so the knowledge base stays self-contained and auditable. This is the backbone of the source-grounded workflows: see [Karpathy's LLM wiki workflow](../workflows/karpathy-llm-wiki.mdx) and the [Entity vault (GBrain-compatible) workflow](../workflows/entity-vault.mdx). Open Knowledge is unopinionated about which workflow you adopt; these are supported patterns, not requirements. Grounding, backlinks, and the graph tools work the same regardless of how you choose to organize. diff --git a/docs/content/workflows/entity-vault.mdx b/docs/content/workflows/entity-vault.mdx new file mode 100644 index 00000000..15813697 --- /dev/null +++ b/docs/content/workflows/entity-vault.mdx @@ -0,0 +1,182 @@ +--- +title: Entity vault (GBrain-compatible) workflow +description: A GBrain-compatible Markdown workflow for people, companies, meetings, and concepts. Open Knowledge 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. + +Open Knowledge 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 | Open Knowledge | 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_document`, `edit_document`, `links`, `version`, `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. Save a version checkpoint before any risky enrichment pass. +6. 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. Save a checkpoint and commit. +6. Run `gbrain sync --repo `. +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/-.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 ` 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. diff --git a/docs/content/workflows/gbrain.mdx b/docs/content/workflows/gbrain.mdx deleted file mode 100644 index c4655882..00000000 --- a/docs/content/workflows/gbrain.mdx +++ /dev/null @@ -1,309 +0,0 @@ ---- -title: Gbrain workflow -description: Entity-grounded second brain in Open Knowledge. Typed dossiers for people, companies, meetings, concepts. The Gbrain starter pack scaffolds the full layout in one click. Pattern inspired by Garry Tan's gbrain. ---- - -An entity-grounded second brain: typed dossiers for every person you meet, every company you track, every meeting you sit through. Each dossier has a top section your agent rewrites as new evidence arrives ("compiled truth") and an append-only timeline below ("evidence trail"). Open Knowledge ships this layout as the **Gbrain starter pack**: one click in the pack picker and you have the folder structure, the templates, and the agent-readable folder frontmatter in place. The pattern is inspired by Garry Tan's [gbrain](https://github.com/garrytan/gbrain); OK ships its own implementation of the layout. - -The point of this guide is to show how **Open Knowledge's features compose** to make this pattern feel native: the starter-pack picker scaffolds the entire layout in one click; per-folder templates + agent-readable folder frontmatter teach the LLM the conventions without you writing a schema doc; the WYSIWYG editor lets you hand-curate without thinking about markdown syntax; the agent activity panel attributes every edit (yours and the agent's); the `links` and `version` tools, plus the standard MCP tools (`write_document`, `edit_document`, `search`, `exec`), compose into routines that take ten minutes a week instead of an hour. Every step below uses three or four of these together. That's the product. - -## Who this is for - -- **You want a brain that knows people, companies, and your relationships**, not just a stack of source documents. -- **You're new to LLM-curated PKM** and the entity-tracking posture matches how you think. - -## Before you begin - -- **The Open Knowledge desktop app.** Install it from the [Quickstart](../get-started/quickstart.mdx). The desktop app is macOS-only today; Linux and Windows desktop builds are deferred. -- **An MCP-capable agent assistant.** [Claude Code](../integrations/claude-code.mdx), [Cursor](../integrations/cursor.mdx), or [Codex](../integrations/codex.mdx). The OK desktop app's first-launch flow detects them and wires them up. - -That's the whole toolchain. Everything below uses OK's MCP server + your agent; no other software required. - -## The scenario - -You meet a founder over coffee on Tuesday. By Wednesday morning, your agent knows who they are, what they're building, who their co-founders are, that you previously met their seed investor, and every concrete thing they said yesterday, in their words, with the date. You walk into Wednesday's calls already briefed. Zero post-meeting research. - -## What's in your vault after one Tuesday - -``` -your-vault/ -├── USER.md ← your profile (created by the pack) -├── SOUL.md ← agent identity / values -├── ACCESS_POLICY.md ← what the agent may surface -├── HEARTBEAT.md ← cadence cues -├── log.md ← append-only audit trail -├── people/ -│ ├── jane-founder.md ← compiled truth + timeline -│ └── alex-seed-investor.md ← (previously created) -├── companies/ -│ └── jane-co.md -├── meetings/ -│ └── 2026-05-12-jane-founder-coffee.md -├── concepts/ -├── originals/ ← your own thinking -└── media/ ← transcripts, voice notes -``` - -A typical `people/jane-founder.md` after the meeting + one enrichment pass: - -```markdown ---- -title: Jane Founder -type: person -tags: [founder, ai-infra] ---- - -## Compiled truth - -Co-founder + CEO of [[Jane Co]], stealth AI infra play. Met through -[[Alex Seed Investor]]. Sharp on cost-per-token economics; less developed -on go-to-market. - ---- - -## Timeline - -2026-05-12: Coffee meeting (see [[2026-05-12-jane-founder-coffee]]). -2026-05-13: Agent enrichment. LinkedIn confirms 4y at hyperscaler; OSS profiler at 5.1k stars. -``` - -Compiled truth is rewritable as evidence arrives. Timeline is append-only. The split is what makes the workflow trustworthy. - -## Setup - -### 1. Pick the Gbrain pack (one click) - -Launch the OK desktop app, drag-and-drop or open a project folder, then click the empty-state **Pick a starter pack** → select **Gbrain** → confirm a subfolder if you want it nested (default `vault/`). Apply. - -You get six folders (`people/`, `companies/`, `meetings/`, `concepts/`, `originals/`, `media/`), six templates (`person`, `company`, `meeting`, `concept`, `original`, `transcript`), agent-readable folder descriptions in each `.ok/frontmatter.yml`, and five root files (`USER.md`, `SOUL.md`, `ACCESS_POLICY.md`, `HEARTBEAT.md`, `log.md`). - -The starter-pack picker is idempotent (safe to re-run on the same project). - -### 2. Fill in `USER.md` (60 seconds) - -Open `USER.md` in the editor. Add your name, role, focus areas. That's enough for every future agent prompt to know who you are. `SOUL.md`, `ACCESS_POLICY.md`, and `HEARTBEAT.md` are stubs to grow into. - -### Do you need to install `gbrain` itself? No, but here's what it adds if you do - -**You don't need it.** The pack + OK's MCP tools (`write_document`, `edit_document`, `links`, `version`, `search`, `exec`) + your agent assistant cover every workflow in this guide. Most users stop here. - -If you want a few capabilities OK doesn't ship, Garry Tan's [`gbrain`](https://github.com/garrytan/gbrain) installs alongside OK and points at the same vault directory. It adds: - -- **Scheduled `dream` cycle.** 11 phases run on a cron: `lint → backlinks → sync → synthesize → extract → patterns → recompute_emotional_weight → consolidate → embed → orphans → purge`. Operates in Postgres. -- **`voice-note-ingest` skill.** Captures voice memos verbatim and routes content into pack folders (`originals/` / `concepts/` / `people/` / `companies/`) plus gbrain-native folders it creates as needed (`ideas/` / `personal/` / `voice-notes/`) based on content classification. -- **Vector retrieval.** pgvector with HNSW cosine search; runs on PGLite (default, embedded) or Postgres. Sits on top of OK's BM25 + literal search (`exec`'s `grep`). -- **34 skills total.** Person enrichment tiers, meeting ingestion, briefing generation, archive crawling, soul-audit, and more. - -Setup if you want it: - -```bash -git clone https://github.com/garrytan/gbrain && cd gbrain && bun install && bun link -gbrain init # user-level; creates ~/.gbrain/ only -``` - -`gbrain init` is entirely user-level. It creates `~/.gbrain/` (config + PGLite database + gbrain's own identity stubs) and doesn't touch your OK vault. To bulk-load your vault into gbrain's Postgres, then keep it in sync: - -```bash -gbrain import ~/your-ok-vault --no-embed # first-time bulk load (re-scans every time) -gbrain embed --stale # generate embeddings for the new content - -gbrain sync --repo ~/your-ok-vault # daily incremental sync (uses git history) -gbrain sync --repo ~/your-ok-vault --watch # active-editing session -gbrain sync --install-cron # scheduled -``` - -Both gbrain's MCP server and OK's register with your agent assistant. The pack-only path stays fully supported; gbrain is purely additive. - -**Compatibility:** gbrain operates entirely from `~/.gbrain/` (config, Postgres database, gbrain's own user-level identity files all live there). `gbrain import` / `sync` read your OK vault one-way into Postgres; gbrain doesn't write canonical dossiers back. The pack's templates + OK's MCP tools + your agent are how new dossiers land in the vault. No file collision; install in either order. - -## A worked example, end to end - -Tuesday 10am through Wednesday 5pm. Everything below uses the OK desktop app + your agent assistant (or any MCP-capable host). - -### Tuesday 10:00, in the cafe - -Open OK on your laptop. New file in the sidebar: `meetings/2026-05-12-jane-founder-coffee.md`. The pack's `meeting` template lands the right frontmatter automatically: - -```markdown ---- -title: Jane Founder coffee -type: meeting -date: 2026-05-12 -attendees: [Jane Founder] -tags: [meeting, ai-infra] ---- - -## Notes - -Jane runs [[Jane Co]]: stealth AI infra play, 6 months in, three people, -agent-runtime observability. Background: 4 years at a hyperscaler, shipped -an OSS profiler. Pulled in by [[Alex Seed Investor]]. - -Pitch: cost-per-token telemetry for multi-agent systems. Sharp on unit -economics; go-to-market less developed. - -Quote: "the agent runtime is the new kernel." - -## Action items - -- [ ] Intro to two design partners next week. -``` - -The `[[Jane Co]]` and `[[Alex Seed Investor]]` wikilinks render as redlinks for now; their dossiers don't exist yet. The CRDT flushes the file to disk in under a second. - -### Tuesday 10:45, walking to the next call - -Open your agent assistant on your phone (or back at your desk): - -``` -> from meetings/2026-05-12-jane-founder-coffee.md, create or update -> dossiers for everyone mentioned, using the gbrain pack's person and -> company templates. Don't enrich yet; just extract the entities and -> seed the timeline entries. -``` - -The agent calls `mcp__open-knowledge__write_document` with the `person` template for `people/jane-founder.md`, the `company` template for `companies/jane-co.md`, and `edit_document` to append a timeline entry to the existing `people/alex-seed-investor.md` (*"2026-05-12: Introduced Jane Founder to me. See [[2026-05-12-jane-founder-coffee]]."*). - -OK's activity panel shows three fresh agent edits. The wikilinks in your meeting note are no longer redlinks. - -### Tuesday 9:00 PM, agent-driven enrichment - -``` -> enrich people/jane-founder.md and companies/jane-co.md from public -> sources (LinkedIn, GitHub, recent press). Rewrite the compiled-truth -> section if you find load-bearing facts; append timeline entries citing -> what you found. Don't touch existing timeline entries. -``` - -The agent uses its web-fetch capability plus the pack's frontmatter rules (it reads the folder descriptions on each `exec` directory listing, so it knows compiled-truth-above / timeline-below discipline). Edits land via `mcp__open-knowledge__edit_document`. The OK editor renders the diff in real time; the activity panel logs each write. - -### Wednesday 7:00 AM, briefing - -``` -> morning briefing: today's calendar plus per-attendee context from -> people/ and companies/, with talking points -``` - -The agent reads the dossiers and returns a brief. You scan it, spot that the agent inferred Alex was Jane's seed lead (he wasn't; he just made the intro). You open `people/jane-founder.md` in the OK editor and fix that line in WYSIWYG. The activity panel logs your edit alongside the agent's; both attributions stack cleanly. - -Save a checkpoint (`mcp__open-knowledge__version`, `action: save`) so a later enrichment pass doesn't quietly overwrite your correction. - -### Wednesday 5:00 PM, your own thinking lands in `originals/` - -Post-call, you have a take. Open `originals/2026-05-13-jane-co-thoughts.md` in the OK editor; the pack's `original` template kicks in: - -```markdown ---- -title: Jane Co, first read -type: idea -date: 2026-05-13 -tags: [original, ai-infra, jane-co] ---- - -After Alex this morning + the meeting yesterday with [[Jane Founder]]: -[[Jane Co]]'s cost-per-token framing is sharp but they're under-baking -GTM. The OSS profiler is the wedge nobody's mentioned in pitch. Three -things to watch: hiring a GTM lead in Q3, profiler-community acceptance -of the runtime-cost taxonomy, Alex's read on the team. -``` - -OK's CRDT flushes. The agent picks this up on the next maintenance pass: the wikilinks become inbound backlinks on both dossiers, and the substantive claim becomes timeline material. - -Two days, end-to-end. No clipboard copy. No external sync. - -**What just composed.** The 48-hour arc above used: the **Gbrain pack** (folder structure + templates + folder frontmatter), the **WYSIWYG editor** (visual editing without markdown syntax), **CRDT auto-flush** (your edits land on disk in under a second), **agent activity attribution** (every write traceable to a human or an agent), `mcp__open-knowledge__write_document` (typed dossier creation), `mcp__open-knowledge__edit_document` (surgical compiled-truth + timeline updates), `mcp__open-knowledge__version` (snapshot before risky enrichment), and the **wikilink graph + folder frontmatter** that lets the agent operate on the entity layer without you re-explaining the conventions per prompt. The same vault. One product. - -## Second worked example: dead links → triage → WYSIWYG - -Entity vaults accumulate redlinks fast: a typed `[[Jane Co]]` before the dossier existed, a typo `[[Alex Investo]]`, a placeholder `[[2026-Q3 Plan]]` for a doc you'll write later. OK's `links` dead-link audit + your agent + the WYSIWYG editor close the loop in about 10 minutes a week. - -### 1. Audit - -``` -> find every dead link across the vault and group results by missing target -``` - -`mcp__open-knowledge__links` with `kind: dead` returns a map of each missing target plus the source docs pointing at it. - -### 2. Agent triage - -``` -> for each dead target, read the source line and decide: -> (a) new entity → create a dossier with the right pack template, -> (b) typo → propose the corrected wikilink, -> (c) intentional placeholder → leave it; add to originals/_intentional-redlinks.md -> show me the plan before you act. -``` - -The agent reads source lines, greps `people/` / `companies/` for closest-name matches, returns a plan: - -- `[[Jane Co]]` → (a) new company. Create `companies/jane-co.md` from the `company` template; initial timeline entries from the two source backlinks; enrich from public sources. -- `[[Alex Investo]]` → (b) typo. Closest match: `Alex Investor`. Fix the source line. -- `[[2026-Q3 Plan]]` → (c) placeholder. One-line entry in `originals/_intentional-redlinks.md`. - -You approve. - -### 3. Execute + WYSIWYG correction - -The agent runs `write_document`, `edit_document` for the typo, and a follow-up enrichment pass on the new dossier. - -Open `companies/jane-co.md` in the OK editor. The agent's compiled-truth sentence reads: - -> Stealth AI infra play. Public profile shows seed round (undisclosed amount) led by [[Alex Investor]] (April 2026). Three people. No press beyond the announce post. - -You know something the agent doesn't: Jane mentioned a fourth hire starting next month. You append in WYSIWYG: - -> Three people. Fourth hire (eng) starts June 2026. - -Your edit is attributed in the activity panel as a human write, stacked next to the agent's earlier edits. The mid-paragraph insertion lands without you touching frontmatter or markdown syntax. - -### 4. Confirm clean - -``` -> find the dead links again; confirm the three resolved -``` - -The audit returns one remaining redlink (`[[2026-Q3 Plan]]`, intentional) plus the placeholder index entry. Graph is whole. - -### Why this loop matters - -Five OK features compose into the routine: - -- `links` (the dead-link audit) finds structural breakage at vault scale in one call. -- The agent triages: reads source context via `exec`, classifies each dead link, routes to the right tool. -- The pack's `/.ok/templates/` mean every dossier the agent creates starts in the right shape, with the right body convention; the `/.ok/frontmatter.yml` descriptions tell the agent what each folder is for — no per-prompt reminders. -- The WYSIWYG editor + CRDT auto-flush make hand-curation a 5-second mid-paragraph insertion, attributed correctly in the activity panel. -- `version` (save + rollback) gives you cheap insurance against a future enrichment pass overwriting human-curated facts. - -Ten minutes weekly instead of an hour of cleanup. None of it requires anything beyond OK + your agent host. - -## Routine - -A maintenance cadence that scales. None of it requires anything beyond OK + your agent. - -| Cadence | What | -|---|---| -| **After each meeting** | Drop raw notes into `meetings/-.md`. The `meeting` template handles frontmatter. | -| **End of day** | Ask the agent: *"process today's meeting notes; update or create dossiers for everyone mentioned. Append timeline entries; don't rewrite compiled truth unless you have clear new evidence."* | -| **Weekly** | Run the dead-link audit above. Also: *"find entities whose compiled-truth is contradicted by recent timeline entries; propose rewrites for me to review."* | -| **Monthly** | *"audit `people/` and `companies/`: dossiers untouched in 90+ days, dossiers with empty timelines, dossiers whose wikilinks have decayed."* | - -You're orchestrating, not implementing. The OK MCP tools (`exec`, `search`, `edit_document`, `links`, `version`) cover every step. - -## Tips - -- **Wikilinks are the graph.** Every `[[Jane Co]]` mention creates a backlink. The graph self-wires. -- **Never rewrite the timeline.** Append-only is what makes compiled-truth rewrites trustworthy. -- **`version` (save) before risky enrichment.** Snapshot + rollback are first-class: cheap insurance for hand-curated facts. - -## Looking for source-grounded knowledge instead? - -This guide is the **entity-grounded** posture. If what you want is a citation-traceable wiki (*"what do we know about X, with evidence?"*), see the [Karpathy LLM wiki workflow](./karpathy-llm-wiki.mdx). Different pattern, same Open Knowledge editor. - -## Further reading - -- **[Agent activity](../features/agent-activity.mdx).** How every agent edit lands in the shadow repo with attribution. -- **[Claude Code](../integrations/claude-code.mdx)**, **[Cursor](../integrations/cursor.mdx)**, **[Codex](../integrations/codex.mdx).** Agent-assistant integrations. -- **[`STARTER_PACKS` registry](https://github.com/inkeep/open-knowledge-legacy/blob/main/packages/server/src/seed/starter.ts).** Canonical source for the Gbrain pack content. -- **[Garry Tan's gbrain](https://github.com/garrytan/gbrain).** The pattern this layout is inspired by. -- **[Karpathy LLM wiki workflow](./karpathy-llm-wiki.mdx).** Source-grounded counterpart. diff --git a/docs/content/workflows/karpathy-llm-wiki.mdx b/docs/content/workflows/karpathy-llm-wiki.mdx index c4d4e32d..22fa1358 100644 --- a/docs/content/workflows/karpathy-llm-wiki.mdx +++ b/docs/content/workflows/karpathy-llm-wiki.mdx @@ -215,7 +215,7 @@ The compounding move: end each ingest session with one synthesis query. The answ ## Looking for entity tracking instead? -This guide is the **source-grounded** posture: bring sources, the LLM curates the wiki. If what you actually want is to track *people, companies, and meetings* (who's in your network, what was said, what changes over time), the [Gbrain workflow guide](./gbrain.mdx) is the better starting point. Different pattern, same Open Knowledge editor. +This guide is the **source-grounded** posture: bring sources, the LLM curates the wiki. If what you actually want is to track *people, companies, and meetings* (who's in your network, what was said, what changes over time), the [Entity vault (GBrain-compatible) workflow guide](./entity-vault.mdx) is the better starting point. Different pattern, same Open Knowledge editor. ## Further reading @@ -231,4 +231,4 @@ This guide is the **source-grounded** posture: bring sources, the LLM curates th ### Adjacent OK workflow -- **[Gbrain workflow in Open Knowledge](./gbrain.mdx).** Entity-vault counterpart, if the source-grounded posture isn't your fit. +- **[Entity vault (GBrain-compatible) workflow in Open Knowledge](./entity-vault.mdx).** Entity-vault counterpart, if the source-grounded posture isn't your fit. diff --git a/docs/content/workflows/meta.json b/docs/content/workflows/meta.json index b856cbc9..7a8fe1e3 100644 --- a/docs/content/workflows/meta.json +++ b/docs/content/workflows/meta.json @@ -1,5 +1,5 @@ { "title": "Workflows", "icon": "LuWorkflow", - "pages": ["karpathy-llm-wiki", "gbrain"] + "pages": ["karpathy-llm-wiki", "entity-vault"] } diff --git a/packages/app/src/components/PackCardGrid.test.ts b/packages/app/src/components/PackCardGrid.test.ts index 0d8b51dc..dceae0aa 100644 --- a/packages/app/src/components/PackCardGrid.test.ts +++ b/packages/app/src/components/PackCardGrid.test.ts @@ -22,7 +22,7 @@ describe('PackCardGrid source-level guards', () => { "'plain-notes'", 'worldbuilding', "'writing-pipeline'", - 'gbrain', + "'entity-vault'", ]) { expect(SRC).toContain(id); } diff --git a/packages/app/src/components/PackCardGrid.tsx b/packages/app/src/components/PackCardGrid.tsx index 49b62c17..6c41799e 100644 --- a/packages/app/src/components/PackCardGrid.tsx +++ b/packages/app/src/components/PackCardGrid.tsx @@ -13,7 +13,7 @@ const PACK_ICONS: Record> 'plain-notes': StickyNote, worldbuilding: Compass, 'writing-pipeline': PenLine, - gbrain: Network, + 'entity-vault': Network, }; function iconForPack(id: string): React.ComponentType<{ className?: string }> { diff --git a/packages/app/src/lib/desktop-bridge-types.ts b/packages/app/src/lib/desktop-bridge-types.ts index c74274b9..44102d17 100644 --- a/packages/app/src/lib/desktop-bridge-types.ts +++ b/packages/app/src/lib/desktop-bridge-types.ts @@ -53,7 +53,7 @@ export type OkPackId = | 'plain-notes' | 'worldbuilding' | 'writing-pipeline' - | 'gbrain'; + | 'entity-vault'; interface OkSeedPlanOptions { rootDir?: string; diff --git a/packages/cli/package.json b/packages/cli/package.json index 00ae9ef5..82c38d74 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -3,6 +3,11 @@ "version": "0.9.1", "private": false, "type": "module", + "repository": { + "type": "git", + "url": "git+https://github.com/inkeep/open-knowledge.git", + "directory": "packages/cli" + }, "exports": { ".": { "types": "./dist/index.d.mts", diff --git a/packages/core/src/desktop-bridge.ts b/packages/core/src/desktop-bridge.ts index eae77a22..f722a024 100644 --- a/packages/core/src/desktop-bridge.ts +++ b/packages/core/src/desktop-bridge.ts @@ -253,7 +253,7 @@ type OkPackId = | 'plain-notes' | 'worldbuilding' | 'writing-pipeline' - | 'gbrain'; + | 'entity-vault'; interface OkSeedPlanOptions { rootDir?: string; diff --git a/packages/server/assets/skills/packs/entity-vault/SKILL.md b/packages/server/assets/skills/packs/entity-vault/SKILL.md new file mode 100644 index 00000000..a2ea6c7a --- /dev/null +++ b/packages/server/assets/skills/packs/entity-vault/SKILL.md @@ -0,0 +1,48 @@ +--- +name: open-knowledge-pack-entity-vault +description: "How to work in an Entity vault project (the `entity-vault` starter pack, GBrain-compatible): a typed-entity vault of people, companies, meetings, and concepts, each a dossier with a rewritable summary plus an append-only timeline. Read when the project has these folders. Carries the dossier convention and entity-extraction behaviors so that guidance does not live inside template bodies or folder descriptions. Complements the platform `open-knowledge` skill; does not replace it." +compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires Open Knowledge MCP server. Installed project-local by `ok seed --pack entity-vault`." +metadata: + pack: "entity-vault" + author: "Inkeep" + repository: "https://github.com/inkeep/open-knowledge" +--- +# Entity vault pack (GBrain-compatible) — how to work here + +A typed-entity vault inspired by Garry Tan's gbrain. Each entity is a dossier; the agent keeps dossiers current by extracting entities from meeting notes and original thinking. This skill holds those behaviors so templates and folder descriptions stay clean. The Markdown shape is **GBrain-compatible**: if the external `gbrain` CLI is installed, it can import/sync the same vault. + +> Pack guidance. The platform `open-knowledge` skill still governs every markdown operation. + +## The dossier convention (the load-bearing rule) + +Every dossier in `people/`, `companies/`, and `concepts/` has two parts, split by an explicit `--- timeline ---` separator: + +1. **Compiled truth** (above `--- timeline ---`) — your current best understanding. Rewrite it as new evidence changes the synthesis. +2. **Timeline** (below `--- timeline ---`) — append-only dated bullets in the parseable form `- **YYYY-MM-DD** | source | @author — evidence. Confidence: …`. **Never edit existing timeline entries; only append.** + +When a new fact arrives, route it: update **compiled truth** if it changes current understanding, or append a timeline bullet if it's raw evidence. The explicit separator and dated-bullet shape are what keep the vault parseable by GBrain's import/sync. + +## Folders + +- **`people/`**, **`companies/`**, **`concepts/`** — dossiers (compiled truth + timeline). Frontmatter `type: person|company|concept`. +- **`meetings/`** — meeting notes (`YYYY-MM-DD-.md`); `attendees:` should match dossier filenames in `people/`. The verbatim record — do NOT rewrite it. +- **`originals/`** — your own untransformed thinking; authoritative source material. Frontmatter `type: original`. +- **`media/`** — bulk transcripts, voice notes, large attachments; often `.okignore`-d to keep the index light. + +## Links + +Prefer path-qualified wikilinks when entity identity matters: `[[companies/acme|Acme]]`, `[[people/jane-founder|Jane Founder]]`, `[[concepts/agent-runtime-observability|agent-runtime observability]]`. Path-qualified links resolve to the right dossier under GBrain's typed extraction. + +## Agent behaviors + +- After a meeting note lands, extract entity mentions and append timeline bullets to each referenced dossier (cite the meeting by markdown link). Stub any mentioned entity not yet captured. +- Treat `originals/` as authoritative (the user's own words, not inferences). +- Surface entity-to-entity edges (person ↔ company, concept hubs) when both ends exist. + +## gbrain CLI (optional) + +This pack ships the Markdown half (folders + templates + this skill); OK is the cockpit/editor/review layer. If the external `gbrain` CLI is installed (`~/.gbrain/`), it adds scheduled enrichment: `gbrain dream` (nightly maintenance), `gbrain briefing`, `gbrain soul-audit`, and `gbrain import`/`gbrain sync --repo` for DB-backed indexing. The root files (`USER.md`, `SOUL.md`, `ACCESS_POLICY.md`, `HEARTBEAT.md`) are read by those skills; fill them in by hand or via `gbrain soul-audit`. None of it is required to use the vault — interop is plain Markdown + Git. + +## Templates + +Create with `write_document({ template: "", … })`. Templates carry the structure (including the compiled-truth / `--- timeline ---` separator) plus short inline reminders at the point of use; this skill holds the full convention, so prefer it as the canonical reference if the two ever disagree. diff --git a/packages/server/assets/skills/packs/gbrain/SKILL.md b/packages/server/assets/skills/packs/gbrain/SKILL.md deleted file mode 100644 index d84b8cbe..00000000 --- a/packages/server/assets/skills/packs/gbrain/SKILL.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -name: open-knowledge-pack-gbrain -description: "How to work in a Gbrain project (the `gbrain` starter pack): a typed-entity vault of people, companies, meetings, and concepts, each a dossier with a rewritable summary plus an append-only timeline. Read when the project has these folders. Carries the dossier convention and entity-extraction behaviors so that guidance does not live inside template bodies or folder descriptions. Complements the platform `open-knowledge` skill; does not replace it." -compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires Open Knowledge MCP server. Installed project-local by `ok seed --pack gbrain`." -metadata: - pack: "gbrain" - author: "Inkeep" - repository: "https://github.com/inkeep/open-knowledge" ---- -# Gbrain pack — how to work here - -A typed-entity vault inspired by Garry Tan's gbrain. Each entity is a dossier; the agent keeps dossiers current by extracting entities from meeting notes and original thinking. This skill holds those behaviors so templates and folder descriptions stay clean. - -> Pack guidance. The platform `open-knowledge` skill still governs every markdown operation. - -## The dossier convention (the load-bearing rule) - -Every dossier in `people/`, `companies/`, and `concepts/` has two parts: - -1. **Compiled truth** (above the `---` divider) — your current best understanding. Overwrite it as new evidence arrives. -2. **Timeline** (below the divider) — append-only `YYYY-MM-DD:` entries. **Never edit existing timeline entries; only append.** - -When a new fact arrives, route it: update **compiled truth** if it changes current understanding, or append to the **timeline** if it's raw evidence. - -## Folders - -- **`people/`**, **`companies/`**, **`concepts/`** — dossiers (compiled truth + timeline). Frontmatter `type: person|company|concept`. -- **`meetings/`** — meeting notes (`YYYY-MM-DD-.md`); `attendees:` should match dossier filenames in `people/`. The verbatim record — do NOT rewrite it. -- **`originals/`** — your own untransformed thinking; authoritative source material. -- **`media/`** — bulk transcripts, voice notes, large attachments; often `.okignore`-d to keep the index light. - -## Agent behaviors - -- After a meeting note lands, extract entity mentions and append timeline entries to each referenced dossier (cite the meeting by markdown link). Stub any mentioned entity not yet captured. -- Treat `originals/` as authoritative (the user's own words, not inferences). -- Surface entity-to-entity edges (person ↔ company, concept hubs) when both ends exist. - -## gbrain CLI (optional) - -This pack ships the markdown half (folders + templates + this skill). If the external `gbrain` CLI is installed (`~/.gbrain/`), it adds scheduled enrichment: `gbrain dream` (nightly maintenance), `gbrain briefing`, `gbrain soul-audit`. The root files (`USER.md`, `SOUL.md`, `ACCESS_POLICY.md`, `HEARTBEAT.md`) are read by those skills; fill them in by hand or via `gbrain soul-audit`. None of it is required to use the vault. - -## Templates - -Create with `write_document({ template: "", … })`. Templates carry only structure (including the compiled-truth / timeline divider); the convention is described here, not repeated in document bodies. diff --git a/packages/server/scripts/build-skill-bundles.test.ts b/packages/server/scripts/build-skill-bundles.test.ts index c809ad4c..3ae5d689 100644 --- a/packages/server/scripts/build-skill-bundles.test.ts +++ b/packages/server/scripts/build-skill-bundles.test.ts @@ -126,7 +126,7 @@ describe('buildPackSkills', () => { test('repo assets — all six starter packs are present to build', () => { const packsDir = join(defaultPaths().skillsDir, 'packs'); const expected = [ - 'gbrain', + 'entity-vault', 'knowledge-base', 'plain-notes', 'software-lifecycle', diff --git a/packages/server/src/seed/install-pack-skill.test.ts b/packages/server/src/seed/install-pack-skill.test.ts index 7c53296f..48186b05 100644 --- a/packages/server/src/seed/install-pack-skill.test.ts +++ b/packages/server/src/seed/install-pack-skill.test.ts @@ -30,7 +30,11 @@ describe('installPackSkill', () => { setUpEditor(proj, '.claude'); setUpEditor(proj, '.cursor'); setUpEditor(proj, '.agents'); - expect(installPackSkill(proj, 'gbrain').sort()).toEqual(['Claude Code', 'Codex', 'Cursor']); + expect(installPackSkill(proj, 'entity-vault').sort()).toEqual([ + 'Claude Code', + 'Codex', + 'Cursor', + ]); }); test('no-op when no editor is set up (no platform skill present)', () => { diff --git a/packages/server/src/seed/starter.test.ts b/packages/server/src/seed/starter.test.ts index ddd6aa1c..738000b2 100644 --- a/packages/server/src/seed/starter.test.ts +++ b/packages/server/src/seed/starter.test.ts @@ -12,6 +12,20 @@ const STARTER_FOLDERS = KNOWLEDGE_BASE_PACK.folders; const STARTER_TEMPLATES = KNOWLEDGE_BASE_PACK.templates; const LOG_MD_TEMPLATE = KNOWLEDGE_BASE_PACK.rootFiles?.['log.md']; if (!LOG_MD_TEMPLATE) throw new Error('knowledge-base pack is missing log.md'); +const ENTITY_VAULT_PACK = STARTER_PACKS['entity-vault']; + +function stripTemplateMetadata(body: string): string { + const match = /^---\n[\s\S]*?\n---\n([\s\S]*)$/.exec(body); + if (!match?.[1]) throw new Error('template missing outer metadata frontmatter'); + return match[1]; +} + +function documentFrontmatter(body: string): string { + const documentBody = stripTemplateMetadata(body); + const match = /^---\n([\s\S]*?)\n---/.exec(documentBody); + if (!match?.[1]) throw new Error('template missing document frontmatter'); + return match[1]; +} describe('STARTER_FOLDERS — Karpathy three-layer starter pack', () => { test('ships exactly three starter folders in Karpathy-layer order', () => { @@ -125,7 +139,7 @@ describe('STARTER_PACKS — all packs structural validation', () => { test('STARTER_PACK_IDS contains exactly the 6 expected packs (pinned to detect silent additions/deletions)', () => { expect(STARTER_PACK_IDS.length).toBe(6); expect([...STARTER_PACK_IDS].sort()).toEqual([ - 'gbrain', + 'entity-vault', 'knowledge-base', 'plain-notes', 'software-lifecycle', @@ -289,6 +303,61 @@ describe('STARTER_PACKS — all packs structural validation', () => { }); }); +describe('Entity vault pack — GBrain-compatible Markdown shape', () => { + test('uses entity-vault as the only canonical pack id (no gbrain alias)', () => { + expect(ENTITY_VAULT_PACK.id).toBe('entity-vault'); + expect((STARTER_PACKS as Record).gbrain).toBeUndefined(); + }); + + test('metadata ties Entity vault to GBrain compatibility without a replacement-engine claim', () => { + expect(ENTITY_VAULT_PACK.name).toBe('Entity vault (GBrain-compatible)'); + expect(ENTITY_VAULT_PACK.description).toContain('people, companies, meetings, and concepts'); + expect(ENTITY_VAULT_PACK.description).toContain('GBrain-compatible Markdown'); + expect(ENTITY_VAULT_PACK.description).toContain('OK handles editing and review'); + expect(ENTITY_VAULT_PACK.description).not.toContain('Gbrain'); + }); + + test('entity templates keep title + type in the generated document frontmatter', () => { + const expectedTypes: Record = { + person: 'person', + company: 'company', + concept: 'concept', + meeting: 'meeting', + original: 'original', + transcript: 'transcript', + }; + for (const [templateName, expectedType] of Object.entries(expectedTypes)) { + const body = ENTITY_VAULT_PACK.templates[templateName]; + expect(body, `missing ${templateName} template`).toBeDefined(); + const fm = documentFrontmatter(body ?? ''); + expect(fm, `${templateName} generated doc frontmatter missing title`).toMatch( + /^title:\s*\S/m, + ); + expect(fm, `${templateName} generated doc frontmatter missing type`).toContain( + `type: ${expectedType}`, + ); + } + }); + + test('compiled-truth dossier templates use the explicit timeline separator and parseable dated bullets', () => { + for (const templateName of ['person', 'company', 'concept']) { + const documentBody = stripTemplateMetadata(ENTITY_VAULT_PACK.templates[templateName] ?? ''); + expect(documentBody).toContain('--- timeline ---'); + expect(documentBody).toMatch(/^- \*\*\{\{date\}\}\*\* \| source \| @\{\{user\}\} — .+/m); + expect(documentBody).not.toMatch(/\{\{date\}\}: First entry/); + } + }); + + test('template guidance prefers path-qualified wikilinks where entity identity matters', () => { + expect(ENTITY_VAULT_PACK.templates.person).toContain('[[companies/acme|Acme]]'); + expect(ENTITY_VAULT_PACK.templates.company).toContain('[[people/jane-founder|Jane Founder]]'); + expect(ENTITY_VAULT_PACK.templates.meeting).toContain('[[companies/jane-co|Jane Co]]'); + expect(ENTITY_VAULT_PACK.templates.meeting).toContain( + '[[concepts/agent-runtime-observability|agent-runtime observability]]', + ); + }); +}); + describe('buildStarterFolderFrontmatterYaml()', () => { test('emits title + description + tags for a folder', () => { const folder = STARTER_FOLDERS[0]; diff --git a/packages/server/src/seed/starter.ts b/packages/server/src/seed/starter.ts index 58824f50..26696aea 100644 --- a/packages/server/src/seed/starter.ts +++ b/packages/server/src/seed/starter.ts @@ -4,7 +4,7 @@ export type PackId = | 'plain-notes' | 'worldbuilding' | 'writing-pipeline' - | 'gbrain'; + | 'entity-vault'; export const DEFAULT_PACK_ID: PackId = 'knowledge-base'; @@ -745,12 +745,12 @@ tags: [published] `, }; -const GBRAIN_FOLDERS: readonly StarterFolder[] = [ +const ENTITY_VAULT_FOLDERS: readonly StarterFolder[] = [ { path: 'people', title: 'People', description: - 'Person dossiers: compiled-truth above the `---` divider, append-only timeline below. Frontmatter `type: person`.', + 'Person dossiers. Compiled-truth section above `--- timeline ---` (rewritten as understanding changes); append-only timeline below using `- **YYYY-MM-DD** | source | @author — evidence` bullets. Frontmatter `type: person`. Prefer path-qualified links such as `[[companies/acme|Acme]]` and `[[meetings/2026-05-12-acme|meeting]]` when identity matters. Agent: when a meeting note mentions a person not yet captured, stub a file here; route new facts into either compiled-truth (current synthesis) or timeline (raw evidence). Never rewrite the timeline.', tags: ['person', 'entity', 'dossier'], starterTemplate: 'person', }, @@ -758,7 +758,7 @@ const GBRAIN_FOLDERS: readonly StarterFolder[] = [ path: 'companies', title: 'Companies', description: - 'Company dossiers, same shape as `people/` (compiled truth + timeline). Frontmatter `type: company`.', + 'Company dossiers. Same body convention as `people/`: compiled-truth above `--- timeline ---`, append-only parseable timeline below. Frontmatter `type: company`. Prefer path-qualified links to `people/`, `meetings/`, and `concepts/`. Agent: when a person dossier references a company not yet captured, stub a file here; surface company-to-person edges when both exist.', tags: ['company', 'entity', 'dossier'], starterTemplate: 'company', }, @@ -766,7 +766,7 @@ const GBRAIN_FOLDERS: readonly StarterFolder[] = [ path: 'meetings', title: 'Meetings', description: - 'Meeting notes (`YYYY-MM-DD-.md`); `attendees:` should match dossier filenames in `people/`. The verbatim record.', + 'Meeting notes. Filename `YYYY-MM-DD-.md`. Frontmatter carries `title`, `date`, `attendees:` (prefer person slugs/names that resolve to `people/` dossiers), and `type: meeting`. Body is raw notes with path-qualified links to the people, companies, and concepts mentioned. Agent: after a meeting note lands, extract entity mentions and append dated timeline bullets to each referenced dossier. Do NOT rewrite the meeting note; it is the verbatim record.', tags: ['meeting', 'note'], starterTemplate: 'meeting', }, @@ -774,7 +774,7 @@ const GBRAIN_FOLDERS: readonly StarterFolder[] = [ path: 'concepts', title: 'Concepts', description: - 'Evergreen idea pages — patterns and frameworks that recur across people, companies, and meetings. Compiled truth + timeline; `type: concept`.', + 'Evergreen idea pages: abstract patterns, frameworks, recurring concepts that surface across people / companies / meetings. Compiled-truth above `--- timeline ---`, append-only parseable timeline below. Frontmatter `type: concept`. Agent: when a meeting note or person dossier references a concept (e.g. "agent-runtime observability") not yet captured, stub a file here; thread path-qualified links so the concept becomes a hub for everywhere it appears.', tags: ['concept', 'idea', 'evergreen'], starterTemplate: 'concept', }, @@ -782,7 +782,7 @@ const GBRAIN_FOLDERS: readonly StarterFolder[] = [ path: 'originals', title: 'Originals', description: - 'Your own untransformed thinking; authoritative source material. Frontmatter `type: idea`.', + "Your own thinking, untransformed. Frontmatter `type: original`. Use freely; link to anything that should become its own entity. Agent: treat originals as authoritative source material when extracting facts; these are the user's words, not inferences. Append timeline entries to referenced dossiers when a clear new claim appears, citing the original by markdown link.", tags: ['original', 'thinking', 'user'], starterTemplate: 'original', }, @@ -790,19 +790,20 @@ const GBRAIN_FOLDERS: readonly StarterFolder[] = [ path: 'media', title: 'Media', description: - 'Bulk transcripts, voice notes, and large attachments. Often `.okignore`-d to keep the index light. Frontmatter `type: transcript`.', + "Bulk transcripts, voice notes, articles, large attachments. Frontmatter `type: transcript` (template provided). Often `.okignore`-d so the OK index stays light. Keep raw media/source material here; analysis belongs in dossiers, not here. If you also run Garry Tan's `gbrain`, import/sync can index these Markdown transcripts alongside the entity dossiers.", tags: ['media', 'transcript', 'bulk'], starterTemplate: 'transcript', }, ] as const; -const GBRAIN_TEMPLATES: Readonly> = { +const ENTITY_VAULT_TEMPLATES: Readonly> = { person: `--- title: Person Name description: One-line characterization. Who they are, why they matter to you. --- --- type: person +title: Person Name created: {{date}} author: {{user}} tags: [person] @@ -810,11 +811,13 @@ tags: [person] ## Compiled truth ---- +(Your current best understanding. Rewrite this section as new evidence changes the synthesis. Prefer path-qualified links such as [[companies/acme|Acme]] when identity matters.) + +--- timeline --- ## Timeline -{{date}}: First entry. +- **{{date}}** | source | @{{user}} — First evidence entry. Confidence: draft. `, company: `--- title: Company Name @@ -822,6 +825,7 @@ description: One-line company summary. What they do, who's involved. --- --- type: company +title: Company Name created: {{date}} author: {{user}} tags: [company] @@ -829,11 +833,13 @@ tags: [company] ## Compiled truth ---- +(Your current best understanding of the company. Rewrite this section as new evidence changes the synthesis. Prefer path-qualified links such as [[people/jane-founder|Jane Founder]].) + +--- timeline --- ## Timeline -{{date}}: First entry. +- **{{date}}** | source | @{{user}} — First evidence entry. Confidence: draft. `, meeting: `--- title: Meeting Title @@ -841,6 +847,7 @@ description: One-line meeting summary. Fill in after the meeting. --- --- type: meeting +title: Meeting Title date: {{date}} attendees: [] author: {{user}} @@ -849,6 +856,8 @@ tags: [meeting] ## Notes +(Raw notes from the meeting. Prefer path-qualified links such as [[people/jane-founder|Jane Founder]], [[companies/jane-co|Jane Co]], and [[concepts/agent-runtime-observability|agent-runtime observability]].) + ## Action items - [ ] @@ -859,6 +868,7 @@ description: One-line concept summary. What it names and why it recurs. --- --- type: concept +title: Concept Name created: {{date}} author: {{user}} tags: [concept] @@ -866,23 +876,27 @@ tags: [concept] ## Compiled truth ---- +(Your current best understanding of the concept. Rewrite as evidence accumulates. Prefer path-qualified links to source entities.) + +--- timeline --- ## Timeline -{{date}}: First entry. +- **{{date}}** | source | @{{user}} — First evidence entry. Confidence: draft. `, original: `--- title: Idea Title description: One-line summary of the idea or take. --- --- -type: idea +type: original +title: Idea Title date: {{date}} author: {{user}} tags: [original] --- +(Your own thinking. Link to anything that should become its own entity, preferably with path-qualified wikilinks once the entity dossier exists.) `, transcript: `--- title: Transcript @@ -890,6 +904,7 @@ description: One-line transcript summary. Source and key topic. --- --- type: transcript +title: Transcript date: {{date}} source: duration: @@ -900,20 +915,43 @@ tags: [transcript, media] ## Source ## Transcript + +(Paste raw transcript. Keep this raw; route analysis and durable claims into entity dossiers with dated timeline bullets.) `, }; -const GBRAIN_LOG_MD = `--- +const ENTITY_VAULT_LOG_MD = `--- title: Work Log -description: Append-only audit trail of changes to this vault. +description: Append-only audit trail. After each turn that creates, edits, or restructures content in the vault, append one dated entry here (one per turn, not per file). --- # Work Log -Append-only audit trail. Add one dated entry per turn that creates, edits, or restructures content. The gbrain pack skill describes what to log and the entry shape. +Append-only audit trail. **Append a dated entry after any turn that creates, edits, or restructures content in the vault.** One entry per turn, not per file. + +What to log: + +- New entity dossiers stubbed (\`people/\` / \`companies/\` / \`concepts/\`) +- Meeting notes captured +- GBrain automation summaries, if you choose to copy or route them back into the vault +- Original-thinking captures +- Folder restructures or rule changes + +**Reference docs as markdown links, not bare paths.** Every doc you touched should appear as \`[name](./path/to/doc.md)\` so the log shows up in \`links({ kind: "backlinks" })\` for those docs. + + `; -const GBRAIN_USER_MD = `--- +const ENTITY_VAULT_USER_MD = `--- title: User profile description: Who you are. Agent reads this on every briefing / enrichment pass. Keep current. --- @@ -936,9 +974,9 @@ description: Who you are. Agent reads this on every briefing / enrichment pass. `; -const GBRAIN_SOUL_MD = `--- +const ENTITY_VAULT_SOUL_MD = `--- title: Agent identity -description: Agent persona, values, voice. If you run gbrain alongside, this is the output of its \`soul-audit\` skill (a 6-phase interview). Fill in by hand or run \`gbrain soul-audit\`. +description: Agent persona, values, voice. Mirrors the SOUL.md convention used in GBrain-style agent workflows; fill in by hand or from your preferred interview flow. --- # Agent identity (SOUL.md) @@ -955,12 +993,12 @@ description: Agent persona, values, voice. If you run gbrain alongside, this is - ... -**Run \`gbrain soul-audit\` to populate this via a guided interview.** Or write it by hand. Anything here informs every gbrain skill that loads SOUL.md on each call. +Fill this in by hand, or use an agent interview to generate it. Treat it as the local source of truth for how agents should speak and make trade-offs in this vault. `; -const GBRAIN_ACCESS_POLICY_MD = `--- +const ENTITY_VAULT_ACCESS_POLICY_MD = `--- title: Access policy -description: What the agent may read, write, and surface. gbrain's 4-tier privacy model, useful even without gbrain. +description: What the agent may read, write, and surface. A 4-tier privacy model for GBrain-style agent workflows, useful even without GBrain installed. --- # Access policy @@ -983,21 +1021,21 @@ description: What the agent may read, write, and surface. gbrain's 4-tier privac `; -const GBRAIN_HEARTBEAT_MD = `--- +const ENTITY_VAULT_HEARTBEAT_MD = `--- title: Operational cadence -description: When the agent does scheduled work: daily briefings, end-of-day dossier maintenance, weekly audits. If gbrain is installed, its \`dream\` schedule also lands here. +description: When the agent does scheduled work: daily briefings, end-of-day dossier maintenance, weekly audits. If you also use GBrain, note its sync/dream cadence here. --- # Heartbeat ## Daily -- **Morning briefing** (\`gbrain briefing\` or ad-hoc agent prompt): today's calendar + per-attendee dossier context. -- **End of day**: ingest the day's meeting notes; let \`dream\` (or a manual agent prompt) extract entity mentions and update dossiers overnight. +- **Morning briefing** (ad-hoc agent prompt, or \`gbrain briefing\` if you run GBrain): today's calendar + per-attendee dossier context. +- **End of day**: ingest the day's meeting notes; ask an agent to extract entity mentions and update dossiers. -## Nightly (\`gbrain dream\` if installed) +## Nightly (optional GBrain automation) -- 11-phase maintenance cycle: lint → backlinks → sync → synthesize → extract → patterns → recompute_emotional_weight → consolidate → embed → orphans → purge. +- If you run Garry Tan's \`gbrain\`, note the \`sync\` / \`dream\` cadence here so OK users know when the engine re-indexes this Markdown vault. ## Weekly @@ -1005,7 +1043,7 @@ description: When the agent does scheduled work: daily briefings, end-of-day dos ## Monthly -- Run OK's \`links({ kind: "dead" })\` across the vault. Triage redlinks into new entities (gbrain creates dossiers), typo fixes (OK edits in place), or removal (drop the link; a tracked task captures any future-doc intent). +- Run OK's \`links({ kind: "dead" })\` across the vault. Triage redlinks into new entities (agents create dossiers through OK), typo fixes (OK edits in place), or removal (drop the link; a tracked task captures any future-doc intent). `; @@ -1056,20 +1094,20 @@ export const STARTER_PACKS: Readonly> = { folders: WRITING_PIPELINE_FOLDERS, templates: WRITING_PIPELINE_TEMPLATES, }, - gbrain: { - id: 'gbrain', - name: 'Gbrain', + 'entity-vault': { + id: 'entity-vault', + name: 'Entity vault (GBrain-compatible)', description: - "Track people, companies, and meetings. Each gets a dossier with a rewritable summary and an append-only timeline. Inspired by Garry Tan's gbrain.", + 'Track people, companies, meetings, and concepts with dossiers: rewritable summaries plus append-only evidence timelines. GBrain-compatible Markdown; OK handles editing and review.', defaultSubfolder: 'vault', - folders: GBRAIN_FOLDERS, - templates: GBRAIN_TEMPLATES, + folders: ENTITY_VAULT_FOLDERS, + templates: ENTITY_VAULT_TEMPLATES, rootFiles: { - 'log.md': GBRAIN_LOG_MD, - 'USER.md': GBRAIN_USER_MD, - 'SOUL.md': GBRAIN_SOUL_MD, - 'ACCESS_POLICY.md': GBRAIN_ACCESS_POLICY_MD, - 'HEARTBEAT.md': GBRAIN_HEARTBEAT_MD, + 'log.md': ENTITY_VAULT_LOG_MD, + 'USER.md': ENTITY_VAULT_USER_MD, + 'SOUL.md': ENTITY_VAULT_SOUL_MD, + 'ACCESS_POLICY.md': ENTITY_VAULT_ACCESS_POLICY_MD, + 'HEARTBEAT.md': ENTITY_VAULT_HEARTBEAT_MD, }, }, };