v0.20.3

v0.20.3

Highlights

Expands platform support to Cursor, Antigravity, and Codex with full MCP config and skill sync. Restructures the public documentation into English-first (docs/en/) and Vietnamese (docs/vi/) mirrors. Fixes MCP text field escaping so multiline content (plans, notes, descriptions) is stored correctly.

---

Added

• Cursor platform support — knowns init and knowns sync now generate .cursor/mcp.json with the Knowns MCP server config; knowns update keeps it in sync after upgrades
• Antigravity platform support — generates .agent/rules/knowns.md guidance file and ~/.gemini/antigravity/mcp_config.json MCP config during init and sync
• Codex platform support — generates .codex/config.toml with [mcp_servers.knowns] section during init and sync
• .agents/skills/ directory — new repo-level skills directory used by OpenCode, Antigravity, and Codex (13 skills: kn-init, kn-plan, kn-implement, kn-commit, kn-research, kn-review, kn-spec, kn-go, kn-verify, kn-doc, kn-extract, kn-template, kn-debug)
• Vietnamese README — full README.vi.md translation alongside the English README
• Bilingual documentation — complete docs/en/ and docs/vi/ doc trees covering getting-started, guides, reference, integrations, and contributing

Improved

• MCP text field escaping — new textArg() / unescapeText() helpers unescape literal \n and \t in MCP arguments, fixing multiline content for task descriptions, plans, notes, doc content, and memory entries
• Semantic search type-aware availability — search engine now checks embedder availability per search type (memory-only searches work even when the main ONNX embedder is not loaded), with nil-guard on semanticSearch and semanticSearchSingleStore
• Init wizard narrow-terminal fallback — automatically falls back to non-interactive defaults when terminal width < 90 columns, with a clear warning message
• Init wizard alt-screen — the interactive setup form now uses bubbletea's alt-screen mode for a cleaner experience
• Skill sync for new platforms — SyncSkillsForPlatforms distinguishes .agents/skills/ (OpenCode, Antigravity, Codex) from legacy .agent/skills/ (agents) with backwards-compatible detection
• knowns sync platform config sync — sync command now regenerates Cursor, Codex, and Antigravity configs alongside existing Claude/Kiro/OpenCode sync
• knowns update MCP config sync — update command syncs Cursor, Codex, and Antigravity MCP configs after binary upgrade
• Windows shell command quoting — hookCommandPath now properly quotes arguments and converts backslashes to forward slashes on Windows for Claude's bash-based command hooks

Documentation

• Restructured docs/ — migrated 14 flat docs into organized docs/en/ and docs/vi/ trees with categories: getting-started, guides, reference, integrations, contributing
• New docs — added compatibility matrix, guidance files reference, model management, sync reference, validate reference, AI agent guide, AI workflow guide, memory system guide, and platform integration mapping
• Updated README — expanded with Before & After comparison, Claude Code Skills workflow section, all skills table, and updated quick reference

Testing

• init_test.go — comprehensive tests for init command including platform config generation, wizard fallback, and narrow-terminal detection
• skill_sync_test.go — tests for .agents/skills/ vs .agent/skills/ directory selection and legacy detection
• runtimeinstall_test.go — tests for shell command quoting and Windows path normalization
• search_test.go — tests for type-aware semantic availability checks

Removed

• internal/cli/guidelines.go — removed standalone guidelines command (functionality merged into sync)
• Root .mcp.json — removed in favor of platform-specific MCP configs

---

Full Changelog: v0.20.2...v0.20.3

v0.20.2

v0.20.2

Highlights

Fixes ONNX Runtime architecture mismatch on Linux, improves knowns update with interactive install method detection, and adds ORT library to CI test environments.

---

Fixed

• ONNX Runtime architecture validation — ResolveORTLibraryPath() now reads the ELF header to verify the shared library matches the host CPU architecture (x86_64 vs aarch64), skipping wrong-arch files instead of letting dlopen fail with a cryptic error
• CI: wrong-arch ORT bundled in Linux x64 package — The build pipeline previously tried Go module test_data first, which only contains arm64 libs, potentially shipping an arm64 .so inside the x64 tarball. Now always downloads from official ONNX Runtime GitHub releases for all platforms
• CI: ELF architecture verification — Tarball verification step now checks e_machine in ELF headers to catch architecture mismatches before publishing
• Self-update missing ORT library — knowns update (script-managed) now copies libonnxruntime.* / onnxruntime.dll from the release tarball alongside the binary, preventing stale or missing native libs after upgrade

