Five situations where a knowledge graph changes what an engineer or an agent can do — framed by the outcome, not the mechanism. Each one is honest about where it stops helping.
The first hour in an unfamiliar codebase is the most expensive hour an agent (or a new hire) spends — grep the obvious names, open the wrong file, guess at the architecture from folder names. The outcome you want isn't "a graph exists" — it's being able to ask a real question and get a cited answer in the first minute.
cd unfamiliar-repo ctx-optimize up # no config → bootstraps + gathers; existing config → pulls or refreshes ctx-optimize hubs --top 10 # the load-bearing nodes — usually the real entry points ctx-optimize query "how does auth work"
A queryable map of the repo before you've read a single file end to end — signatures, doc comments, callers, and (if the repo has them) route bindings and dependency edges, all cited to file:line. The generated wiki/ gives a second way in: a readable, regenerated-on-every-gather markdown map that names your symbols instead of showing raw graph dumps. If a teammate already gathered and shared the store (remote pull), up gets you their graph instead of re-doing the work.
change-plan and affected.The dangerous part of a refactor isn't writing the new code — it's not knowing everything that depends on the old shape. The outcome you want is a single, trustworthy answer to "if I change this, what do I have to also touch or re-test" — before you touch anything.
ctx-optimize change-plan validateRefund
One composed call — the signature, every caller, the blast radius to a bounded depth, which tests to run (affected nodes filtered down to test declarations), and historical co-change data pulled from git log, all in one answer instead of a query→card→affected→grep chain. Confidence is split honestly: extracted (parsed fact) vs inferred (name-matched) evidence, so you know which lines to double-check by hand and which you can act on directly (see EXTRACTED vs INFERRED). Measured on this project's own source: 229 tokens in one call vs 2,270 tokens across the chain it replaces — about 90% fewer answer tokens for the same question.
Want just the blast radius, no test/caller framing? ctx-optimize affected X --depth N is the narrower verb underneath.
"What breaks if I change this" isn't only a refactor question — it's the question a reviewer, an on-call engineer, or a security auditor asks about a proposed change, a flagged function, or a shared dependency. The outcome is the same reverse-dependency walk change-plan uses, available standalone and composable.
ctx-optimize affected PaymentService --depth 2 ctx-optimize path "cmdAdd" "Store.Merge" # how do two symbols actually connect? ctx-optimize query "dev dependency" --json # pull dep: nodes into a script/CI check
A reverse-impact walk — every node that reaches the one you named, to whatever depth you ask for — with the same EXTRACTED/INFERRED confidence split as change-plan. Because dep: nodes federate across every build tool in the repo (package.json, go.mod, pom.xml, csproj+sln, Gradle, Cargo), asking "what depends on this shared library" answers across module boundaries in a polyglot repo, not just within one language's manifest.
A monorepo makes "just gather the whole thing" actively wrong: one giant graph means every query is ranked against modules nobody asked about, and one edit invalidates the whole store. The outcome you want is a store that costs what the change costs — edit one service, refresh one service.
cd my-monorepo ctx-optimize up # detects the monorepo, scans, writes config, fans out the gather # — or, with review before it commits to a module list: ctx-optimize scan # read-only preview — what WOULD be declared ctx-optimize init --scan --yes && ctx-optimize add . # curate config.json, then gather explicitly
One store per declared module, plus a root navigator — not a merged mega-graph (see how federation works). Ask a question inside services/billing and it answers from billing's store alone; a miss escalates repo-wide and labels which module actually answered. Editing one service re-gathers in a second or two — not the whole tree. Measured on apache/beam: 310 modules discovered at depth 8, all gathered in 14.5s, including maven modules nested inside other modules' resource trees. Adding a module to config.json and running up again gathers exactly that module — nothing else is touched, and a module removed from config is reported as an orphan, never silently deleted.
merge api worker --into everything gives you one combined (but now-stale-the-moment-either-side-changes) view. Source/test splits across separate directories need an explicit multi-path module declaration or calls between them won't resolve.A lot of "what does this system do" questions have their real answer outside the repo: a table your code reads but never declares in an ORM model, a Kafka topic, an OpenAPI contract another team owns. The outcome is asking a code question and a schema question in the same breath, with one citation format for both.
Markdown in the repo is gathered natively on every add/sync — headings become sections, nested by level, indexed the same way as code. No adapter, no flag.
ctx-optimize adapters help postgres # the setup card: value format, credential params, a paste-ready command export BILLING_DB_URL='postgres://reader:$PG_PASS@db.internal:5432/billing' ctx-optimize add BILLING_DB_URL # resolve → dial → capture → merge → recorded in config sources
Nine wire-protocol connectors — postgres, mysql, mongodb, redis, kafka, nats, s3, mssql, openapi — capture the logical shape a developer actually reasons about: system schemas skipped, a partitioned table collapses to one node with a partitions: N fact, samples bounded, every cap reported. Credentials are structural, not a policy you have to remember: argv and committed config carry env-var names only — a literal password in a committed entry is a hard error at load — and the resolution ladder (process env → repo-root .env → machine-global ~/.config/ctx-optimize/.env) means a teammate without the credential still runs up cleanly (one skip line, prior nodes stay) instead of failing the whole gather.
ctx-optimize remote push # runs YOUR declared script — a git repo, S3, anything # teammate: ctx-optimize up # pulls the prebuilt store instead of dialing the DB themselves
Only the person with credentials needs to dial the database. Once captured, the schema travels with the rest of the store through whatever `remote push`/`pull` script your team declared — nobody else needs the connection string.
--sources=always forces a re-capture) — this is a periodically-refreshed snapshot of external state, not a live query against production. Treat schema answers as "true as of the last capture," and for anything time-sensitive, dial the source directly instead of trusting the graph.