Architecture

Knowledge graph

The project's memory: data mirrors, context, and the generated brief.

A project built across many working sessions needs a memory. The knowledge graph holds both the live data and the reasoning behind it — decisions, constraints, gaps, failures and dated notes — so the next session starts from what is true, not from scratch.

Two layers, one store#

Data layer: Mirrors of companies, roles, people, emails and replies, plus your profile and skills. Rebuilt by kg sync after every cycle; never edited by hand.
Context layer: Seeded from knowledge/context.yaml: the problem, decisions, constraints, guarantees, features, stages, modules, gaps, failure modes and open questions — plus dated notes from kg note.

Both live in jobhunter.db as kg_node, kg_edge and an FTS5 index kg_fts. There is no graph database (D10); NetworkX loads the graph when analysis needs it.

The shape of the data#

profile:me ─HIGH_MATCH→ job ─POSTED_BY→ company ←WORKS_AT─ contact ←SENT_TO─ email ←REPLIES_TO─ reply

Plus USES_ATS, FOUND_VIA, HAS_SKILL, FUNDED_BY, AFFILIATED_WITH, PREVIOUSLY_AT and IN_CITY. Those power the warm paths on a company page (who you might reach through whom) and “similar companies” (shared investors and skills).

The brief#

knowledge/BRIEF.md is generated from the graph: the problem, live pipeline counts, constraints and guarantees, settled decisions, what exists per stage, gaps in build order, failure modes, open questions, the module map and a dated session log. It is rewritten daily by the paid tick and on every kg build.

Everyday use#

terminal

python scripts/run.py kg build                        # reload context + sync data + BRIEF.md + viewer
python scripts/run.py kg search "warmth"              # full-text, both layers
python scripts/run.py kg show feature:warmth-tiers    # a node and its neighbours
python scripts/run.py kg path contact:3 constraint:send-cap-25
python scripts/run.py kg why "Skylo Technologies"     # write to them? to whom? why?
python scripts/run.py kg note "what changed" --about gap:1-send-ledger

Command	Answers
kg hubs	The most load-bearing nodes (betweenness centrality)
kg compose	The best feature per stage across all architecture drafts
kg shortlist	Targets ranked by grade, hiring, skill overlap and reachable people
kg expand	Companies funded by the same investors, two hops out
kg guard	May we write to this person or company now? (cooldowns)
kg audit	Contradictions inside the graph

The working rule

When a piece of work is finished, record it with kg note … --about <ids>. When a decision changes or a feature moves from gap to built, edit its status in context.yaml and run kg build.

The dashboard's Graph page draws the same graph as a star map: distance is bet quality, a filled star is a complete company, a ring is one still filling.