Improved

• Interactive install method detection — knowns update now shows a bubbletea confirm prompt with the detected install method, with option to choose a different one from a selectable list (↑/↓ navigation, number keys, Esc/Ctrl+C to cancel)
• Runtime-first detection — Install method detection prioritizes binary path analysis over persisted install.json metadata, correctly handling cases where users switch install methods (e.g. script → Homebrew)
• Cross-platform path detection — Path matching normalizes separators for Windows compatibility, detecting npm/bun/pnpm/yarn/script installs on all platforms
• CI test coverage for semantic search — Both ci.yml and publish.yml now download ONNX Runtime v1.25.0 for unit tests and E2E semantic search tests

---

Full Changelog: v0.20.1...v0.20.2

v0.20.1

v0.20.1

Highlights

Patch release fixing ONNX Runtime library resolution for Homebrew installations and CI bundling improvements.

---

Fixed

• Homebrew ONNX Runtime resolution — ResolveORTLibraryPath() now checks sibling directories (../libexec, ../lib) relative to the binary, fixing semantic search on Homebrew where the dylib is installed in libexec/ rather than next to the binary
• CI ONNX Runtime bundling — Download ONNX Runtime x64 libs from official GitHub releases as fallback when Go module test_data lacks them

Removed

• macOS Intel (darwin/amd64) — Dropped from build matrix, npm packages, tarballs, verification, Homebrew formula, and install script. ONNX Runtime 1.25.0 no longer ships macOS x64 binaries.

---

Breaking Changes

• macOS Intel (x86_64) no longer supported — Only macOS Apple Silicon (arm64) is supported going forward. The install script now exits early on macOS Intel with a clear message.

---

Full Changelog: v0.20.0...v0.20.1

v0.20.0

v0.20.0

Highlights

This release replaces the external sidecar embedding process with a native ONNX runtime, introduces an AI permission guard system, adds MCP audit trail capabilities, and consolidates MCP tools for a cleaner API surface. The CI pipeline is also simplified by removing the now-unnecessary sidecar smoke tests.

---

Added

• AI Permission Guard — New permission system (internal/permissions) with guard, policy, and registry modules for controlling AI tool access
• MCP Audit Trail — Track all MCP tool invocations with audit middleware, storage layer, CLI commands (knowns audit), API routes, and a new Audit UI page
• Structural Knowledge Retrieval — Code graph edge storage and traversal (internal/storage/structural_*) for querying code relationships
• Project Activation Readiness — New internal/readiness module to check project setup completeness
• Status CLI command — knowns status for quick project health overview

Changed

• MCP Tool Consolidation — Refactored all MCP handlers; removed standalone board and working_memory handlers in favor of unified interfaces; added shared handler helpers
• Native ONNX Embedding — Replaced the external knowns-embed sidecar process with native ONNX runtime integration (internal/search/onnx_runtime.go, embedding_native.go), eliminating the need for a separate binary
• Skills Update — Synced skill definitions across all platforms (.agent/, .claude/, .kiro/, internal/instructions/)
• Working Memory Merged — Consolidated internal/workingmemory into the unified memory store
• CI Simplified — Removed sidecar-smoke job (5-platform matrix) and sidecar build steps from CI pipeline
• Install Scripts — Updated for new binary structure
• Publish Workflow — Refactored CI publish pipeline

Removed

• internal/mcp/handlers/board.go — Merged into consolidated handler
• internal/mcp/handlers/working_memory.go — Merged into memory handler
• internal/workingmemory/store.go — Replaced by unified memory store
• internal/search/embedding_sidecar*.go — Replaced by native ONNX embedding
• internal/cli/skill.go — Skill CLI command removed
• cmd/knowns-embed/main_nonwindows.go — No longer needed
• sidecar-smoke CI job — No longer needed with native embedding

Documentation

• Added research docs and specs for: AI permission model, audit trail, structural retrieval, project readiness, MCP tool consolidation
• Updated AI, MCP, skills, and architecture documentation
• Updated README, user guide, commands reference, and templates docs
• Synced agent instruction files (AGENTS, CLAUDE, GEMINI, KNOWNS, OPENCODE)

