Repository navigation
Changelog Highlights
Curated, human-readable release summaries. For the complete, authoritative history (every fix, every migration), read CHANGELOG.md.
This page lags CHANGELOG.md on purpose — it's the "what matters" view, not the ledger.
Wiki pages' ```mermaid fences now render as actual diagrams in the dashboard detail view — client-side mermaid.js (strict security level), degrading to the visible code block offline. No new Python dependency. Also: a second-boundary timestamp flake in the OKF round-trip tests is pinned.
Focus: cairn can now grow a wiki, not just report one — a port of the "Generate Project wiki" idea, cairn-native: the graph plans the outline, agents write the pages, the critic gates every word.
-
cairn wiki generate --llm: a deterministic catalog planner (overview + top modules ranked by cross-module incoming degree,--pagescap) queues onewiki-pagetask per page in the agent-decoupled task queue — cairn still never calls an LLM itself. Task completions are critic-gated (the## Sourcesfooter is the wiki quality signal; every backtick and footer entry must resolve in the graph) and promoted asWiki-Articleconcepts with verifiedsourcesfrontmatter; failing attempts run the bounded revise cycle. -
Incremental by construction: a
.knowledge/_wiki/manifest.json({repo}/{page_id}rows, atomic writes) skips unchanged+promoted or already-queued pages;--forcere-queues everything;wiki status/wiki retryre-queue exactly the failed/dropped pages with fresh chains. -
--refine-catalogqueues awiki-catalogtask so an agent can reorganize the deterministic outline first; entries naming modules absent from the graph revert positionally to the deterministic plan. -
New surfaces: the
wiki_generateMCP tool (the server is now 28 tools) and a dashboard wiki tab (state badges, rendered markdown + sources via a stdlib escape-first renderer — no new dependency). - Also in this release: the dashboard graph tab's curated default view (degree-ranked, tests excluded) with its inspect side panel, deep links from callers/callees/impact rows into the symbol graph, full landing coverage of every sidebar view, and the mypy type check promoted to a hard CI gate.
Spec-driven build (task/decision records in git history).
Focus: custom CAIRN_HOME installs work end-to-end — the root cause of
#70, where a client-spawned
server silently resolved an empty default store.
-
Every generated integration now carries the store location: stdio MCP
registrations embed
env.CAIRN_HOMEacross all nine client shapes (the Claude global-scope registration uses the verifiedclaude mcp add -eform), generated hook commands and the git post-commit template embed the assignment, and the LaunchAgent plist propagates it to the SSE daemon. Default-home installs generate byte-identical configs. -
Missing stores fail loudly: the error names the resolved path, the env
resolution chain, and the remediation — on both the server boot and CLI
paths — instead of a raw
sqlite3.OperationalError. -
Two verification layers:
cairn install-agentsspawn-verifies every written stdio registration (per-client PASS/FAIL naming both stores on mismatch), andcairn doctorgains a tenthenvironmentcheck (store existence, registration consistency with mixed severity, platform/transport supportability, binary coherence).cairn config --jsonis a new read-only resolution probe. - A changed-
CAIRN_HOMEreinstall now refreshes stale env in the zcode/opencode/kilo config shapes.
Spec-driven build (task/decision records in git history).
Focus: embeddings via any OpenAI-compatible /v1/embeddings server —
oMLX, Ollama, LM Studio, llama.cpp, vLLM — with zero torch in the cairn
process. CAIRN_EMBED_BACKEND gains server/omlx/ollama; a parity gate
(≥0.98 mean cosine on 16 stored chunks) verifies any producer switch before
writing, so moving local bge-m3 to a server serving the same weights costs
zero re-embeds. When a backend disappears, retrieval degrades in verified
steps (same-server alias → parity-verified local → BM25/RRF hybrid, never
hash) and every degradation fans out to logs, telemetry, an MCP footnote, a
doctor entry, and a dashboard banner. New persistent
~/.cairn/config.json (env > file > default, hot re-read) with dashboard
Settings + Embeddings views, and expanded cairn doctor embed checks.
-
cairn knowledge ingest— staged multi-source ingestion: repo doc-tree scans, fed markdown, and pdf/docx conversion (behind the newcairn[ingest]extra), one parse/classify/stage path into an OKF outbox with a dry-run manifest;--ingestexecutes, embeds, and verifies. -
install-agentsgains the omp CLI (MCP + two native subagent files). - The entire
docs/set rewritten from a fresh code survey (agent-first, every identifier verbatim from source); legacy docs and the oldspecs/tree removed.
- Kotlin on the fwcd grammar, vendored in-tree and compiled into per-platform wheels (macOS arm64, manylinux ×2, Windows) — modern syntax parses clean; musllinux and Intel macOS are deliberately not shipped (upstream wheel gaps). The dashboard gets a GitNexus-inspired visual overhaul with live typeahead graph search.
-
install-agentsclient/transport fixes: kilo + omp-shaped registrations (0.14.4), SSE-by-default everywhere (0.14.3), zcode global scope writes the file the CLI actually reads (0.14.3), agy gets its documentedserverUrlshape (0.14.4 — the previous entry was silently ignored). - Embed-deps robustness (0.14.1/0.14.2): per-interpreter-ABI shared-lib dirs fix the unrepairable mixed-ABI corruption; quiet single-line progress for install/model-download/upgrade instead of pages of noise.
cairn dashboard grows from a graph window into a full console for months
of recorded agent traffic: machine-wide workspaces launcher with live store
switching, session-grouped tool-call chains, per-tool token estimates,
time windows + keyset pagination (10.5k calls in budget), live auto-refresh,
cross-view drill-downs, usage retention, CSV/JSON export, dark theme. MCP
tool calls and CLI invocations are both recorded into tool_metrics.
cairn eval gains k-fold cross-validation; a cross-corpus DS-v2 ground
truth (198 queries, seal-verified in CI) lands; IDF enrichment, RM3
pseudo-relevance feedback, and multi-vector embeddings are measured for the
first time. Multivector cleared DS-v1 targets but was refuted zero-shot on
DS-v2 — nothing shipped, and the honest verdict lives in the unified
ablation record. 0.12.1 restructured README + docs as a product surface.
Impact queries from the precomputed closure (20.9 ms → 0.1 ms p50); server
connection pooling (11.7×) + model pre-warm (first semantic query 9.4 s →
0.3 s); confidence-gated rerank; incremental cairn update maintains
derived indexes (1,000-file single-file update 377 s → 9.7 s); live file
watching with the [watch] extra (save → queryable in ~2 s); the
agent-effort benchmark measures 99% fewer tool calls and 99.5% fewer
tokens vs a grep/read control. numpy became a core dependency.
A local-only event pipeline (events + build_runs tables) gives every
previously-silent degradation a durable signal; cairn doctor debuts with
its health checks (now exit-code gateable), cairn metrics --builds/ --quality/--contention trends, a redacted cairn report for bug reports,
optional OTLP export (strictly opt-in), and the after-task cairn doctor
step in the agent workflow. make ci-local replicates CI in a clean-room
Apple container (no Docker).
Parser coverage jumps to 14 languages (C# with namespaces and records,
C with typedef struct and field-expression calls, C++ with templates and
inheritance). recall_memory falls back to semantic similarity when
lexical matching comes up empty; remaining MCP lock-contention gaps close;
secret redaction covers memory evolve.
PHP (enums, nullsafe calls, constructor promotion) and Ruby (singleton
methods, scoped classes, block-bearing calls) parsers land — 11 languages.
The TS/JS parser now emits references edges for capitalized JSX elements,
closing the biggest React blind spot (cairn callers UserCard previously
missed ~half of real component usage). A deep parser audit fixes
silent edge-drops in TS/JS variable initializers and Ruby calls.
0.7.0 repositions cairn around three machine-checked promises (every
exact edge resolved; every doc symbol graph-verified by a deterministic
critic; no LLM in the query path) and ships cairn verify, the
recall_memory STALE flag, memory-triggered build hints, and
cairn download-reranker (bge-reranker-base, auto-enabling). 0.7.1
remediates a 10-defect audit — headliners: record_memory persisted
secrets verbatim (now redacted at the shared chokepoint), and
semantic_search's RRF fusion silently never ran (a swallowed
AttributeError).
Focus: no API changes. Two threads of work landed:
cairn update had a class of bugs where derived state under-refreshed and
incoming edges broke silently. Highlights:
-
incremental_updatenow rebuildsdataflow+transitive_edgesafter a change (previously onlycairn builddid → stale impact lookups post-update). - New
resolver.repair_incoming_edgesre-resolves edges from other files that pointed at re-created symbols, and backfillstarget_name(was cleared to NULL on resolved edges). -
--repobuilds take the advisorybuild_lock(concurrent builds raise instead of interleaving writes). - Each file's delete+reinsert is one transaction (rollback on failure).
A 7-agent parallel audit of full src/ vs every doc surfaced 12 high + 23
medium + 34 low discrepancies; all 12 high + 5 medium fixed in this release:
- Broken README install example (
--client claude,cursor→ repeated flags). -
opencodeinstallable but not uninstallable via--client. - Stale install template regenerating wrong ANN / recall_memory / layer claims into every fresh AGENTS.md.
- "wiki generate is critic-gated" overclaim scoped to compass only.
- SCIP
configuration.mdrow: "skipped by tree-sitter" → actual coexistence- then-merge model. - Version drift (README / SECURITY /
architecture.html) refreshed to 0.6.x.
Also folded from [Unreleased] (work that predated the audit): the
vertical-rail flow UI for cairn init / cairn build, hybrid SCIP/tree-sitter
indexing, and the portable .kg database.
Tests: 597 passed, 1 skipped.
Focus: install-agents gets an interactive checkbox picker;
scripts/install.sh no longer silently mis-installs semantic-search deps or
wires up AI-client hooks that fail on every invocation.
See the full 0.6.0 entry in CHANGELOG.md.
-
0.5.x —
MCP tool-count reconciliation, Go parser, PEP 440 version comparison in
cairn upgrade, README rewrite to lead with PyPI install. - 0.4.0 — inaugural documented release (prior history was internal).
Full detail for every version is in CHANGELOG.md.
cairn uses tag-triggered PyPI Trusted Publishing (no API tokens):
- CHANGELOG
[Unreleased]→[X.Y.Z] - YYYY-MM-DD; bumppyproject.toml+src/cairn/__init__.py. - Commit
release: X.Y.Z, merge tomain. -
git tag vX.Y.Z && git push origin vX.Y.Z. -
.github/workflows/release.ymlbuilds wheel + sdist, publishes to PyPI, cuts a GitHub Release.
See docs/release-checklist.md for the pre-release pass each tag runs through.