Every time you start a new AI coding session, you re-explain your architecture, paste docs, repeat conventions, and clarify past decisions. Your AI assistant is powerful - but it forgets everything between sessions.

Knowns fixes that. It gives AI assistants like Claude Code, Codex, Cursor, Copilot, OpenCode, and others structured, persistent access to your project's tasks, documentation, specs, acceptance criteria, and architectural decisions. Instead of prompting from scratch, your AI reads what it needs and picks up where you left off.

If you believe AI should truly understand software projects, consider giving Knowns a star.

Table of Contents

• Why Knowns?
• Before & After
• What is Knowns?
• Who It's For
• How It Works
• Quick Start
• Core Capabilities
• What You Can Build
• AI Integrations
• Agent Skills Workflow
• Installation
• Documentation
• Roadmap
• Development
• Links

Why Knowns?

AI coding assistants are stateless. Every session starts from zero.

That means you end up doing the same work over and over:

• Re-explaining your architecture and design patterns
• Pasting documentation into chat windows
• Repeating coding conventions and project rules
• Clarifying decisions that were already made last week
• Rebuilding context that took 20 minutes to set up

The AI doesn't lack intelligence. It lacks access to what your project already knows.

Knowns gives it that access.

Before & After

| Without Knowns | With Knowns | | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | | "We use the repository pattern with..." (paste 50 lines) | AI reads @doc/patterns/repository automatically | | "Here's the task, the acceptance criteria are..." (re-type everything) | AI reads the task, its ACs, linked specs, and related docs | | "Remember, we decided last week to..." (hope it sticks) | Choice is stored as a first-class System Decision with a verifiable lifecycle | | "The auth flow works like this..." (explain for the 4th time) | AI follows @doc/architecture/auth and builds on it | | "Are we done? Let me check the requirements again..." | AI checks acceptance criteria and validates completion itself | | Session starts cold - 10 min of context-setting | Session starts warm - AI already knows the project |

What is Knowns?

Knowns is a local-first, self-hostable project context layer for AI-native development.

It stores your project knowledge in structured, AI-readable files - and exposes them to AI assistants through CLI and MCP (Model Context Protocol).

Concretely, Knowns manages:

• Tasks with acceptance criteria, implementation plans, and status tracking
• Documentation in nested markdown folders with cross-references
• Specs that define what "done" looks like for a feature
• Memory - project-level, session-level, and global knowledge that AI can recall
• Templates for code generation with Handlebars
• References like @task-KN-4F7Q2M and @doc/patterns/auth that AI can follow and resolve
• Code intelligence - LSP-based symbols, definitions, references, diagnostics, and safe edits

Everything lives in a .knowns/ directory in your repo. Plain files. Committable to Git. No cloud required.

Who It's For

• Solo developers who pair with AI daily and want it to remember project context across sessions
• Teams building with AI assistants and tired of everyone re-explaining the same architecture
• Open-source maintainers who want contributors (human or AI) to onboard faster
• Anyone who uses Claude Code, Codex, Cursor, Copilot, OpenCode, Windsurf, or other AI coding tools and wants them to actually understand the project

How It Works

Knowns sits alongside your existing tools. Your stack stays the same.

1. You structure your project knowledge - tasks, docs, specs, decisions - using the Knowns CLI or Web UI
2. AI reads it - through MCP integration or CLI commands, your AI assistant accesses exactly the context it needs
3. AI acts on it - follows references, checks acceptance criteria, updates task status, and builds with full awareness
4. Knowledge accumulates - decisions, patterns, and conventions persist across sessions instead of disappearing

Your specs -> understood. Your tasks -> connected. Your docs -> usable. Your decisions -> remembered.

Quick Start

# Install
brew install knowns-dev/tap/knowns
# or: npm install -g knowns
# or: curl -fsSL https://knowns.sh/script/install | sh
# or on Windows PowerShell:
# irm https://knowns.sh/script/install.ps1 | iex

# verify the install
knowns --version

# Initialize in your project
cd your-project
knowns init
# Creates .knowns/ plus lightweight agent shims such as CLAUDE.md/AGENTS.md

# Before starting work, especially after cloning a repository
# that already contains .knowns/
knowns doctor

# or run without a global install
npx knowns init

# Create your first task
knowns task create "Add user authentication" \
  -d "JWT-based auth with login and register endpoints" \
  --ac "User can register with email/password" \
  --ac "User can login and receive JWT token" \
  --ac "Protected routes reject unauthenticated requests"

# Add project documentation
knowns doc create "Auth Architecture" \
  -f "architecture" \
  -d "Authentication design decisions and patterns"

