KFS Setup Playbook
forge
knowledge-graph
setup-guide
· 2026-03-17 · No new accounts required
What this sets up: The Forge shared brain — every Ralph loop, every Telegram voice memo, every session decision saved and connected. Phone capture working in 2 minutes (Supabase SQL only). Full graph intelligence in 15 minutes (+ Docker setup).
What you need: VPS terminal access (dashboard Terminal tab works) + Supabase browser. No new accounts.
📱 Fast Path — Phone Capture in 2 Min
Gets /note, voice memos, and file uploads working from your phone. Ralph builds the rest after you run the SQL.
1 Open Supabase SQL Editor
Go to supabase.com → your project → SQL Editor
2 Paste and run the migration SQL
File is at
/opt/forge/scripts/kfs-schema-migration.sql on VPS. Copy the contents (cat it from the terminal tab) and paste into SQL Editor → Run.
cat /opt/forge/scripts/kfs-schema-migration.sql
✓ You should see: "Success. 0 rows affected" (or similar — no errors)
3 Verify tables were created
Paste this in SQL Editor and run:
SELECT table_name FROM information_schema.tables
WHERE table_name IN ('kfs_episodes', 'kfs_brain_events');
✓ You should see 2 rows returned
4 Send a test note from Telegram
(After Ralph deploys Phase C.5 — usually within 30 min of SQL completion)
In your Forge Telegram bot:
/note testing KFS capture from phone
✓ Bot replies: "Saved to your vault ✓"
That's it for the fast path. Ralph builds the rest automatically.
🧠 Full Path — Graph Intelligence in ~15 Min
Adds Graphiti + FalkorDB: temporal facts, entity deduplication, /drift, /trace. Run the fast path first, then do these.
All code is pre-built at /opt/forge/services/kfs-graphiti/ — docker-compose, Python service, systemd unit. Nothing to write.
5 Open VPS terminal
Dashboard → Terminal tab, or SSH: ssh forge@178.156.253.142
6 Start FalkorDB (graph database)
docker compose -f /opt/forge/services/kfs-graphiti/docker-compose.yml up -d
✓ You should see: "Container kfs-falkordb Started"
7 Verify FalkorDB is running
docker ps | grep falkordb
✓ You should see: kfs-falkordb ... Up N seconds ... 6379/tcp
8 Install Python dependencies
cd /opt/forge/services/kfs-graphiti && pip3 install -r requirements.txt
✓ You should see: "Successfully installed graphiti-core fastapi uvicorn ..."
9 Add environment variable
In terminal:
echo 'KFS_GRAPHITI_URL=http://localhost:5020' >> /opt/forge/.env.system
✓ No output = success
10 Install and start the kfs-graphiti service
This queues the install via privileged-exec (auto-runs in ~30 seconds):
bash /opt/forge/scripts/lib/queue-command.sh "cp /opt/forge/services/kfs-graphiti/forge-kfs-graphiti.service /etc/systemd/system/ && systemctl daemon-reload && systemctl enable --now forge-kfs-graphiti" "install kfs-graphiti"
✓ Check after 60s: curl http://localhost:5020/health returns {"status":"ok","graphiti_ready":true}
11 Tell the bot you're done
In Telegram:
/note KFS full setup complete — FalkorDB running, Graphiti active
✓ This becomes the first entry in your jason vault with graph intelligence active
🔄 What Happens Automatically (Ralph + Forge)
After Phase A SQL runs, Ralph will build these automatically (in order):
- Phase B — Knowledge Service v2 endpoints (dual-write Supabase + Graphiti)
- Phase C — Ralph brain events + pre-task context briefs (Ralph gets smarter)
- Phase C.5 — Telegram /note command + voice memo transcription + file upload processing
- Phase D — Session harvester (Claude Code sessions → claude-code vault)
- Phase E — /recall, /drift, /trace Telegram commands
- Phase F — Daily Notes delegation scanner (/ralph X in any note auto-queues to Ralph)
📲 Phone Usage After Setup
| What you want to do | Command | Goes to |
|---|
| Save a quick idea | /note your idea here | jason vault |
| Dictate a voice memo | Send a voice message (no command) | jason vault (auto-transcribed) |
| Upload a PDF or file | Send the file (no command) | jason vault (auto-extracted) |
| Search everything | /recall what you remember | All vaults — results with sources |
| Delegate to Ralph | /ralph task description | ralph_queue (auto on next reconcile) |
| Entity timeline | /trace Brian Muka | Temporal fact chain |
| Priority drift check | /drift | Stated vs actual agent behavior |
🗂 Vault Architecture
| Vault | Who writes | What it stores | Trust |
|---|
| jason | You only (RLS-protected) | /note, voice memos, files, Daily Notes | Highest — never overwritten by agents |
| agent:ralph | Ralph (auto) | Task outputs, learnings, failure patterns | Medium-low |
| agent:claude-code | Claude Code (session end) | Decisions, architectural patterns, session summaries | Medium |
| agent:bot | Commander bot | Conversation extracts, intents | Medium-low |
| curated | Ingestion agents | Google Drive, RSS, web research | Medium |
⚡ In a Hurry?
Minimum viable setup — just Steps 1-4 (fast path). You get phone capture. Skip everything else until you're back from vacation. Ralph builds the intelligence layer in the background.
Total time: 2 minutes (fast path) or 15 minutes (full path).
Forge Collective Intelligence — PRD at Vault/projects/forge-collective-intelligence/PRD.md