Release Notes

Changelog

Stay up to date with all the latest features, improvements, and bug fixes in Knowns CLI.

npmv0.20.5 GitHub30 releases

v0.20.5Latest

April 30, 2026 View on GitHub

v0.20.5

Highlights

Major code ingest performance boost — batch embedding with length-sorted content and parser pooling cuts ingest time from ~1m27s to ~17s (5× speedup). Adds Java, Rust, and C# language support to the AST indexer. Expands knowns mcp setup to support 10 platforms via a unified registry pattern, including new Cline, Continue, Claude Desktop, and Gemini CLI targets.

Added

• Java, Rust, C# language support — AST indexer now parses .java, .rs, and .cs files via tree-sitter CGO bindings, extracting symbols (classes, structs, enums, traits, impl blocks, constructors) and edges (imports, method ownership)
• Cline platform support — knowns mcp setup cline generates .cline/mcp_settings.json with Knowns MCP server config
• Continue platform support — knowns mcp setup continue generates Continue MCP config
• Claude Desktop platform support — knowns mcp setup claude-desktop generates global Claude Desktop MCP config
• Gemini CLI platform support — knowns mcp setup gemini generates global Gemini CLI MCP config
• Unified MCP platform registry — all 10 platforms (Claude Code, Kiro, OpenCode, Cursor, Codex, Cline, Continue, Claude Desktop, Antigravity, Gemini CLI) managed through a single mcpPlatform registry with consistent setup interface

Improved