# Open the Web UI
knowns browser --open

# Update Knowns later
knowns update

# Connect to your AI assistant via MCP
# See: docs/en/guides/mcp-integration.md

Now when your AI reads the project, it sees structured tasks with acceptance criteria, linked documentation, and clear definitions of done - instead of guessing.

Core Capabilities

Task & Workflow Management

Create tasks with acceptance criteria, implementation plans, and status tracking. AI can read tasks, follow plans, check off ACs, and know exactly when work is complete.

knowns task create "Title" --ac "Criterion 1" --ac "Criterion 2"
knowns task edit <id> -s in-progress
knowns task edit <id> --check-ac 1

Structured Documentation

Organize project knowledge in nested markdown folders. Cross-reference with @doc/path and @task-id. AI follows these references to load exactly the context it needs.

knowns doc create "API Design" -f "architecture"
knowns doc "architecture/api-design" --smart --plain

Project Memory

Three-layer memory system - project, session, and global - so AI recalls patterns, conventions, and preferences without you repeating them.

knowns memory add "We use repository pattern for data access" --category pattern
knowns memory list --plain

Knowns has two Decision domains: Spec Decisions are locked D1, D2, … rules inside an approved spec that implementers must follow and report; System Decisions are first-class records of durable project evolution. New System Decisions always start as drafts and become current only after linked evidence is verified.

knowns decision create "Use Postgres for metadata" --decision "Use Postgres as the metadata store."
knowns decision link <id> --source @doc/architecture/storage --task <done-task-id>
knowns decision accept <id>

Memory category decision is legacy and read-only for new writes. Review it with knowns decision migrate preview; migration is explicit, one record at a time, and reversible.

Semantic Search

Search by meaning, not just keywords. Runs locally with ONNX models - fully offline, no API keys needed.

knowns search "how does authentication work" --plain

MCP Integration

Full Model Context Protocol server. Claude Code, Codex, Cursor, OpenCode, and other MCP-compatible assistants get native access to tasks, docs, memory, search, and validation - no copy-pasting required.

Code Intelligence

LSP-based code intelligence for supported languages. List symbols, jump to definitions, find references, inspect diagnostics, and make safe symbol-aware edits through MCP.

knowns lsp list
knowns lsp install <language>

Project Diagnostics

Run knowns doctor before starting work, especially after cloning a repository that already contains .knowns/. It performs offline, read-only checks for project setup, semantic search, local runtimes, language servers, AI integration artifacts, and runtime-memory hooks. Findings include actionable remediation without applying changes automatically.

knowns doctor
knowns doctor --scope search,lsp
knowns doctor --verbose
knowns doctor --json --strict

Templates & Code Generation

Handlebars-based templates for scaffolding. Define patterns once, generate consistently.

knowns template list
knowns template run <name> --name "UserService"

AI Agent Workspaces

Multi-phase agent orchestration with git worktree isolation, live terminal streaming, and automatic phase progression (research -> plan -> implement -> review).

Web UI

Kanban board, document browser, knowledge graph visualization, and mermaid diagram support - all in a local browser UI.

knowns browser --open

What You Can Build With Knowns

| Capability | What It Does | | --------------------- | ----------------------------------------------------------------------- | | Task Management | Tasks with acceptance criteria, plans, status, and time tracking | | Documentation | Nested markdown folders with cross-references and mermaid support | | Semantic Search | Meaning-based search with local AI models (fully offline) | | Time Tracking | Built-in timers and reports per task | | Context Linking | @task-KN-4F7Q2M and @doc/patterns/auth references AI can resolve | | Validation | Detect broken references and incomplete tasks with knowns validate | | Template System | Code generation with Handlebars (.hbs) templates | | Import System | Import docs and templates from git, npm, or local sources | | Memory System | Project / session / global memory for persistent AI recall | | MCP Server | Native AI assistant integration with full tool access | | AI Workspaces | Multi-phase agent orchestration with worktree isolation | | Code Intelligence | LSP-based symbols, definitions, references, diagnostics, and safe edits | | Web UI | Kanban board, doc browser, knowledge graph, mermaid diagrams |

AI Integrations

Knowns does not replace your AI assistant. It gives the assistants you already use one shared project context layer: tasks, docs, specs, memory, decisions, search, validation, and code intelligence through MCP and synced skills.

For normal personal setup, use knowns setup <target> --global. Use project-level setup only when you intentionally want config files committed or scoped to one repository.

