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:

1. You plan — Create tasks with acceptance criteria in Web UI or CLI
2. You link — Reference docs like @doc/patterns/auth in task descriptions
3. 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

# using npm
npm install -g knowns

# using bun
bun install -g 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 support | | Time Tracking | Built-in timers and reports | | Context Linking | @task-42 and @doc/patterns/auth references | | 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, templates page |

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
knowns time start <id> && knowns time stop
knowns search "query" --plain

# AI Guidelines
knowns agents sync                          # Sync CLAUDE.md, AGENTS.md
knowns agents sync --type mcp               # MCP tools format

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
• Changelog

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

For technical details, see Architecture and Contributing.