• 5× code ingest speedup — batch embedding with length-sorted content minimizes padding waste in ONNX inference; adaptive batch sizes (64 for short content, 32 for long) balance throughput and memory
• Parser instance pooling — tree-sitter parsers are reused via per-extension pools, eliminating alloc/dealloc overhead per file
• Compact embedding content — classes embed as signature + member signature list instead of full source code; functions embed as signature + edge summary. Content truncated to ~2000 chars (model's effective window) to save tokenizer CPU
• Audit page expandable events — audit event rows now expand to show argument summaries and project root details
• Code graph page improvements — layout and interaction refinements
• Memory page resilience — removed dependency on /api/working-memories route that caused silent page failure; page now loads reliably with persistent memories only

Fixed

• Memory page silent failure — MemoryPage crashed silently when Promise.all included a call to the non-existent /api/working-memories endpoint; removed the broken call
• Watch command stale ingest reference — corrected knowns ingest → knowns code ingest in the semantic search warning message
• E2E test flaky port allocation — findPort() generated random port numbers without checking availability, causing server startup timeouts on CI. Now uses OS-assigned port via net.createServer() bound to port 0
• E2E server startup diagnostics — increased waitForServer timeout from 15s to 30s and added stderr capture for better failure messages

Dependencies

• Added tree-sitter-java, tree-sitter-rust, tree-sitter-c-sharp Go bindings

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.20.4...v0.20.5

v0.20.4

April 28, 2026 View on GitHub

v0.20.4

Highlights

Fixes a critical MCP server crash caused by the ONNX Runtime native library accessing freed memory. The crash occurred when Embedder.Close() destroyed the process-global ONNX environment while background indexing goroutines were still active or about to reinitialize it.

Fixed

• MCP server crash — ONNX Runtime use-after-free — ORTRuntime.Close() called ort.DestroyEnvironment() on every Embedder.Close(), tearing down the process-global ONNX C++ environment while other goroutines could still be using it. The fault address (0x614d3a3a786e6e6f → onnx::Ma) confirmed the crash was inside native ONNX code accessing freed memory. Close() now only releases the model session; the environment lives for the process lifetime.
• ONNX environment initialization race condition — ensureORTEnvironment() used a simple IsInitialized() check with no synchronization, allowing two goroutines to race into InitializeEnvironment() simultaneously. Now guarded by sync.Once.

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.20.3...v0.20.4

v0.20.3

April 24, 2026 View on GitHub

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: https://github.com/knowns-dev/knowns/compare/v0.20.2...v0.20.3

v0.20.2

April 24, 2026 View on GitHub

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: https://github.com/knowns-dev/knowns/compare/v0.20.1...v0.20.2

v0.20.1

April 23, 2026 View on GitHub

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: https://github.com/knowns-dev/knowns/compare/v0.20.0...v0.20.1

v0.20.0

April 23, 2026 View on GitHub

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: https://github.com/knowns-dev/knowns/compare/v0.19.2...v0.20.0

v0.19.2

April 22, 2026 View on GitHub

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: https://github.com/knowns-dev/knowns/compare/v0.19.1...v0.19.2

v0.19.1

April 20, 2026 View on GitHub

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](https://github.com/howznguyen)

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.19.0...v0.19.1

v0.19.0

April 20, 2026 View on GitHub

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](https://github.com/howznguyen)

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.18.4...v0.19.0

v0.18.4

April 17, 2026 View on GitHub

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](https://github.com/howznguyen)

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.18.3...v0.18.4

v0.18.3

April 12, 2026 View on GitHub

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](https://github.com/howznguyen)

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.18.2...v0.18.3

v0.18.2

April 11, 2026 View on GitHub

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](https://github.com/howznguyen)

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.18.1...v0.18.2

v0.18.1

April 11, 2026 View on GitHub

v0.18.1 - Release Docs, MCP Schema & Update Guidance

✨ Added

• Public docs for the v0.18.0 feature set, including workspace-aware browser mode, code intelligence commands, code graph usage, and chat/runtime UX updates
• Installer README examples for pinning a specific version with KNOWNS_VERSION on both shell and PowerShell installers

🔄 Changed

• README and command guides now describe the shipped knowns code ingest, knowns code watch, knowns code search, knowns code deps, and knowns code symbols workflows
• Browser and web UI docs now cover workspace switching, project scanning, code watcher mode, and richer graph/chat capabilities

🐛 Fixed

• Fixed MCP tool schema for knowns_retrieve so sourceTypes declares array item types and no longer triggers array schema missing items
• Fixed Homebrew upgrade guidance to use brew upgrade knowns-dev/tap/knowns consistently in the CLI notifier and release/install messaging

Contributors

@howznguyen](https://github.com/howznguyen)

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.18.0...v0.18.1

v0.18.0

April 10, 2026 View on GitHub

v0.18.0 - Workspace Switching, Code Intelligence & Chat UX

✨ Added

• AST-based code intelligence with symbol indexing, relationship edges, neighbor discovery, and dedicated tests
• New code-focused CLI and MCP capabilities for code search, code graph exploration, ingest, and file watching/sync flows
• Dedicated Code Graph experience in the web UI with new graph toolbar, legend, styling, and detail panel improvements
• Welcome page and chat timeline dialog to improve session onboarding and chat history navigation
• Workspace picker and server-side workspace switching improvements, including broader browser/server test coverage
• Search benchmarking utilities and new research/spec docs for retrieval, graph UX, and chat runtime upgrades

🔄 Changed

• Upgraded chat runtime and message rendering to better support tool calls, shell output, sub-agents, and richer thread interactions
• Expanded search engine and server routes to support code-aware retrieval alongside existing knowledge/doc search flows
• Updated browser/server integration, route wiring, and configuration plumbing to support workspace-aware behavior end to end
• Refined agent skill instructions and internal guidance for planning, implementation, review, research, and debugging workflows

🐛 Fixed

• OpenCode client/runtime handling is more robust, with added tests around client behavior and browser command flows
• Graph, search, validation, storage, and API route handling received targeted fixes alongside the new workspace/code features
• Publish workflow and package metadata were adjusted to keep release/build behavior aligned with the new runtime changes

Contributors

@howznguyen](https://github.com/howznguyen)

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.17.1...v0.18.0

v0.17.1

April 2, 2026 View on GitHub

v0.17.1 - MCP Fixes & Working Memory Persistence

🐛 Fixed

• create_task MCP handler now properly saves plan and notes fields (were being silently ignored)
• update_doc MCP handler no longer clears content when sending empty string content: ""
• Working memory now persists to .knowns/.working-memory/ directory instead of RAM-only, surviving restarts and compacts
• clear_working_memory properly removes working memory files from disk

Contributors

@howznguyen](https://github.com/howznguyen)

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.17.0...v0.17.1

v0.17.0

April 2, 2026 View on GitHub

v0.17.0 - Memory System & Knowledge Graph

✨ Highlights

• 🧠 3-Layer Memory System — Working, project, and global memory layers for agents. Store patterns, decisions, and conventions that persist across sessions via CLI (knowns memory) and full MCP tool coverage (add_memory, list_memories, search_memories, promote_memory, add_working_memory).
• 🕸️ Knowledge Graph UI — New Graph page visualizes relationships between tasks, docs, and memories as an interactive network. Click any node to open a detail panel with full context.
• 📈 Semantic Search Quality — Model-specific embedding prefixes (EmbedQuery/EmbedDocument) for bge, nomic, and e5; H1 content loss fixed; tokenizer-based chunk splitting; ChunkVersion auto-reindex on version mismatch.
• 🔄 knowns update Command — New CLI command to check for and install the latest version of Knowns.
• 🔌 Custom Provider UI — Add custom OpenCode-compatible providers (base URL, models, headers, API key) directly from the provider connect dialog.

🚀 Added

• knowns memory CLI command — list, view, add, update, delete, and search memory entries across layers
• add_memory / get_memory / update_memory / delete_memory / list_memories / search_memories MCP tools (project + global layers)
• promote_memory / demote_memory MCP tools for cross-layer promotion (project → global)
• add_working_memory / get_working_memory / list_working_memories / delete_working_memory / clear_working_memory MCP tools (session-scoped, in-memory)
• MemoryEntry model with id, title, layer, category, tags, content, metadata, createdAt, updatedAt
• MemoryStore file-backed storage under .knowns/memory/ with semantic search indexing
• GET /api/memories, POST /api/memories, PATCH /api/memories/:id, DELETE /api/memories/:id REST endpoints
• GET /api/graph endpoint — returns nodes and edges for tasks, docs, and memories with relationship inference
• Graph page (/graph) with force-directed network visualization and node type filtering
• Graph detail panel — click any node to see title, type, tags, excerpt, and outbound links
• Memory page (/memory) — list and browse all memory entries by layer and category
• knowns update CLI command — checks GitHub releases and installs the latest binary
• OpenCode auto-detection during knowns init wizard — skips download if already installed
• Custom provider step in ProviderConnectDialog — provider ID, display name, base URL, models, optional headers and API key
• Sidebar navigation entries for Graph and Memory pages
• kn-extract skill: new Step 5 saves memory entry alongside extracted doc
• kn-init skill: Step 3.6 loads project memory at session start
• kn-research skill: Step 2 searches project memory before completed tasks

📝 Changed

• knowns search — improved result ranking with model-aware embedding prefixes
• Chunker now uses tokenizer-based token counting with configurable overlap; splits oversized task chunks
• ChunkVersion bumped — mismatched indexes are automatically wiped and reindexed on next sync
• KNOWNS.md / compatibility shims — added Memory Usage section with usage guidelines for agents
• Skills (kn-extract, kn-init, kn-research) updated to include memory steps in their workflows
• knowns sync — content-based out-of-sync detection replaces .version file mechanism
• MDRender components (CopyablePre, CopyableTable, StableHeading) moved to module scope to fix React reconciliation key warnings
• .air.toml dev server switched from pre-built binary to go run ./cmd/knowns/main.go

🐛 Fixed

• H1 heading content captured correctly in chunker (was being dropped before the first H2)
• Code block language detection in chunker prevented false heading matches inside fenced blocks
• execLookPath in mcpCommand() now injectable — CI test failures caused by knowns not being in PATH resolved
• Chat scroll uses useLayoutEffect for instant initial positioning (no flash of bottom-scrolled content)
• Mention badge re-rendering stabilized with stable useMemo refs
• sync.go import sync no longer races on concurrent file writes

Contributors

@howznguyen](https://github.com/howznguyen)

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.16.3...v0.17.0

v0.16.3

March 28, 2026 View on GitHub

v0.16.3 - Mermaid Viewer & Import Sync

✨ Highlights

• 🔍 Interactive Mermaid Diagrams — Drag to pan, Ctrl+scroll to zoom, auto-fit to container, and theme-aware colors for light/dark mode.
• 📦 Git Import Auto-Sync — Git imports now clone and sync immediately on add, with a spinner UI and private repo token support.
• 🎨 Brand Progress Bars — All CLI progress bars use the Knowns navy blue (#1e3a5f) instead of the default gradient.
• ⏱️ Time Tracking Fix — Stopping a timer now correctly updates the task's timeSpent field.

🚀 Added

• Mermaid drag-to-pan with grab/grabbing cursor feedback
• Mermaid Ctrl+Scroll zoom centered on cursor position with smooth animation
• Mermaid auto-fit on render — large diagrams scale down, small ones cap at 150%
• Mermaid dynamic container aspect ratio (4:3 to 21:9) based on SVG shape
• Mermaid zoom percentage indicator in bottom-right controls
• KnownsBrand constant (#1e3a5f) in styles.go for centralized brand color
• Git import auto-sync on knowns import add with bubbletea spinner UI
• Git token injection for private HTTPS clone URLs
• importedAt and ref fields in import metadata
• Dry-run preview → "Import Now" flow in ConfigPage add import modal

📝 Changed

• Mermaid controls simplified — removed D-pad buttons, kept zoom +/- and reset (fit-to-view)
• Mermaid hardcoded dark colors replaced with theme tokens (bg-muted, text-muted-foreground, border-border)
• All 4 CLI progress bars (model.go, download_setup.go, search.go) switched from WithDefaultBlend() to WithColors(lipgloss.Color(KnownsBrand))
• CopyablePre now skips wrapping mermaid code blocks to avoid duplicate copy button
• Import metadata format aligned between CLI and server (_import.json)
• ImportEntry struct extended with Ref and ImportedAt fields

🐛 Fixed

• Duplicate copy button on mermaid diagrams — CopyablePre wrapper now detects language-mermaid and yields
• Mermaid Ctrl+scroll zoom not working in fullscreen — wheel listener now re-attaches on isFullscreen toggle
• Task timeSpent not updating when stopping timer via API — time.go now writes accumulated duration back to task

Contributors

@howznguyen](https://github.com/howznguyen)

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.16.2...v0.16.3

v0.16.2

March 28, 2026 View on GitHub

v0.16.2 - Custom Providers & Render Stability

✨ Highlights

• 🔌 Custom Provider UI — Add any OpenAI-compatible endpoint directly from the Provider Connect dialog.
• ⚡ Stable Markdown Rendering — Fixed React error #310 and eliminated mention badge flickering on re-render.
• 📜 Chat Scroll Fix — Messages now appear at the correct position instantly instead of jumping.
• 🧹 No More .version Files — Replaced auto-sync mechanism with content-based knowns sync warning.

🚀 Added

• Custom provider UI in ProviderConnectDialog — add any OpenAI-compatible endpoint with provider ID, display name, base URL, models, optional headers, and optional API key
• patchConfig() API method to call PATCH /config on OpenCode server
• addCustomProvider() action in OpenCodeContext (patchConfig → setAuth → globalDispose → refreshAll)
• SkillsOutOfSync() content-based check — compares embedded skills vs on-disk copies without version files
• CLI warning ⚠ Skills are out of sync. Run 'knowns sync' to update. when skills are stale after upgrade

📝 Changed

• Extracted CopyablePre, CopyableTable, StableHeading, MermaidLoading into mdComponents.tsx for cleaner separation
• MDRender useMemo deps reduced to [] — all callbacks accessed via stable refs, components object created once
• Chat scroll switched from useEffect + smooth scroll to useLayoutEffect + instant scroll for new messages
• Removed AutoSyncOnUpdate config field and init wizard step
• Removed .version file generation from skill sync
• Added **/.version to .gitignore

🐛 Fixed

• React error #310 — hooks inside useMemo (pre/table components) lost identity on dep change, causing "Rendered more hooks than during the previous render"
• Mention badges (task/doc) flickering and re-fetching on every render due to unstable components object identity in MDRender
• Chat messages appearing above the last message then jumping down — scroll now fires before paint via useLayoutEffect

Contributors

@howznguyen](https://github.com/howznguyen)

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.16.1...v0.16.2

v0.16.1

March 27, 2026 View on GitHub

v0.16.1 - Enhanced Skills & Developer Experience

✨ Highlights

• 🤖 3 New Skills — kn-go (full pipeline), kn-review (code review), kn-debug (structured debugging) for a more complete AI workflow.
• 🔍 Socratic Exploring — kn-spec now asks one question at a time to lock decisions before writing specs.
• 📊 Context Usage Indicator — Arc indicator in Chat UI showing real-time context window usage with heatmap breakdown.
• 🔄 Smart Sync — knowns sync reads config.json and sets up everything locally (skills, instructions, model, search index).
• 🧠 MCP Auto-Detect — MCP server automatically finds the project from cwd, --project flag, or KNOWNS_PROJECT env.

🚀 Added

• kn-go skill — full pipeline execution from approved spec (generate tasks → plan → implement → verify → commit) with no review gates between steps
• kn-review skill — multi-perspective code review (quality, architecture, security, completeness) with P1/P2/P3 severity triage
• kn-debug skill — structured debugging: triage → check known patterns → reproduce → root cause → fix → capture learning
• kn-spec Phase 0 Socratic exploring — scope assessment, domain classification, gray area identification, one-question-at-a-time dialog, decision locking with stable IDs
• kn-extract compounding — captures decisions and failures alongside patterns, promotes critical learnings, --consolidate mode for reviewing all learnings
• kn-plan pre-execution validation — AC coverage check, scope sizing, dependency check, risk assessment before approval
• kn-init critical learnings — loads learnings/critical-patterns at session start for institutional knowledge
• Context usage indicator in Chat UI — arc indicator with percentage, hover popover with heatmap grid and token breakdown
• knowns sync command — applies config.json after cloning (skills + instructions + git integration + model download + reindex)
• knowns sync --model flag to download embedding model only
• MCP server auto-detects project from --project flag, KNOWNS_PROJECT env var, or cwd walk-up
• MCP --project flag for explicit project path
• Auto-setup warning when embedding model is missing (suggests knowns sync)
• knowns init --force pre-populates all wizard fields from existing config.json (name, git mode, platforms, semantic model)

📝 Changed

• Init wizard splits prompts into sequential groups (one at a time instead of combined)
• Git-ignored mode now whitelists config.json for clone+sync workflow
• Git tracking mode select pre-populates from existing config on re-init
• Semantic search and model selection pre-populate from existing config on re-init
• set_project MCP tool description updated (only needed for runtime switching)
• All MCP error and success messages centralized in handlers/messages.go
• Skills table updated from 10 to 13 in docs

🐛 Fixed

• MCP create_task and update_task now call SaveVersion for version tracking
• SSE multiplexing — OpenCode SSE events merged into Knowns SSE stream (1 connection per tab)
• Auto-inject directory param in session list proxy
• Auto-reload on stale chunk imports (lazy retry for code-split bundles)
• Vietnamese text in skills replaced with English
• Removed unused splitView prop from VersionDiffViewer

Contributors

@howznguyen](https://github.com/howznguyen)

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.16.0...v0.16.1

v0.16.0

March 24, 2026 View on GitHub

v0.16.0 - Hub Mode & Multi-Project Support

✨ Highlights

• 🏠 Hub Mode — Run knowns browser from anywhere, no repo needed. The server becomes a multi-project hub.
• 📂 Workspace Picker — Browse, switch, add, and scan projects from the UI without restarting.
• 🗂️ Project Registry — Global registry tracks all your Knowns projects with auto-discovery.
• 🔄 Runtime Switching — Switch projects on the fly. No restart needed.
• 🤖 Shared OpenCode Daemon — Single shared process with auto health checks and crash recovery.

🚀 Added

• Launch knowns browser outside any repo — opens workspace picker to choose a project
• --project <path> flag to open a specific project directly
• --scan <dirs> flag to discover projects from directories
• Workspace Picker dialog — list, switch, add, scan, and remove projects from the UI
• Sidebar switcher button for quick workspace switching
• Global project registry with auto-discovery and last-used tracking
• Auto-registers current project on startup
• Workspace REST API — list, switch, scan, remove projects
• Live data reload via SSE when switching workspaces
• Shared OpenCode daemon with PID management, health checks, and auto-restart
• Graceful remote shutdown via API

📝 Changed

• Server binds port before writing port file (eliminates race condition)
• Server can start without a project (picker mode)
• OpenCode now runs as a single shared daemon instead of per-server process
• Server restart command now works reliably

🐛 Fixed

• Port file written before port was actually available
• Server errors silently swallowed on startup
• Stale port file left behind after shutdown
• Server restart command was broken (wrong HTTP method)

Contributors

@howznguyen](https://github.com/howznguyen)

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.15.3...v0.16.0

v0.15.3

March 20, 2026 View on GitHub

v0.15.3 - Compact Sessions & Hosted Installers

✨ Highlights

• 📦 /compact Slash Command - Summarize the current chat session into a compact context directly from the Chat UI
• 🌐 Hosted Installers - New install and uninstall entrypoints via knowns.sh
• 📦 Smarter npm Binary Install - knowns now auto-recovers platform binaries during install with npm and GitHub release fallbacks

🚀 Added

Chat UI

• Added local /compact slash command to the Chat input command menu
• Added OpenCode session summarize API support via POST /session/{id}/summarize
• Added model-aware summarize requests using the active session model or effective default model

Install & Uninstall

• Added install/uninstall.sh for macOS/Linux uninstall flow
• Added install/uninstall.ps1 for Windows uninstall flow
• Added hosted installer/uninstaller docs using:
  • https://knowns.sh/script/install
  • https://knowns.sh/script/install.ps1
  • https://knowns.sh/script/uninstall
  • https://knowns.sh/script/uninstall.ps1

npm Distribution

• Added npm/knowns/install.js postinstall binary bootstrapper
• Added fallback logic to install platform binaries from npm first, then GitHub Releases if needed
• Added package homepage metadata across npm packages

📝 Changed

Release Workflow

• Updated publish workflow to upload install and uninstall scripts as release assets
• Added release metadata tracing and built artifact checks in GitHub Actions
• Added verification that the expected release version is present in the built UI artifact

Documentation

• Updated README.md install instructions to use hosted knowns.sh endpoints
• Updated docs/user-guide.md install instructions to use hosted knowns.sh endpoints
• Added uninstall instructions to both main docs

Chat Command Handling

• /compact is now available even when it does not come from the remote OpenCode command registry
• Chat session summarize flow now uses streaming/watchdog handling like other async session actions
• Stop-session handling now uses the OpenCode abort endpoint and restores UI state more safely on failure

🐛 Fixed

Chat Input

• Fixed slash command selection so pressing Enter while the command menu is open autocompletes the selected command instead of submitting partial input like /com

npm CLI

• Improved missing-binary error output with reinstall hints for the expected platform package
• Improved packaged binary installation resilience for platform-specific npm installs

🔧 Technical

UI / OpenCode

• New OpenCodeSummarizeSessionRequest request type in ui/src/api/client.ts
• New opencodeApi.summarizeSession() client method
• Updated ui/src/pages/chat/useChatPage.ts to route /compact through summarize flow
• Updated ui/src/data/skills.ts to merge local slash items with remote command items

Packaging

• npm/knowns/package.json now runs a postinstall script
• All platform packages now include homepage: https://knowns.sh
• Release assets now include install and uninstall scripts alongside archives and checksums

Contributors

@howznguyen](https://github.com/howznguyen)

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.15.2...v0.15.3

v0.15.2

March 19, 2026 View on GitHub

Changes

• fix(npm): restore executable packaged binaries

Contributors

@howznguyen](https://github.com/howznguyen)

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.15.1...v0.15.2

v0.15.1

March 19, 2026 View on GitHub

Known issue: v0.15.1 is broken and may not run after npm/bun install. Please use v0.15.2 or later.

v0.15.0

March 19, 2026 View on GitHub

v0.15.0 - Go Rewrite & Cross-Platform CI

✨ Highlights

• ⚙️ Go Rewrite - Rebuilt Knowns from TypeScript to a Go-native CLI, server, MCP, and packaging flow
• 🧪 Stronger CI - Native test coverage on Ubuntu and Windows, plus Playwright UI E2E in CI
• 📦 Better Packaging - Cross-platform build and npm packaging flow updated for the Go release model

🚀 Added

Go Runtime

• New Go-native knowns CLI entrypoint
• Go-based server implementation for browser/UI workflows
• Go-based MCP implementation and supporting handlers
• New Go-first project structure replacing the previous TypeScript runtime layout

CI & Verification

• Native go test coverage on both ubuntu-latest and windows-latest
• UI Playwright E2E execution in CI
• Automatic browser installation for Playwright in CI
• Cross-platform build verification for Linux and Windows targets

npm Packaging

• Main npm launcher script for the knowns package
• Updated npm wrapper flow to resolve and execute platform-specific binaries

📝 Changed

Architecture

• Migrated the repository from TypeScript to Go as the primary implementation language
• Reorganized runtime, build, packaging, and workflow structure around the Go codebase
• Updated embedded UI handling to work with the new Go binary layout

Build & CI

• CI now builds the UI before Go validation so embedded assets exist during vet/test
• CI now builds the binary before E2E suites that expect bin/knowns
• Windows CI build steps now use platform-appropriate shell commands
• Non-interactive init flow now avoids TTY-dependent semantic setup in CI/E2E contexts

UI Tooling

• Standardized UI workflow on Bun in CI jobs
• Updated Playwright E2E helpers to use non-interactive init and stable binary resolution

🐛 Fixed

• Fixed go vet failures caused by missing embedded UI assets in CI
• Fixed Linux and Windows cross-build failures caused by CGO-only semantic embedding paths
• Fixed Windows-specific CI shell errors in binary build steps
• Fixed E2E failures caused by missing bin/knowns on fresh runners
• Fixed Playwright E2E setup failures caused by relative TEST_BINARY path resolution
• Fixed repository ignore rules that prevented cmd/knowns from being tracked
• Fixed npm publish packaging by tracking the main launcher script used by npm/knowns

📚 Documentation

• Updated specs and docs to reflect the Go-first repository layout
• Refreshed workflow and agent/skill assets to match the new architecture
• Synced repository guidance with the rewritten runtime and packaging flow

🔧 Technical

• Split semantic embedding into build-specific implementations:
  • CGO/ONNX-enabled runtime path
  • non-CGO stub path for portable cross-builds
• Split terminal-specific stdin draining into Unix and Windows implementations
• Added Windows-aware binary path handling in Go test helpers
• Added npm launcher resolution for:
  • npm/pnpm layouts
  • hoisted installs
  • platform package resolution

Contributors

@howznguyen](https://github.com/howznguyen)

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.12.4...v0.15.0

v0.12.4

March 3, 2026 View on GitHub

v0.12.4 - Error Handling & Stability Improvements

✨ Highlights

• 🛡️ Error Boundary - Catch rendering errors to prevent full app crashes
• 🔄 Retry UI - Graceful error recovery with retry button in DocsPage
• 📝 Defensive Parsing - Skip corrupted docs instead of crashing

🚀 Added

Error Handling

• New ErrorBoundary component to catch React rendering errors
• Error state and retry UI in DocsPage when docs fail to load
• Fallback UI with "Try Again" button and error message display

🐛 Fixed

Stability

• App crashes from rendering errors - ErrorBoundary prevents full app crash
• Corrupted doc files crash - Now skips invalid .md files with try-catch
• Missing doc metadata - Ensures all docs have required defaults (title, createdAt, updatedAt)
• DocsPage load failures - Shows error state with retry instead of silent failure

🔧 Technical

Error Boundary Component

• React class component with getDerivedStateFromError and componentDidCatch
• Supports custom fallback UI via props
• Logs errors to console for debugging
• Reset error state with retry button

Doc Parsing Safety

• Wrapped doc parsing in try-catch blocks
• Filters out null results from failed parsing
• Prevents server route crashes on invalid markdown files
• Default metadata injection for missing fields

App Integration

• ErrorBoundary wraps all page content in App.tsx
• Page errors are isolated and don't affect sidebar/header
• Users can continue using the app even if one page fails

Files Changed

src/ui/components/atoms/ErrorBoundary.tsx - New component (61 lines)
src/ui/components/atoms/index.ts          - Export ErrorBoundary
src/ui/App.tsx                            - Wrap pages in ErrorBoundary
src/ui/pages/DocsPage.tsx                 - Error state + retry UI
src/server/routes/docs.ts                 - Defensive parsing with try-catch

Contributors

@howznguyen](https://github.com/howznguyen)

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.12.3...v0.12.4

v0.12.3

February 26, 2026 View on GitHub

v0.12.3 - Mobile Responsive UI & UX Enhancements

✨ Highlights

• 📱 Mobile Responsive - Optimized padding, spacing, and layouts for mobile devices
• 🚀 Performance - Lazy load Mermaid and page components (bundle reduced ~680KB)
• 🎨 UX Improvements - Breadcrumb navigation, scroll memory, copy table as markdown

🚀 Added

Mobile Support

• Mobile drawer for DocsPage, TemplatesPage, ImportsPage
• Mobile warning banner for Kanban (drag & drop not optimal on touch)
• Responsive padding throughout: p-3 sm:p-6
• Task modals use sheet-only mode on mobile (no center dialog)
• Hide maximize button on mobile (not applicable)

UX Features

• Copy table as markdown button (hover on tables)
• Breadcrumb navigation for DocsPage
• Scroll position memory when navigating between docs
• Keyboard shortcut Ctrl+B to toggle sidebar

Performance

• Lazy load MermaidBlock with React.lazy/Suspense
• Lazy load all page components in App.tsx
• Bundle size reduced from ~2,682KB to ~2,003KB

📝 Changed

Mermaid Diagrams

• GitHub-style zoom/pan controls
• Fullscreen mode support
• Improved rendering with better styling

Table Styling

• GitHub-like appearance with zebra striping
• Hover effects on rows
• Better border styling for headers vs cells

Typography

• Improved heading sizes and spacing
• Better list styling
• Custom checkbox styling for task lists

🐛 Fixed

• Task links in DocsPage - Now opens global modal instead of navigating to Kanban
• SSE reconnection - Improved handling for connection drops
• Safari markdown editor - Fixed issues with react-markdown-editor-lite

🔧 Technical

Responsive Patterns

• Consistent mobile padding: p-3 (mobile) / p-6 (desktop)
• Responsive gaps: gap-2 sm:gap-4, gap-3 sm:gap-6
• Responsive text: text-xl sm:text-2xl
• Truncate with min-w-0 for flex overflow handling

Components Updated

• TaskDetailSheet - mobile sheet mode, reduced padding
• TaskCreateForm - mobile sheet mode, compact layout
• TaskDataTable - responsive toolbar, stacked on mobile
• TaskGroupedView - responsive filters
• Board - responsive column controls

Files Changed

src/ui/App.tsx                    - Lazy load pages
src/ui/components/editor/MDRender.tsx - Table copy, lazy Mermaid
src/ui/components/editor/MermaidBlock.tsx - Zoom/pan/fullscreen
src/ui/components/organisms/TaskDetailSheet.tsx - Mobile sheet
src/ui/components/organisms/TaskCreateForm.tsx - Mobile sheet
src/ui/pages/DocsPage.tsx         - Breadcrumb, scroll memory, drawer
src/ui/pages/KanbanPage.tsx       - Mobile warning banner
src/ui/pages/TasksPage.tsx        - Responsive layout
src/ui/pages/TemplatesPage.tsx    - Mobile drawer
src/ui/pages/ImportsPage.tsx      - Mobile drawer
src/ui/index.css                  - Table styling, typography

Contributors

@howznguyen](https://github.com/howznguyen)

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.12.2...v0.12.3

v0.12.2

February 25, 2026 View on GitHub

v0.12.2 - Browser Improvements & Validate E2E Tests

✨ Highlights

• 🌐 Smart Browser Detection - Prevents duplicate server instances when running knowns browser
• ✅ Validate E2E Tests - Comprehensive validation tests with scope filtering
• 🎨 Dynamic Status Options - UI now uses custom statuses from project config

🚀 Added

Validation Tests

• Added 29 vitest integration tests in validate.test.ts
• Expanded MCP e2e tests with 6 validation workflow tests
• Expanded CLI e2e tests with 6 validation workflow tests
• Tests cover: scope filtering, SDD mode, strict mode

Browser Command Improvements

• Server detection before starting new instance
• Auto-switch to next available port if occupied
• Only opens browser on successful port (not fallback)

📝 Changed

UI Enhancements

• TaskDataTable now uses dynamic status options from config.statuses
• StatusBadge supports custom statuses (e.g., "urgent")
• DocsPage and TaskGroupedView UI improvements

Skills System

• Updated /kn-spec with validation step
• Updated /kn-template with validation step
• Updated /kn-verify with improved coverage reporting

Publish Workflow

• Changed install instructions from Homebrew to npm/bun

🐛 Fixed

• Browser duplicate ports - Fixed knowns browser opening both 6420 and 6421
• Server port detection - Now properly checks if Knowns server is already running
• E2E test order - Fixed git init must run before knowns init

🔧 Technical

Validate Command

• Enhanced MCP handler with better scope filtering
• Improved stats reporting (tasks, docs, templates count)
• SDD validation with coverage percentage

Server

• Added isKnownsServerRunning() health check function
• Browser only opens on originally requested port
• Port fallback message shown when switching ports

Contributors

@howznguyen](https://github.com/howznguyen)

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.12.1...v0.12.2

v0.12.1

February 24, 2026 View on GitHub

v0.12.1 - E2E Tests & Node 20+ Requirement

✨ Highlights

• 🧪 E2E Test Suite - Comprehensive CLI and MCP workflow tests
• 📦 pnpm Support - Added pnpm as package manager option
• ⚡ Node 20+ - Dropped Node 18, now requires Node 20+

🚀 Added

E2E Tests

• scripts/test-cli.mjs - CLI basic tests
• scripts/test-cli-e2e.mjs - CLI workflow tests
• scripts/test-mcp.mjs - MCP basic tests
• scripts/test-mcp-e2e.mjs - MCP workflow tests with semantic search
• New npm scripts: test:cli, test:cli:e2e, test:mcp, test:mcp:e2e

Documentation

• Added auth-patterns.md pattern documentation

📝 Changed

Node.js Requirements

• Breaking: Minimum Node.js version raised from 18 to 20
• Vite 7 and @vitest](https://github.com/vitest)/coverage-v8 require Node 20+

Package Manager

• Added pnpm-lock.yaml for pnpm support
• CI now uses pnpm for faster installs

Skills System

• Removed .agent/skills/ synced files
• Skills now sourced directly from src/instructions/skills/

🐛 Fixed

• Fixed semantic search not working in MCP e2e tests
• Fixed CI coverage failing on Node 18 (now skipped)

🔧 Technical

• Updated CI matrix: Node 20, 22, 24 (removed 18)
• MCP e2e tests now use CLI to setup semantic search properly
• Removed obsolete engine.test.ts and store.test.ts

Contributors

@howznguyen](https://github.com/howznguyen)

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.12.0...v0.12.1

v0.12.0

February 24, 2026 View on GitHub

v0.12.0 - Semantic Search & SDD Enhancements

✨ Highlights

• 🔍 Semantic Search - AI-powered search using vector embeddings for better relevance
• 🔗 Fulfills Field - Link tasks to spec acceptance criteria for SDD workflow
• 📊 Similarity Scores - See match confidence (%) in search results

🚀 Added

Semantic Search

• New knowns search with hybrid mode (semantic + keyword + fuzzy matching)
• knowns modelcommand for embedding model management
  • model list - List available models (6 curated models)
  • model download <id> - Download embedding model
  • model set <id> - Set model for project
  • model status - Show current model status
• --reindex flag to rebuild search index
• --status-check flag to check semantic search status
• --keyword flag for keyword-only search fallback
• Similarity scores shown in results: (97%) for high relevance
• Matched by: semantic, fuzzy, keyword to explain why results matched

SDD (Spec-Driven Development)

• fulfills field on tasks to link to spec ACs
• Auto-check spec ACs when task AC is completed
• Pattern documentation for fulfills mapping

New Commands

• knowns guidelines- Display Knowns usage guidelines for AI agents
  • --plain for AI-readable output
  • --mode cli|mcp|unified for different guideline modes
  • --search <query> to search within guidelines
  • --compact for condensed rules (what goes in CLAUDE.md)

Auto-Sync & Version Tracking

• .version file in skill directories for tracking sync state
• Auto-sync skills when CLI version changes
• Progress bar utility for visual feedback during operations

📝 Changed

Search Output

• Plain output now shows structured format for AI:

#taskId [status] [priority] (97%)
    Content snippet...
    Matched by: semantic, fuzzy, keyword

• Doc results show section and match reason

Documentation

• Converted ASCII diagrams to Mermaid in all docs
• Translated all Vietnamese text to English
• Removed non-existent CLI commands from docs
• Added 9 guide docs in .knowns/docs/guides/
• Updated README.md structure

MCP

• Search MCP tool now includes score field in results
• Added mode parameter: hybrid, semantic, keyword

🐛 Fixed

• Fixed config test using invalid key testKey
• Removed fake CLI commands: knowns ai detect, knowns mcp status, knowns skill export

📚 New Documentation

• docs/semantic-search.md - Semantic search guide
• docs/skills.md - Skills system guide
• docs/auto-sync.md - Auto-sync version tracking
• docs/guidelines.md - AI guidelines command
• docs/multi-platform.md - Multi-platform support
• .knowns/docs/guides/ - 9 new guide docs

🔧 Technical

• New src/search/ module:
  • chunker.ts - Document chunking for embeddings
  • embedding.ts - Embedding service (transformers.js)
  • engine.ts - Hybrid search engine
  • store.ts - Search index storage
  • index-service.ts - Incremental indexing
• New src/utils/progress-bar.ts - Progress bar utility
• New src/utils/auto-sync.ts - Version tracking
• New src/utils/sync-spec-acs.ts - Spec AC sync utility

Contributors

@howznguyen](https://github.com/howznguyen)

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.11.4...v0.12.0

v0.11.4

February 7, 2026 View on GitHub

Changea

• Add setNotifyProjectRoot() to cache project root in notify-server
• Call setNotifyProjectRoot() when MCP sets project via set_project tool
• Sync project root in getFileStore() for all MCP tool calls
• Fixes issue where MCP couldn't notify web UI due to process.cwd() mismatch

Contributors

@howznguyen](https://github.com/howznguyen)

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.11.3...v0.11.4

Showing all 30 releases. View on GitHub

Knowns v0.20.5

A new version is available

View changelog

Ask AI I

v0.20.5 available