Turn stateless AI into a project-aware engineering partner.
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.
AI is powerful — but fundamentally stateless.
Every session forces developers to:
This breaks flow and limits AI’s effectiveness.
Knowns fixes that.
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:
So AI doesn’t just generate code — it understands what it’s building.
Give AI long-term understanding of your codebase and workflows.
Connect specs, tasks, and docs into a unified context layer.
Automatically provide relevant context to AI — reducing noise and token usage.
Transform AI from a tool into a true engineering collaborator.
Keep your knowledge private and fully under your control.
Knowns sits above your existing tools and makes them readable by AI.
Your stack stays the same.
But now:
AI stops guessing — and starts contributing.
# npm
npm install -g knowns
# bun
bun install -g knowns
# npx (no install)
npx knowns
knowns init
knowns browser # Open Web UI
| 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 |
| Web UI | Kanban board, doc browser, mermaid diagrams |
# 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
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
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)"
| 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-spec | Create specification document for features (SDD) |
/kn-verify | Run SDD verification and coverage report |
/kn-doc | Create or update documentation |
/kn-extract | Extract reusable patterns into docs/templates |
/kn-template | List, run, or create code templates |
| 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 |
| Semantic Search | Setup and usage of AI-powered search |
| 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 |
Knowns will optionally support a self-hosted sync server — for teams that want shared visibility without giving up local-first workflows.
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 # Test
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.
FAQs
AI-native task and documentation management for dev teams
We found that knowns demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
TC39’s March 2026 meeting advanced eight ECMAScript proposals, including Temporal reaching Stage 4 and securing its place in the ECMAScript 2026 specification.
Research
/Security News
Since January 31, 2026, we identified at least 72 additional malicious Open VSX extensions, including transitive GlassWorm loader extensions targeting developers.
Research
Six malicious Packagist packages posing as OphimCMS themes contain trojanized jQuery that exfiltrates URLs, injects ads, and loads FUNNULL-linked redirects.