knowns

<p align="center">
  <img src="./images/logo.png" alt="Knowns logo" width="240">
</p>

# Knowns

[![Go](https://img.shields.io/badge/go-%3E%3D1.24.2-00ADD8?style=flat-square&logo=go)](https://go.dev/)
[![npm](https://img.shields.io/npm/v/knowns.svg?style=flat-square)](https://www.npmjs.com/package/knowns)
[![CI](https://github.com/knowns-dev/knowns/actions/workflows/ci.yml/badge.svg)](https://github.com/knowns-dev/knowns/actions/workflows/ci.yml)
[![Platform](https://img.shields.io/badge/platform-win%20%7C%20mac%20%7C%20linux-lightgrey?style=flat-square)](#installation)
[![License](https://img.shields.io/github/license/knowns-dev/knowns?style=flat-square)](LICENSE)

> Turn stateless AI into a project-aware engineering partner.

> [!WARNING]
> Knowns is under active development. APIs, database schemas, and configuration formats may change between releases. Review the known limitations and security considerations before deploying to production.

> [!IMPORTANT]
> **v0.13+: Rewritten in Go.** To support AI Agent Workspaces (process management, live terminal, git worktree isolation), Knowns has been rewritten in Go as a native binary. CLI commands and `.knowns/` data format are fully backward-compatible. Install via `npm i -g knowns` still works (auto-downloads platform binary).

**Knowns is the memory layer for AI-native software development — enabling AI to understand your project instantly.**

Instead of starting from zero every session, AI works with structured, persistent project context.

No repeated explanations.  
No pasted docs.  
No lost architectural knowledge.

Just AI that already understands your system.

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

<p align="center">
  <img src="./images/task-workflow.gif" alt="Knowns task workflow demo" width="100%">
</p>

## Table of Contents

- [Why Knowns?](#why-knowns)
- [What is Knowns?](#what-is-knowns---really)
- [Core Capabilities](#core-capabilities)
- [How It Works](#how-it-works)
- [Installation](#installation)
- [What You Can Build](#what-you-can-build-with-knowns)
- [Quick Reference](#quick-reference)
- [Claude Code Skills Workflow](#claude-code-skills-workflow)
- [Documentation](#documentation)
- [Roadmap](#roadmap)
- [Development](#development)
- [Links](#links)

---

## Why Knowns?

AI is powerful — but fundamentally **stateless**.

Every session forces developers to:

- Re-explain architecture
- Paste documentation
- Repeat conventions
- Clarify past decisions
- Rebuild context

This breaks flow and limits AI’s effectiveness.

### AI doesn't lack intelligence.

### It lacks the right context.

**Knowns fixes that.**

---

## What is Knowns - Really?

Knowns provides **persistent, structured project understanding** so AI can operate with full awareness of your software environment.

Think of it as your project's **external brain**.

Knowns connects:

- Specs
- Tasks
- Documentation
- Decisions
- Team knowledge

So AI doesn’t just generate code — it understands what it’s building.

---

## Core Capabilities

### 🧠 Persistent Project Memory

Give AI long-term understanding of your codebase and workflows.

### 🔗 Structured Knowledge

Connect specs, tasks, and docs into a unified context layer.

### ⚡ Smart Context Delivery

Automatically provide relevant context to AI — reducing noise and token usage.

### 🤝 AI-Native Workflow

Transform AI from a tool into a true engineering collaborator.

### 🔐 Self-Hostable

Keep your knowledge private and fully under your control.

---

## How It Works

Knowns sits **above your existing tools** and makes them readable by AI.

Your stack stays the same.

But now:

- Specs → understood
- Tasks → connected
- Docs → usable
- Decisions → remembered

AI stops guessing — and starts contributing.

---

## Installation

### Pre-built binaries

```bash
# Homebrew (macOS/Linux)
brew install knowns-dev/tap/knowns
```

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

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

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

### Uninstall

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

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

The uninstall scripts only remove installed CLI binaries and PATH entries added by the installer. They leave project `.knowns/` folders untouched.

```bash
# npm — installs platform-specific binary automatically
npm install -g knowns

# npx (no install)
npx knowns
```

### From source (Go 1.24.2+)

```bash
# Install to GOPATH/bin
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: dist/knowns
make install      # Install to GOPATH/bin
```

### Get started

```bash
knowns init
knowns browser --open   # Start Web UI and open browser
```

---

## What You Can Build With Knowns

| Feature             | Description                                        |
| ------------------- | -------------------------------------------------- |
| **Task Management** | Create, track tasks with acceptance criteria       |
| **Documentation**   | Nested folders with markdown + mermaid support     |
| **Semantic Search** | Search by meaning with local AI models (offline)   |
| **Time Tracking**   | Built-in timers and reports                        |
| **Context Linking** | `@task-42` and `@doc/patterns/auth` references     |
| **Validation**      | Check broken refs with `knowns validate`           |
| **Template System** | Code generation with Handlebars (`.hbs`) templates |
| **Import System**   | Import docs/templates from git, npm, or local      |
| **AI Integration**  | Full MCP Server with AC/plan/notes operations      |
| **AI Workspaces**   | Multi-phase agent orchestration with live terminal |
| **Web UI**          | Kanban board, doc browser, mermaid diagrams        |

---

## Quick Reference

```bash
# Tasks
knowns task create "Title" -d "Description" --ac "Criterion"
knowns task list --plain
knowns task <id> --plain                    # View task (shorthand)
knowns task edit <id> -s in-progress -a @me
knowns task edit <id> --check-ac 1          # Mark AC as done

# Documentation
knowns doc create "Title" -d "Description" -f "folder"
knowns doc "doc-name" --plain               # View doc (shorthand)
knowns doc "doc-name" --smart --plain       # Auto-handle small/large docs
knowns doc "doc-name" --section "2" --plain # Read specific section

# Templates
knowns template list                        # List available templates
knowns template run <name> --name "X"       # Generate from template
knowns template create <name>               # Create new template

# Imports
knowns import add <name> <source>           # Add import
knowns import sync                          # Sync all imports
knowns import list                          # List imports

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

# AI Guidelines
knowns agents --sync                        # Sync/generate instruction files
knowns sync                                 # Sync skills + instruction files
```

---

## Claude Code Skills Workflow

When using Claude Code with Knowns, use skills (slash commands) for a guided workflow:

```
/kn-init     → Read project docs, understand context
/kn-plan     → Take task, gather context, create plan (wait for approval)
/kn-implement → Follow plan, check ACs, track progress
/kn-commit   → Commit with conventional format
```

### Example Session

```
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: [Take

[truncated…]