---

Breaking Changes

• MCP tool names may have changed due to handler consolidation. Clients using board or working_memory tools directly will need to update to the new unified endpoints.
• Sidecar binary no longer required — The knowns-embed binary is no longer needed. Embedding is handled natively via ONNX runtime. Existing KNOWNS_EMBED_BIN environment variable references can be removed.

---

Full Changelog: v0.19.2...v0.20.0

v0.19.2

v0.19.2

0.19.2 is a patch release focused on semantic search stability, especially on Windows, while also improving CI and release reliability.

Highlights

• Improved semantic search setup in non-interactive environments such as CI or terminals without TTY support.
• Added multi-platform smoke tests for knowns-embed, with a strong focus on Windows runtime validation.
• Expanded test coverage for sync, semantic search, and related MCP workflows.

Changed

• Semantic search setup now behaves more reliably when running in non-interactive environments.
• The CI pipeline now builds and validates the sidecar across macOS, Linux, Windows x64, and Windows ARM.
• The build and release flow now includes real runtime checks for the Windows sidecar before publishing artifacts.

Fixed

• Reduced the risk of shipping semantic search artifacts that fail at runtime on Windows.
• Improved early failure detection for semantic search and sync workflows through E2E and smoke tests.
• Increased release stability by validating that the sidecar not only exists in published packages, but also runs successfully.

Testing

• Added CI smoke tests for knowns-embed across multiple platforms.
• Added test coverage for:
• knowns sync --instructions
• knowns sync --skills
• semantic CLI subset
• semantic MCP subset

Notes

• There are no breaking changes in this release.
• This release prioritizes stability and reliability over new feature work.

Full Changelog: v0.19.1...v0.19.2

v0.19.1

v0.19.1 - CI and Semantic Search Stabilization

✨ Added

• Added cross-platform sidecar smoke checks in PR CI for all Bun targets: darwin x64/arm64, linux x64/arm64, and windows x64/arm64
• Added end-to-end CLI coverage for knowns sync --instructions --platform claude and knowns sync --skills
• Added semantic search subsets to PR CI so semantic CLI and MCP search flows are exercised in pull requests

🔄 Changed

• Updated CI runner selection for Darwin x64 sidecar smoke to use the Intel macOS runner label already used by publish workflow
• Adjusted Unix sidecar smoke execution to export bundle-local dynamic library paths before launching the compiled sidecar
• Refined PR CI coverage so sidecar packaging/runtime validation and semantic search validation run as separate targeted checks

🐛 Fixed

• Fixed semantic model download in non-interactive environments by avoiding Bubble Tea setup UI when running without a TTY
• Fixed CI failures where semantic CLI tests fell back to keyword-only mode because model setup could not complete in GitHub Actions
• Fixed sidecar smoke regressions on Unix runners caused by missing runtime loader paths when executing packaged sidecar binaries directly

---

Contributors

@howznguyen

Full Changelog: v0.19.0...v0.19.1

v0.19.0

v0.19.0 - Tree-sitter Sidecar Runtime for Search

✨ Added

• New Bun-based sidecar runtime for symbol extraction, parsing, and embedding support across supported platforms
• Tree-sitter-driven symbol extraction pipeline, candidate discovery helpers, and sidecar server/build assets under sidecar/
• Sidecar runtime plumbing in the CLI, including setup/download flow updates and tunnel/cloudflared helpers for runtime-managed services
• Spec doc for the tree-sitter sidecar design and rollout

🔄 Changed

• Search and indexing flows now use the new sidecar-based embedding/runtime path instead of the previous ONNX implementation
• Runtime queue, MCP server integration, install scripts, and update/browser/runtime commands were updated to support sidecar packaging and execution
• Publish workflow, Makefile, and release packaging now build and ship sidecar bundles alongside the main CLI artifacts

🐛 Fixed

• Improved cross-platform search/runtime consistency by removing the older ONNX/stub split and standardizing parsing and embedding behavior behind the sidecar runtime
• Tightened AST indexing coverage and runtime-related tests around parser candidates, browser/search flows, and sidecar-backed indexing behavior

---

Contributors

@howznguyen

