Skip to Content
Live OKF Context Sync

Live OKF Context Sync

Sync a Google Open Knowledge Format (OKF) context folder across every client and agent a user runs — laptop, browser, local agent, and cloud agent — without building a custom realtime backend.

This example is intentionally minimal: write kalam/schema.sql, run kalam dev, edit OKF Markdown on disk, and watch metadata updates flow live to the UI and demo agent.

Source: examples/live-okf-context-sync/

Showcase only. KalamDB does not ship folder sync as a core feature. This app demonstrates how to layer OKF context sync on top of SQL metadata, file upload/download, and live subscriptions.

What is Google Open Knowledge Format (OKF)?

Google Open Knowledge Format (OKF) is a folder of Markdown files agents and tools can read as structured context: profiles, project notes, runbooks, policies, and preferences. OKF files often include YAML frontmatter (title, type, tags) so agents know what each document is for.

Teams adopting OKF usually need the same folder available everywhere the user works:

  • A local agent on the laptop
  • A cloud agent in the browser or on a server
  • A web UI for preview and status
  • Multiple devices editing the same OKF paths

This example shows how KalamDB coordinates that shared state.

What it does

  • Watches a local Google Open Knowledge Format (OKF) folder (context/alice/, context/bob/)
  • Uploads Markdown file bytes through KalamDB file upload
  • Stores metadata only in a user-scoped SQL table (path, sha256, frontmatter, conflict flags)
  • Pushes live metadata updates to subscribers — no page refresh
  • Lets a demo agent download canonical OKF files from KalamDB instead of reading disk
  • Keeps per-user isolation (Alice cannot see or download Bob’s context)
TEXT
OKF folder on device A          OKF folder on device B        |                                |        v                                v   sync worker                      sync worker        \                              /         v                            v              KalamDB (metadata + file bytes)                        |            +-----------+-----------+            |           |           |         web UI    local agent   cloud agent      (live list)  (downloads)  (downloads)

Why KalamDB for OKF context?

NeedHow this example solves it
Same OKF folder on multiple clientsEach client runs a sync worker; metadata rows are the shared source of truth
Local agent + cloud agent both need contextBoth subscribe to SQL metadata and download files by file_ref when needed
Realtime UI without websockets codelive() on a metadata SELECT
Per-user privacyUSER TABLE scopes rows and file downloads per user
Minimal setupschema.sql + kalam dev — no ORM, no generated schema

Prerequisites

  • Node.js 18+
  • Kalam CLI with kalam dev support (kalam self-update or build from source)

Quick start

BASH
cd examples/live-okf-context-syncnpm installkalam dev

Then:

  1. Open http://127.0.0.1:5177
  2. Sign in as alice (default)
  3. Edit context/alice/profile.md — an OKF profile Markdown file
  4. Watch the file list update live
  5. Ask the demo agent: npm run dev:agent -- "Who is Alice?"

kalam dev starts KalamDB Server, applies kalam/schema.sql, and runs three processes:

TOML
[dev.processes]sync = "npm run dev:sync"web = "npm run dev:web"agent = "npm run dev:agent"

Default credentials:

RoleUserPassword
Server admin (kalam dev)rootkalamdb123
Demo user Alicealicealice123
Demo user Bobbobbob123

Multi-client OKF sync flow

When an OKF Markdown file changes on disk:

  1. The sync worker computes sha256
  2. Parses YAML frontmatter from the Markdown file
  3. Uploads file bytes first (never writes metadata before upload completes)
  4. Compares base_sha256 with the server hash for conflict detection
  5. Updates the canonical row or creates a dated conflict copy
  6. Live subscribers (web UI, agents) receive the metadata change immediately

Conflict policy: the faster writer keeps the canonical path (for example profile.md). A stale writer from another client creates profile.conflict-{timestamp}.md so nothing is silently lost.

Schema source of truth

The database schema lives only in:

TEXT
kalam/schema.sql

Not schema.ts, Drizzle, or generated TypeScript types. kalam.toml sets generate_types = false.

File content is not stored in SQL columns. OKF bytes use KalamDB upload/download; SQL stores paths, hashes, frontmatter, and sync state.

What to try

Scenario 1: First sync

With context/alice/index.md and context/alice/profile.md present, run kalam dev. Files upload and metadata rows appear in the UI.

Scenario 2: Live edit across clients

  1. Keep the web UI open as Alice
  2. Edit context/alice/profile.md in your editor
  3. The table updates without refresh — the same live row a cloud agent would see

Scenario 3: Local agent and cloud agent share context

  1. Run npm run dev:agent -- "What projects is Alice working on?"
  2. Edit context/alice/projects/kalamdb.md
  3. Run the agent again — it reads the updated OKF file from KalamDB, not from disk

Scenario 4: Per-user isolation

Switch the UI to bob. Bob only sees his own context_files rows and cannot download Alice’s files.

To sync Bob’s OKF folder, run: KALAM_SYNC_USER=bob npm run dev:sync

Files worth reading

FilePurpose
kalam/schema.sqlSingle user-scoped metadata table — the only schema source
kalam.tomlkalam dev wiring with generate_types = false
src/sync-worker.tsWatches OKF folder, uploads bytes, writes metadata
src/web.tsxLive metadata table with preview/download
src/agent.tsDownloads canonical OKF files for demo answers
src/conflicts.tsSimple last-writer-wins conflict copies

Verify it works

BASH
npm test

With kalam dev running:

BASH
npm run test:e2e

Integration tests against a live server:

BASH
KALAM_INTEGRATION=1 npm test

Next steps

Last updated on
OverviewRealtime Ops Feed