Introduction

Getting started with Knowns CLI - the knowledge management tool for developers

Knowns is a CLI-first knowledge and workflow layer that gives AI persistent memory of your project context. Document once, link everywhere.

v0.20 brings native ONNX embedding (no sidecar needed), consolidated MCP tools, AI permission guards, audit trails, and structural knowledge retrieval.

Latest Releases

v0.20.1: Fix ONNX runtime lib resolution in sibling dirs
v0.20.0: Native ONNX embedding, MCP tool consolidation (46 → 10 domain-grouped tools), AI permission model, MCP audit trail, structural knowledge retrieval, Windows native support
v0.19.x: Semantic reference runtime, tree-sitter sidecar, design system reference
v0.18.x: Code intelligence, code graph UI, workspace switching, chat UX, 3-layer memory, runtime adapter install

How To Use These Docs

If you are new to Knowns, read the docs in this order:

Installation
Task Management
Workflow
CLI Reference
Feature-specific pages such as MCP, memory, code intelligence, or Web UI

Why Knowns?

Modern development involves juggling tasks, documentation, and context across multiple tools. Knowns brings everything together in a simple, git-friendly format that works seamlessly with AI assistants.

Key Benefits

Semantic Search: AI-powered search using native ONNX embedding. Find by meaning, not just keywords
AI Chat: Built-in project-aware chat inside Knowns, powered by OpenCode
Spec-Driven Development: Write specs first with /kn-spec, link to tasks, auto-sync ACs
CLI-First: Everything accessible from your terminal
AI-Ready: Automatic context loading via @doc/..., @task-..., and @template/... references
Skills System: /kn-* namespace for task, spec, plan, implement, verify workflows
Code Intelligence: Dedicated code search, symbols, deps, and graph flows for code-aware AI work
Memory System: Working, project, and global memory layers for durable AI context
AI Permission Model: Capability-based permission guards for AI actions across MCP and runtime
MCP Audit Trail: Structured audit events and aggregate tool usage statistics
Structural Retrieval: Relation-aware knowledge retrieval across entities and graph edges
Dashboard + Web UI: Faster local interface for Kanban, docs, memory, graph, and chat
Knowledge Graph: Visualize relationships between tasks, docs, and memories
Template System: Generate code with Handlebars templates linked to documentation
Import System: Share docs and templates across projects from Git, npm, or local sources
Git-Friendly: All data stored as Markdown in .knowns/ folder

Prerequisites

Knowns supports multiple install paths. Only the npm-based path requires Node.js 20+. See the Installation Guide for platform-specific instructions.

Quick Start

# Install
curl -fsSL https://knowns.sh/script/install | sh

# Initialize in your project
cd your-project
knowns init

# Create your first task
knowns task create "Setup project" -d "Initial setup" --ac "Dependencies installed"

# Open local UI + AI Chat
knowns browser --open

# (Optional) Auto-setup MCP for AI assistants
knowns mcp setup

Core Concepts

Tasks

Tasks are the primary work items in Knowns. Each task has:

Title: Clear summary of what needs to be done
Description: Context and requirements
Acceptance Criteria: Testable outcomes
Status: todo, in-progress, in-review, blocked, on-hold, done, urgent

Documentation

Documentation lives in .knowns/docs/ as Markdown files with frontmatter. Reference docs anywhere using @doc/path or @docs/path syntax (both work identically).

Memory

Three-layer memory system for persistent AI context:

Working memory: Session-scoped, ephemeral
Project memory: Repo-specific patterns, decisions, conventions
Global memory: Cross-project preferences and workflow rules

Time Tracking

Built-in timers let you track time spent on tasks. Generate reports by date range, label, or project.

Templates

Code generation with Handlebars (.hbs) templates powered by Go's text/template engine. Each template can link to documentation for context-aware generation.

# List templates
knowns template list

# Generate code
knowns template run component --name Button