Know what your team knows.
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.
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...
# 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 forgetsHow it works:
- You plan — Create tasks with acceptance criteria in Web UI or CLI
- You link — Reference docs like
@doc/patterns/authin 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.
# using npm
npm install -g knowns
# using bun
bun install -g knowns
knowns init
knowns browser # Open Web UI| 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.
| 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 |
| AI Integration | MCP Server for Claude, --plain output |
| Web UI | Kanban board, doc browser, dark mode |
# 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
# Documentation
knowns doc create "Title" -d "Description" -f "folder"
knowns doc "doc-name" --plain # View doc (shorthand)
# Time & Search
knowns time start <id> && knowns time stop
knowns search "query" --plain| 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 |
| Web UI | Kanban board and document browser |
| MCP Integration | Claude Desktop setup |
| Configuration | Project structure and options |
| AI Workflow | Guide for AI agents |
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.
npm install
npm run dev # Dev mode
npm run build # Build
npm run test # TestFor design principles and long-term direction, see Philosophy.
For technical details, see Architecture and Contributing.
Know what your team knows.
Built for dev teams who pair with AI.