0.6.4 — read-only graph query

agentforge-graph 0.6.4 — ask the graph anything structural

Theme: query. The CKG already answered questions through fixed, typed verbs
(ckg search, ckg impact, ckg routes, …) — each great for the question it
was built for, but a closed set. 0.6.4 adds the escape hatch: a read-only,
guard-railed structural query surface so any exact question over the graph is
answerable directly, without us shipping a new verb.

Highlights

ckg query --graph / ckg_query — a read-only Cypher subset (feat-015)

# "classes tagged Repository with no inbound CALLS", "interfaces implemented by many classes", …
ckg query --graph 'MATCH (c:Class)-[:IMPLEMENTS]->(i:Interface)
                   RETURN i.name, count(c) AS impls ORDER BY impls DESC'

ckg query --graph 'MATCH (f:Function) WHERE NOT (f)<-[:CALLS]-() RETURN f.name, f.path'
ckg query --graph '<q>' --format json      # {columns, rows, truncated, stopped_reason}
ckg query --schema                          # the queryable vocabulary

• The escape hatch, not a replacement. For semantic "find code about X" use
  ckg_search; for "who calls this" use ckg_impact. ckg_query is for precise
  structural questions with exact predicates — MATCH patterns (directions,
  bounded var-length [:CALLS*1..3]), WHERE (comparisons, AND/OR/NOT, IN,
  STARTS/ENDS WITH, CONTAINS, pattern existence), RETURN with
  count/min/max/avg/collect, ORDER BY/SKIP/LIMIT.
• Safe by construction. Caller text is never executed. It is parsed into a
  validated AST (the single trust boundary), then compiled to native Cypher
  (Kuzu, Neo4j) or interpreted over the storage API (SurrealDB, and any
  backend without a query language). Writes/DDL, procedure calls, unbounded paths,
  and un-joined Cartesian products are rejected with a clear reason — never a
  stack trace.
• Identical on every backend. A shared conformance suite proves Kuzu, Neo4j,
  and SurrealDB return the same rows for the same query.
• Bounded, no silent caps. query.max_rows / timeout_ms / max_expansions
  are enforced on every backend and reported via truncated + stopped_reason,
  so a partial answer is never mistaken for a complete one.
• For agents too. A capability-gated ckg_query MCP tool (present only when
  the backend is query-capable and query.allow_in_mcp is on) with the usual
  staleness envelope; ckg status reports the query-language version.

See the new guide: Ad-hoc structural queries.

Fixed

• Re-exported base classes now resolve. A base class imported via an absolute
  path and re-exported through a package __init__.py (e.g.
  class KuzuGraphStore(GraphStore)) previously produced no INHERITS edge. The
  resolver now binds through a package re-export namespace — improving INHERITS
  and CALLS recall for every consumer (retrieval, impact, repo-map), not
  just the query surface.

v0.6.3 — watch mode + CI indexing

agentforge-graph 0.6.3 — keep the graph fresh, automatically

Theme: freshness / ops. 0.6.2 made it one command to connect the graph to
your agent; 0.6.3 makes it automatic to keep it current. Re-indexing was
already cheap and incremental — now you don't have to remember to run it. A local
ckg watch loop tracks your working copy; a scaffolded CI workflow keeps the
shared central index fresh. The two target different stores, and the engine keeps
them apart.

Highlights

ckg watch — local freshness on a trigger you choose (feat-014)

pip install "agentforge-graph[watch]"
ckg watch                       # re-index on a trigger (on-commit by default)
ckg watch --trigger on-idle     # or reflect uncommitted edits when you pause
ckg watch --status              # trigger · store · last indexed commit · dirty?
ckg watch --once                # one refresh if dirty, then exit

• Won't churn or burn spend. Default trigger is on-commit — ordinary saves
  do nothing; the graph tracks committed state. on-idle / on-save /
  interval / manual are there when you want them, all debounced and
  single-flight so bursts coalesce. A watch refresh is structural-only by
  default (embed_on_watch / enrich_on_watch off), so it never runs embeddings
  or LLM enrichment per save.
