knowns

Knowns

What your AI should have knowns.

CLI-first knowledge layer that gives AI persistent memory of your project.

TL;DR: Knowns is a CLI-first knowledge layer that lets AI reliably read and reuse your project context — instead of asking the same questions every session.

The Problem

AI assistants are stateless — they forget your architecture, patterns, and decisions every session.

Session 1: "Implement feature X" → AI: "How does your auth work?" → You explain

Session 2: "Implement feature Y" → AI: "How does your auth work?" → You explain AGAIN

Session 100: Still explaining the same thing...

The Solution

# Document once
knowns doc create "Auth Pattern" -d "JWT with guards" -f patterns

# Reference everywhere
knowns task create "Add login" -d "Follow @doc/patterns/auth-pattern"

# AI reads context automatically — never forgets

How it works:

• You plan — Create tasks with acceptance criteria in Web UI or CLI
• You link — Reference docs like @doc/patterns/auth in task descriptions
• AI executes — Tell AI "Work on task 42", it reads the task, follows the refs, and implements

Knowns resolves @doc/... and @task-... into real files. AI reads them via MCP or --plain output — no copy-paste needed.

Install

# Homebrew (macOS/Linux) - no Node.js required
brew install knowns-dev/tap/knowns

# npm
npm install -g knowns

# bun
bun install -g knowns

# npx (no install)
npx knowns


knowns init
knowns browser  # Open Web UI

Why Knowns over Notion / Jira / Obsidian?

	Knowns	Notion/Jira	Obsidian
AI-readable	--plain output, MCP server	Copy-paste manually	Plugins needed
File-based	Git-friendly .knowns/ folder	Cloud-locked	Local files
CLI-first	Full CLI + Web UI	Web only	GUI only
Context linking	@doc/... @task-42 refs	Manual links	Wiki links
Source of truth	Local files (Git-versioned)	Remote database	Local vault
Minimal setup	knowns init and done	Complex setup	Many plugins

Best for: Dev teams who pair with AI and want persistent project memory.

Features

Feature	Description
Task Management	Create, track tasks with acceptance criteria
Documentation	Nested folders with markdown + mermaid support
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
Web UI	Kanban board, doc browser, mermaid diagrams

Quick Reference

# 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 CLAUDE.md, AGENTS.md
knowns agents sync --type mcp               # MCP tools format

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

Skill	Description
/kn-init	Initialize session - read docs, understand project
/kn-plan <id>	Take task, gather context, create implementation plan
/kn-implement <id>	Execute plan, track progress, check acceptance criteria
/kn-research	Search codebase, find patterns, explore before coding
/kn-commit	Create conventional commit with verification
/kn-doc	Create or update documentation
/kn-extract	Extract reusable patterns into docs/templates
/kn-template	List, run, or create code templates

Documentation

Guide	Description
Command Reference	All CLI commands with examples
Workflow Guide	Task lifecycle from creation to completion
Reference System	How @doc/ and @task- linking works
Templates	Code generation with Handlebars
Web UI	Kanban board and document browser
MCP Integration	Claude Desktop setup with full MCP tools
Configuration	Project structure and options
Developer Guide	Technical docs for contributors
Changelog	Version history

Roadmap

Self-Hosted Team Sync 🚧 (Planned)

Knowns will optionally support a self-hosted sync server — for teams that want 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
• Progress tracking — Track activity over time
• Full data control — Self-hosted, no cloud dependency

The CLI and local .knowns/ folder remain the source of truth. The server acts only as a sync and visibility layer.

Development

npm install
npm run dev      # Dev mode
npm run build    # Build
npm run test     # Test

Links

• npm
• GitHub
• Discord
• Changelog

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

For technical details, see Architecture and Contributing.

What your AI should have knowns.
Built for dev teams who pair with AI.