| Assistant | Setup | What it gets | | ------------------------ | -------------------------------------------------------------------- | ------------------------------------------------- | | Claude Code | knowns setup claude --global | MCP, /kn-* skills, runtime memory hooks | | Codex | knowns setup codex --global | MCP, $kn-* skills, runtime memory hooks | | OpenCode | knowns setup opencode --global | MCP, .agents/skills, plugin/runtime integration | | Kiro | knowns setup kiro --global | MCP, skills, runtime hooks | | Cursor | knowns setup cursor --global | MCP access to Knowns context | | Gemini / Antigravity | knowns setup gemini --global / knowns setup antigravity --global | Global MCP config | | Copilot / generic agents | knowns setup copilot / knowns setup agents | Instruction shims and agent-readable guidance |

See Platforms for the full mapping.

Agent Skills Workflow

When using Knowns with an agent runtime such as Claude Code or Codex, skills provide a guided workflow:

Tiny change:
/kn-init -> /kn-research -> /kn-plan -> /kn-implement -> /kn-review -> /kn-commit

Feature / approved spec:
/kn-init -> /kn-research -> /kn-spec -> /kn-flow -> /kn-commit

Example Session

Claude Code example:

You: /kn-init
Claude: [Reads README, ARCHITECTURE, checks task backlog]
        "Project uses NestJS with CQRS pattern. 3 tasks in-progress..."

You: /kn-plan 42
Claude: [Takes task, reads refs, searches docs]
        "Task #42: Add user authentication

         ## Implementation Plan
         1. Review @doc/patterns/auth
         2. Create AuthModule with JWT strategy
         3. Add login/register endpoints
         4. Write unit tests

         Approve this plan?"

You: Yes

You: /kn-implement 42
Claude: [Follows plan, generates code, checks ACs]
        "✓ AC1: User can login - DONE
         ✓ AC2: JWT token returned - DONE
         ✓ AC3: Tests pass - DONE

         All acceptance criteria complete. Ready to commit?"

You: /kn-commit
Claude: [Creates conventional commit]
        "feat(auth): add JWT authentication

         - Add AuthModule with passport JWT strategy
         - Add login/register endpoints
         - Add unit tests (94% coverage)"

All Skills

Skills are agent workflow commands, not MCP tools. MCP tools show up in codex mcp as domain tools such as tasks, docs, memory, search, and code; skills are synced separately to the agent's skills directory.

| Platform | Invocation | | ----------- | ------------------------------------ | | Claude Code | /kn-spec, /kn-flow, /kn-review | | Codex | $kn-spec, $kn-flow, $kn-review |

The table below uses Claude Code's /kn-* syntax. In Codex, use the same skill name with $ instead of /.

| Skill | Description | | --------------------------- | --------------------------------------------------------------------- | | /kn-init | Initialize session - read docs, load memory, understand project | | /kn-plan <id> | Take task, gather context, create implementation plan | | /kn-implement <id> | Execute plan, track progress, check acceptance criteria | | /kn-research | Research project context, code, and relevant external MCP/web sources | | /kn-handoff | Write a cross-repo brief or API contract handoff document | | /kn-commit | Create conventional commit with verification | | /kn-spec | Create specification document for features (SDD) | | /kn-flow @doc/<spec-path> | Recommended full approved-spec flow: plan, implement, review, verify | | /kn-go <spec> | Legacy full pipeline from approved spec without review gates | | /kn-verify | Run SDD verification and coverage report | | /kn-review | Multi-perspective code review (P1/P2/P3 severity) | | /kn-doc | Create or update documentation | | /kn-extract | Extract reusable patterns into docs, templates, and memory | | /kn-template | List, run, or create code templates | | /kn-debug | Debug errors and failures with memory-backed triage |

Installation

Homebrew (macOS/Linux)

brew install knowns-dev/tap/knowns

Shell installer (macOS/Linux)

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

# Or with wget
wget -qO- https://knowns.sh/script/install | sh

# Install a specific version
curl -fsSL https://knowns.sh/script/install | KNOWNS_VERSION=0.18.0 sh

PowerShell installer (Windows)

irm https://knowns.sh/script/install.ps1 | iex

# Install a specific version
$env:KNOWNS_VERSION = "0.18.0"; irm https://knowns.sh/script/install.ps1 | iex

If semantic search reports a missing local model, run knowns search --setup or download one explicitly with knowns model download <model-id>, then rebuild with knowns search --reindex.

npm

# Global install - auto-downloads platform-specific binary
npm install -g knowns

# Or run without installing
npx knowns

From source (Go 1.24.2+)

go install github.com/howznguyen/knowns/cmd/knowns@latest

# Or clone and build
git clone https://github.com/knowns-dev/knowns.git
cd knowns
make build        # Output: bin/knowns
make install      # Install to GOPATH/bin