• Branch-gated. Watches feature branches, skips main / release/* by
  default (watch.branches).
• Can't corrupt a shared store. ckg watch refuses a central
  (store.central_root) or read-only store — that split is enforced in the
  engine, so a developer's loop never races writes into the authoritative graph.

ckg ci init — deterministic central indexing (feat-014)

ckg ci init                     # write .github/workflows/ckg-index.yml
ckg ci init --print             # preview, write nothing
ckg ci init --extra bedrock --enrich

Scaffolds a self-contained workflow that indexes into the central store on
merge-to-main + nightly, single-writer (concurrency group, no write
races), incremental (only the diff since the last indexed commit). CI is the sole
authoritative writer, so read-only consumers can trust it. Managed-marker +
idempotent; won't clobber a hand-edited file without --force.

See the new guide: Watch mode & CI indexing.

Fixed

• Post-release verification no longer false-alarms (#148). postrelease.yml
  now triggers off the Release workflow completing successfully
  (workflow_run) instead of the GitHub release: published event — under
  on-demand OIDC publishing the release exists before the artifact reaches PyPI,
  so the old trigger polled too early and auto-opened a spurious failure issue
  each release.

v0.6.2 — ckg setup (agent auto-configuration)

agentforge-graph 0.6.2 — one command to wire the graph into your agent

Theme: adoption. 0.6 made it easy to build an org-scale code graph; 0.6.2
makes it easy to connect one. New ckg setup writes your coding agent's
MCP config for you — no hand-editing JSON — and (with --hooks) nudges the agent
to actually use the graph.

Highlights

ckg setup — agent auto-configuration (feat-013)

ckg setup            # detect agent → show a diff → confirm → write .mcp.json → connection check
ckg setup --print    # dry-run
ckg setup --hooks    # also add the "prefer the graph" nudge to AGENTS.md/CLAUDE.md
ckg setup --undo     # reverse everything it wrote

• Repo-level by default — writes a committable <repo>/.mcp.json (the
  portable MCP standard, read by Claude Code and other clients). Commit it and
  the whole team's agents are wired. --scope user writes the global
  ~/.claude.json instead.
• Safe on files you didn't author — edits are structural (never text
  splicing), marked (_managed_by: agentforge-graph), idempotent, and
  conflict-safe: a ckg entry you wrote is never clobbered without
  --force. Everything is reversible with --undo.
• Connection check — after writing, it spawns the server and confirms the
  agent can reach it (connected ✓).
• --hooks — appends a short, non-blocking nudge block to
  AGENTS.md/CLAUDE.md so the agent prefers the ckg_* tools over grep/glob.
• Extensible — new agents register via the
  agentforge_graph.agent_adapters entry-point group (Claude Code built in).

Frictionless first run (FA-001 Phase 1)

• Try it with zero install: uvx agentforge-graph index . /
  pipx run agentforge-graph serve-mcp --repo ..
• ckg --version now reports how it was launched, e.g. ckg 0.6.2 (uvx).

See the new guide: Agent auto-configuration.

Validation

• Gate: ruff + ruff format + mypy --strict clean; 903 passed / 45
  skipped, 94.71% coverage.
• Live end-to-end: a real MCP client (mcp SDK) connected to a spawned
  ckg serve-mcp → 10 tools; project/user scope, --hooks, conflict/--force,
  idempotency, and --undo exercised against a real repo; the uvx trial path
  verified from a built wheel.

Install / upgrade

pip install -U agentforge-graph        # 0.6.2
ckg --version                          # ckg 0.6.2 (pip)

No index-schema change — existing .ckg/ indexes are unaffected.

Full changelog

See CHANGELOG.md.

v0.6.1

Docs/packaging patch ahead of the repo going public. No code or behavior changes.

Changed

• Generalized third-party tool/protocol names out of the published docs, README, guides, and source comments, keeping the technical substance (e.g. "stable descriptor-based symbol IDs", "personalized-PageRank repo-map recipe"). Names of modules/backends the project actually integrates (tree-sitter, Kuzu, LanceDB, Neo4j, SurrealDB, pgvector, Bedrock, OpenAI, Anthropic, MCP, …) are unchanged.
• The prior-art / research survey is now local-only and no longer shipped in the source distribution (the wheel never contained it, so pip install was always unaffected).

Gate: ruff + ruff format + mypy --strict clean; 839 passed, 94.67% coverage.

pip install -U agentforge-graph

v0.6.0 — workspace build

The workspace build release — the build/setup side of org-central knowledge. 0.5 made consuming a central, federated graph easy; 0.6 makes building it easy: stand up a multi-repo CKG from one workspace.yaml + one config + one command, with fail-fast validation and (optionally) repos cloned from git URLs.

Highlights

• ckg build + --workspace (ENH-021) — index every member (and embed where enabled, --enrich for tags) in one command, with a per-member report.
• Workspace config cascade (ENH-022) — a defaults: block in workspace.yaml (or sibling ckg.yaml) inherited by every member, with per-member overrides. Configure the org once.
• Per-member embed toggle (ENH-023) — embed.enabled / embed: false; structure-only members build with no embedder (no creds).
• ckg doctor + fail-fast preflight (ENH-026) — validate config (drivers installed, credentials present) before any work, with the exact pip install / export fix; --workspace checks every member at once.
• Remote repo sources (ENH-024) — a member can be a git/github URL (git: + ref:), cloned into a managed, git-ignored .checkouts/ via your ambient git auth.
• ckg --version and config/CLI-controlled logging/tracing — logging.level in ckg.yaml, --log-level/--debug/-v, $CKG_LOG_LEVEL; traces index/embed/checkout/workspace-build end to end.

Deferred: ENH-025 (Voyage embedder) — raised upstream first.

Validation

839 tests / 94.67% coverage, mypy --strict + ruff clean. Verified end-to-end on sample repos and with a live AWS Bedrock build + semantic query.

Full notes: CHANGELOG.

v0.5.0 — org-level central knowledge

The org-level central knowledge release — take CKG from "indexes my one repo"
to "is my org's shared code brain": host the index centrally and consume it
read-only, serve a multi-repo workspace from one federated MCP endpoint,
and trace requests across services (HTTP client → route, matched by path or
OpenAPI contract). (Also: the scaffold template was upgraded to AgentForge 0.3.1.)

Added

• ckg services-map and ckg trace CLI commands (ENH-020). The cross-service
  call graph and request tracing — previously MCP-only — are now on the command
  line: ckg services-map --workspace workspace.yaml prints from → to edges
  (with handler + via), and ckg trace <service> --workspace … [--direction downstream|upstream] [--depth N] walks the graph (data flow /
  blast radius). See the org topology from a terminal, not just an agent.
• Microservices demo + end-to-end test for the org-central features. A
  bundled examples/microservices workspace (web→gateway→orders→payments,
  spanning JS fetch, Python httpx/requests, and a contract-first OpenAPI
  service) with a runnable walkthrough, plus an automated e2e test that exercises
  ENH-018 (central hosting + read-only), ENH-019 (cwd discovery) and ENH-020
  (federation + ckg_services_map + ckg_trace) in one flow — the demo is the
  test fixture, so they can't drift.
• OpenAPI contract anchoring for the cross-service map (ENH-020 C-full). When
  a member ships an OpenAPI/Swagger spec (openapi.{json,yaml,yml} /
  swagger.{json,yaml} at the repo root), service_map now matches calls against
  the declared contract too — giving authoritative paths, the operationId as
  the handler, and coverage for contract-first services with no detected
  framework. A framework route and its spec twin are deduped (param-agnostic) so
  they never make a call ambiguous; each edge reports its via (framework |
  openapi). Precision + coverage upgrade over URL-string matching alone.
• JS/TS cross-service calls (fetch / axios) (ENH-020 C-full). A new
  jshttpclient pack (spanning .js + .ts) captures fetch("…"),
  axios.get("…") / axios.post("…") and axios("…") as ServiceCall nodes —
  fetch's method read from a literal { method: "POST" } option, default GET.
  So a JS/TS frontend or BFF now appears as a caller in the cross-service map /
  ckg_services_map / ckg_trace, not just Python services.
• HTTP client coverage: instance clients + base_url (ENH-020 C-full). The
  httpclient pack now also captures calls through a client instance —
  s = requests.Session(); s.get(…) and c = httpx.Client(base_url="http://orders"); c.get("/v1/x") — composing base_url + path into the matched URL. This is the
  dominant real-world pattern (previously only module-qualified requests.get(…)
  with a literal URL was seen), so the cross-service map covers far more actual
  calls. Still conservative: dynamic URLs are counted, not guessed.
• ckg_trace — walk a request across services (ENH-020 C-full). From a
  starting service, trace the cross-service call graph downstream (what it
  calls — data flow) or upstream (who calls it — blast radius), to a depth.
  Returns the reachable hops (with hop numbers) and the services reached; cycles
  terminate. Turns the ckg_services_map edges into the answer to "what does
  this service depend on / which services break if I change it" — impact
  analysis that spans service boundaries. Federation-only tool.
• Cross-service call graph (ENH-020, C-full increment 2). The federated MCP
  server now draws who-calls-whom across services: it matches each member's
  outbound ServiceCall to a Route in another member by (method, path) —
  with path-parameter awareness ({id} / :id / <id>) — and exposes the org
  call graph via a new ckg_services_map tool (from_service → to_service,
  method, path, handler, plus unresolved calls). Computed live because member
  graphs are separate stores; unique-match-only (ADR-0004) — an ambiguous call is
  reported, never guessed. This completes the microservices payoff: an agent can
  see the whole org's service topology from one endpoint.
• Outbound HTTP client calls are captured (ENH-020, C-full increment 1).
  A new httpclient framework pack records module-qualified requests.get("…")
  / httpx.post("…") calls as ServiceCall graph nodes (method + URL + path),
  riding the caller file's subgraph like routes. Surfaced via
  CodeGraph.service_calls() and ckg service-calls. Conservative (ADR-0004):
  literal URLs only; dynamic URLs / client-instance calls are counted, not
  guessed. This is the caller side of a cross-service edge — at federation
  time these match Route nodes in other services (the next increment:
  ckg_services_map / ckg_trace).
• Federated MCP over a workspace (ENH-020, C-lite). ckg serve-mcp --workspace workspace.yaml serves many member repos/services from one
  endpoint. The survey tools (ckg_search, ckg_routes, ckg_decisions,
  ckg_status) fan across every member and tag each result with its service
  (with a per-service staleness envelope); the pinpoint tools (ckg_symbol,
  ckg_impact, ckg_neighbors, ckg_explain, ckg_history, ckg_repo_map)
  take a service to target one member. A single repo is unchanged (no
  services envelope). This is the microservices payoff of the
  org-central-knowledge theme — one code brain for the whole org. (Cross-service
  contract edges — tracing a request across services — are the next phase,
  C-full.) Also fixes the MCP _Engine to honor store.central_root (ENH-018).
• Read-only consumers (ENH-018). store.read_only: true (or --read-only /
  $CKG_READ_ONLY) makes a store consume-only: the write verbs (index,
  embed, enrich) refuse with a clear message and a non-zero exit, and opening
  a missing index errors instead of silently creating one. Read verbs
  (query, map, routes, serve-mcp, …) work normally. This is what lets a
  team host one central index (built by CI) and hand it to many developers and
  agents without risk of accidental mutation.
• Host the index outside the repo with store.central_root (ENH-018).
  By default the index stays in the gitignored .ckg/ inside the repo (the
  laptop story, unchanged). Set store.central_root: /shared/ckg and each repo's
  artifacts move to a stable, collision-free per-repo subdir under that root
  — keyed by git remote (org/repo, host-independent) or <dirname>-<hash> with
  no remote — so a team/CI can build once and host many repos centrally. The
  .ckg root is now resolved through one helper (store.location.resolve_root),
  de-duplicating ~10 call sites. ckg status shows the resolved location
  ((central) when hosting is on). First rung of the org-central-knowledge theme.
• ckg now discovers the repo root from the working directory (ENH-019).
  When no path is given, every subcommand — including ckg serve-mcp — walks up
  from the cwd to the nearest .ckg/ / agentforge.yaml / ckg.yaml / .git
  (nearest wins), like git. So a bare ckg serve-mcp from anywhere inside a
  repo serves that repo — no --repo needed — which is what an MCP client
  launching the server in a project directory wants. Falls back to . when no
  marker is found (unchanged for a bare directory); an explicit positional /
  --path / --repo always wins; when discovery climbs above the cwd the
  resolved root is announced on stderr. First rung of the org-central-knowledge
  theme (zero-config consumption).

Changed

• Getting-started guides reorganised by setup into three step-by-step
  walkthroughs — single repo,
  workspace, and
  central store — under a hub
  (01-getting-started.md, kept so existing links resolve). The 10 topic guides
  are unchanged.
• README refreshed for the three setups with a new docs/assets/setups.gif
  (single repo → central store → workspace services-map / trace), rendered by
  scripts/render-setups-gif.sh.
• Scaffold template upgraded to AgentForge 0.3.1 (agentforge upgrade); the
  files we own are forked so future upgrades skip them.

v0.4.0

agentforge-graph 0.4.0 — framework awareness goes wide, retrieval gets measured, config gets simpler.

Highlights

• SurrealDB storage backend (ENH-010) — graph + vectors in one server, conformance-verified.
• Cross-file framework resolution (ENH-011) — include_router prefix composition + DI grounding (FastAPI).
• Four new route packs (ENH-012) — Gin (Go), ASP.NET (C#), Laravel (PHP), Rails (Ruby) → 11 packs across 6 languages, plus generic cross-file route-handler grounding.
• Bedrock-native reranker + measured benchmark (ENH-013) — torch-free Bedrock Rerank; an objective NL→code benchmark (388 queries / 4 OSS repos) shows base retrieval MRR 0.95 / recall@1 0.92 and a statistically-significant rerank lift (ΔMRR +0.019, p<0.001). See the README "Retrieval quality (measured)".
• One config file — engine config consolidated into agentforge.yaml under app: (auto-discovered; plain pyyaml, ADR-0001); ckg.yaml standalone still supported.
• HTTP MCP auth now rides the framework's from_http(middleware=) seam (no reimplemented runner).
• Developer guides (numbered learning path + TL;DRs) incl. a Getting-started walkthrough, a demo GIF, community health, and the AgentForge pin bumped to >=0.3,<0.4.

Full detail: CHANGELOG.

Verification: 724 tests / 95% coverage / ruff + mypy clean; live Bedrock embed + rerank, live MCP HTTP auth, and Neo4j/pgvector/SurrealDB conformance all green. PyPI publish to follow after manual validation.

v0.3.3

[0.3.3] - 2026-06-19

Leaner base install + the refreshed README on PyPI.

Changed

• Dropped the unused fastembed dependency from the base install (and the
  heavy onnxruntime wheel it pulled). It was a leftover from the original
  feat-005 plan to default to local embeddings; the shipped embedders are
  bedrock / openai / fake, none of which import it. Removing it keeps the
  promise true: the base install carries only what the engine actually uses, and
  every model/DB provider is opt-in. (No local-embeddings driver existed, so
  nothing is lost; a fastembed driver behind a [local] extra can be added as
  a deliberate feature later.)
• README refreshed (out-of-the-box overview, quick start, demo) now renders on
  the PyPI project page.

v0.3.2

[0.3.2] - 2026-06-19

Packaging fix — base-install completeness (caught on a TestPyPI dry run).

Fixed

• pip install agentforge-graph now works out of the box. The deterministic
  graph engine dependencies (tree-sitter, tree-sitter-language-pack, kuzu,
  lancedb, fastembed, networkx) moved from the optional engine extra into
  the base dependencies — the package's top-level import chain loads the
  parse/store/embed/repo-map stack, so a bare install previously failed at
  import agentforge_graph with ModuleNotFoundError: No module named 'kuzu'.
  The engine extra is kept as an empty no-op for backward compatibility
  (pip install agentforge-graph[engine] still resolves).

v0.3.1

[0.3.1] - 2026-06-19

Packaging release — the PyPI debut. No functional changes.

Packaging

• Add PyPI distribution metadata: readme (renders the README on the project
  page), keywords, and trove classifiers.
• Pin the AgentForge framework dependencies (agentforge-py,
  agentforge-anthropic, agentforge-mcp) to the validated >=0.2.4,<0.3
  line, so a fresh pip install resolves the framework version this release was
  built and tested against (rather than an unvalidated newer line).