Forge KFS: The Knowledge Fabric Service

forge knowledge-graph graphiti infrastructure · March 25, 2026

Every Claude Code session accumulates decisions, patterns, and context. KFS (Knowledge Fabric Service) is the layer that captures this context, extracts the structure from it, and builds a temporal knowledge graph — so future sessions, Ralph tasks, and the dashboard can query what was decided, what was built, what was blocked, and why.

The Core Idea

Without KFS: every session starts cold. With KFS: every session is aware of the full history — every decision made, every pattern confirmed, every connection drawn between Forge components. The graph compounds with time.

Architecture

KFS is two services operating in layers:

Service	Port	Responsibility
`knowledge`	5012	Supabase-backed entity/relationship store. Ingests Gmail, Calendar, Drive. Vector search.
`kfs-graphiti`	5022	Temporal graph via Graphiti + FalkorDB. Stores episodes (sessions, events) → extracts entities → builds relationships with time windows.

The graphiti layer is what makes KFS different from a plain database: every fact has a valid_at and invalid_at timestamp, so the graph can answer "what was true at this point in time" rather than just "what is true now."

The Harvest Pipeline

The harvest script reads Claude Code session JSONLs and feeds them into the graph automatically:

~/.claude/projects/*.jsonl → harvest-session.py → extract assistant messages → POST /v1/ingest → Graphiti (gpt-4o-mini) → FalkorDB graph

How it works

Reads the N most recent session JSONL files from ~/.claude/projects/-opt-forge/
Extracts assistant messages (skips thinking blocks, tool calls, tool results)
Prioritizes messages containing: DECISION, PATTERN, BLOCKED, BUILT, RESOLVED, FIXED, DEPLOYED
Builds an 8,000-char summary (chronological, marker-heavy messages given priority)
Deduplicates via sha256(filepath+mtime) — never re-processes a session
POSTs to kfs-graphiti which uses GPT-4o-mini to extract entities + relationships
Logs to /opt/forge/logs/kfs-harvest.log

Runs automatically every 30 minutes via forge-kfs-harvest.timer systemd unit. Processes the 5 most recent sessions. Dedup ensures no wasted work.

What the Graph Captures

Each session is ingested as an episode in the claudecc vault. Graphiti automatically extracts:

People — Jason, Ralph, team members, external contacts
Services — Commander, ClawdRouter, Knowledge, Gateway, etc.
Projects — Forge, MasteryOS, MasteryBook, NowPage, KFS
Decisions — architectural choices, routing policies, cascade configs
Patterns — recurring solutions, anti-patterns, confirmed approaches
Relationships — "service X calls service Y", "decision A unblocked work B"

Querying the Graph

# Semantic search across all sessions
curl -X POST http://localhost:5022/v1/query \
  -H "Content-Type: application/json" \
  -d '{"query":"cascade routing decisions","group_ids":["claudecc"],"limit":5}'

# Timeline for a specific entity
curl "http://localhost:5022/v1/timeline?entity=ClawdRouter&group_id=claudecc"

# Knowledge service search (Supabase vector)
curl "http://localhost:5012/v1/search?q=who+works+on+GTM"

Vault Namespaces

group_id	Source	What's in it
`claudecc`	harvest-session.py	All Claude Code session decisions/patterns
`ralph`	ralph.sh (planned)	Ralph task completions, errors, patterns
`jason`	knowledge service	Gmail, Calendar, Drive entities
`curated`	manual	Hand-crafted canonical facts

Second-Order Effects

What a populated graph unlocks

Session continuity — Every new CC session can query "what did we decide about X?" without relying on MEMORY.md
Ralph context injection — Before Ralph starts a task, query the graph for relevant prior decisions. Fewer mistakes.
Dashboard intelligence — "Show me everything we know about the MasteryOS auth layer" as a live graph visualization
Pattern detection — "We've blocked on this 3 times — here's why it keeps failing"
Dependency mapping — Automatically trace service → service → decision chains
Temporal context — "What was the state of the cascade router on March 10?" — answerable from the graph

How to Use It Now

# Harvest the current session manually
python3 /opt/forge/scripts/kfs/harvest-session.py --recent 1

# Backfill historical sessions
python3 /opt/forge/scripts/kfs/harvest-session.py --backfill 50

# Force re-harvest a session
python3 /opt/forge/scripts/kfs/harvest-session.py --recent 1 --force

# Query what the graph knows about a topic
curl -X POST http://localhost:5022/v1/query \
  -H "Content-Type: application/json" \
  -d '{"query":"YOUR QUESTION","group_ids":["claudecc"],"limit":5}'

Current status (March 25, 2026): Graph seeded with 3 sessions, backfill of 100 sessions running. Timer installed. ClawdRouter restarted with improved Telegram quality (Groq 70B before Llama 3B). Next: add graph visualization to dashboard, wire Ralph task completions into the ralph vault.

Files

Path	Purpose
`scripts/kfs/harvest-session.py`	Core harvest script
`scripts/kfs/harvest-session.sh`	Bash wrapper (uses kfs venv)
`services/forge-kfs-harvest.service`	systemd oneshot service
`services/forge-kfs-harvest.timer`	systemd timer (every 30min)
`services/kfs-graphiti/main.py`	Graphiti FastAPI service (port 5022)
`logs/kfs-harvest.log`	Harvest run log
`logs/kfs-harvested.txt`	Dedup index (sha256 hashes of processed files)