Uninstall

Use the method that matches how you installed Knowns:

# Homebrew
brew uninstall knowns

# npm
npm uninstall -g knowns

# Shell installer (macOS/Linux)
curl -fsSL https://knowns.sh/script/uninstall | sh

# Go install
rm -f "$(go env GOPATH)/bin/knowns"

# PowerShell installer (Windows)
irm https://knowns.sh/script/uninstall.ps1 | iex

If you installed runtime memory adapters, remove them before uninstalling the CLI:

knowns runtime uninstall codex

Uninstall removes CLI binaries and PATH entries added by the installer. It leaves project .knowns/ folders, tasks, docs, memories, and AI integration files untouched. Delete .knowns/ only if you intentionally want to discard project context.

Quick Reference

# Tasks
knowns task create "Title" -d "Description" --ac "Criterion"
knowns task list --plain
knowns task <id> --plain
knowns task edit <id> -s in-progress -a @me
knowns task edit <id> --check-ac 1

# Documentation
knowns doc create "Title" -d "Description" -f "folder"
knowns doc "doc-name" --plain
knowns doc "doc-name" --smart --plain
knowns doc "doc-name" --section "2" --plain

# Templates
knowns template list
knowns template run <name> --name "X"
knowns template create <name>

# Imports
knowns import add <name> <source>
knowns import sync
knowns import list

# Time, Search & Validate
knowns time start <id> && knowns time stop
knowns search "query" --plain
knowns validate

# Code intelligence
knowns lsp list
knowns lsp install <language>
# Use the MCP code tool for symbols, definitions, references, diagnostics, and edits

# Project diagnostics
knowns doctor
knowns doctor --scope search,lsp
knowns doctor --json --strict

# AI setup
knowns setup agents        # lightweight repo-local agent shims only
knowns setup codex --global # user-level Codex MCP/skills/hooks
knowns setup --global      # interactive user-level AI integration setup
knowns setup               # interactive project integration setup
knowns sync

Documentation

| Guide | Description | | ------------------------------------------------------------ | ------------------------------------------------------------ | | Installation | Install, verify, run without a global install, and uninstall | | User Guide | Getting started and daily usage | | Command Reference | Core CLI commands with examples | | Workflow Guide | Recommended human + AI workflow | | MCP Integration | MCP setup and supported platforms | | Reference System | How @doc/ and @task- linking works | | Semantic Search | Setup and usage of semantic search | | Templates | Code generation and template workflows | | Web UI | Board, docs, graph, and config UI | | Configuration | Project config and platform IDs | | Skills | Skill paths and regeneration | | Developer Guide | Notes for contributors | | Platforms | Platform integration mapping |

Roadmap

AI Agent Workspaces ✅ (Active)

Multi-phase agent orchestration - assign tasks to AI agents with git worktree isolation, live terminal streaming, and automatic phase progression (research -> plan -> implement -> review).

Self-Hosted Team Sync 🚧 (Planned)

Optional self-hosted sync server for shared visibility without giving up local-first workflows.

• Real-time visibility - See who is working on what
• Shared knowledge - Sync tasks and documentation across the team
• Full data control - Self-hosted, no cloud dependency

Development

Requires Go 1.24.2+ and optionally Node.js + pnpm for UI development.

make build              # Build binary -> bin/knowns
make dev                # Build with race detector
make test               # Run unit tests
make test-e2e           # Run CLI + MCP E2E tests
make test-e2e-semantic  # E2E tests including semantic search
make lint               # Run golangci-lint
make cross-compile      # Build for all 6 platforms
make ui                 # Rebuild embedded Web UI (requires pnpm)

Project Structure

cmd/knowns/          # CLI entry point
internal/
  cli/               # Cobra commands
  models/            # Domain models
  storage/           # File-based storage (.knowns/)
  server/            # HTTP server, SSE, WebSocket
    routes/          # REST API handlers
    workspace/       # Agent orchestrator, process manager, worktree
  mcp/               # MCP server (stdio)
  search/            # Semantic search (ONNX)
ui/                  # Embedded React UI (built assets)
tests/               # E2E tests

Links

• npm
• GitHub
• Discord
• Releases

For design principles and long-term direction, see Philosophy.

For technical details, see Architecture and Contributing.

Support Knowns

If Knowns helps your workflow, consider supporting its development:

• ⭐ Star the repo - helps others discover the project
• 🐛 Report bugs and suggest features - your feedback shapes the roadmap
• 💬 Share with your team - the more developers who use it, the better it gets
• ☕ Sponsor on GitHub - sustains ongoing development

All contributions help make Knowns better for everyone building with AI.