Full Changelog: v0.18.4...v0.19.0

v0.18.4

v0.18.4 - Semantic References & Working Memory

✨ Added

• Semantic reference model and resolution flow for knowledge links such as references, implements, blocked-by, related, depends, and follows
• New reference resolution and rewrite helpers in storage and reference packages, with dedicated tests
• knowns resolve CLI support for resolving semantic references directly
• Working memory store and MCP/server support for session-scoped memory operations
• New semantic reference badge rendering in the editor and richer release/spec docs for the feature set

🔄 Changed

• Search, graph, docs, and MCP flows now surface semantic references more consistently across backend and web UI
• Memory APIs and the Memory page were reworked to separate persistent memory from working memory, with improved create/view/edit flows
• Graph filtering and legends now support semantic relation edge types and clearer impact exploration
• Installer and publish workflow assets were updated to include the new runtime/reference-related behavior
• User and developer docs were refreshed for semantic references, mention playground usage, and related workflows

🐛 Fixed

• Improved document reference resolution and validation behavior so semantic links are interpreted more reliably across storage, routes, and search
• Tightened tests around MCP search, doc storage, graph routes, runtime memory, and reference resolution to reduce regressions in the new reference pipeline

---

Contributors

@howznguyen

Full Changelog: v0.18.3...v0.18.4

v0.18.3

v0.18.3 - Runtime Adapter Install, MCP-First Retrieval & Search Improvements

✨ Added

• Unified runtime adapter install package for global hook/plugin setup across claude-code, codex, kiro, and opencode
• runtime-memory CLI command for direct runtime memory hook invocation
• Kiro native runtime-memory hook (.kiro/hooks/knowns-runtime-memory.kiro.hook)
• Specs: multi-store semantic memory retrieval and unified runtime adapter install
• Design system reference doc for SVG diagrams, Web UI, and knowns.sh visual consistency
• README SVG diagrams: architecture, capabilities, cover, knowledge-graph, mcp-integration, multi-platform, template-pipeline, workflow

🔄 Changed

• All agent skills and compatibility shims now prefer MCP retrieve tool over CLI, with CLI as fallback
• Search engine improvements: chunker source-type awareness, vecstore type filtering, sqlite store optimizations, and sync refinements
• Init flow updated with runtime discovery, adapter install integration, and MCP-first guidance generation
• Docs refreshed: commands, configuration, semantic-search, mcp-integration, user-guide, developer-guide, web-ui

🐛 Fixed

• Search type filtering now applies at the vector store level so --type memory queries are not crowded out by unrelated doc/task chunks

---

Contributors

@howznguyen

Full Changelog: v0.18.2...v0.18.3

v0.18.2

v0.18.2 - Shared Runtime Queue, Script Updates & Stability Fixes

✨ Added

• Shared global runtime queue for background semantic/code indexing work, with project-scoped queues, lease tracking, idle shutdown, and runtime status reporting
• Installer metadata persisted under ~/.knowns/install.json for official shell and PowerShell installs
• Script-managed self-update flow for knowns update, including runtime version awareness and safer runtime restart behavior after upgrades
• MCP and runtime process logs under ~/.knowns/logs, including per-process MCP logs and bounded log rotation

🔄 Changed

• MCP write paths now keep source-of-truth writes synchronous while enqueueing follow-up indexing, watch-triggered work, and reindex tasks to the shared runtime
• knowns watch and related background indexing flows now reuse shared runtime infrastructure instead of spawning redundant heavyweight work
• Shell installer now defaults to ~/.knowns/bin, reducing the need for sudo and avoiding password prompts for script-managed installs on macOS and Linux
• Background indexing now uses queue pacing, debounce windows, duplicate coalescing, and lower ONNX thread defaults to reduce CPU spikes

🐛 Fixed

• Fixed runtime memory injection scoring so prompt hooks only inject memories with actual prompt relevance instead of matching only on runtime/context tokens
• Fixed Windows and race-sensitive test behavior by forcing test commands and MCP e2e flows to run with inline runtime mode instead of leaving shared runtime processes behind
• Fixed MCP/background work stability issues caused by inline indexing pressure, stale runtime reuse, and oversized shared log growth

---

Contributors

@howznguyen

Full Changelog: v0.18.1...v0.18.2