Knowns

AI-native task and documentation management tool for dev teams, serving as a persistent memory layer for AI. Manages tasks, documents, and decisions via local Markdown file system, leveraging MCP protocol to grant AI assistants persistent contextual understanding of projects.

Core Positioning#

Knowns is a TypeScript-based CLI tool and Web platform designed to serve as the "memory layer" for AI-native development. It solves the "statelessness" pain point of large language models in programming assistance — traditional AI assistants lose project context in every session, forcing developers to repeatedly explain architecture, paste documents, and restate conventions.

Core Capabilities#

Persistent Project Memory#

Provides AI with long-term understanding of codebase and workflows
Solves the problem of state loss between AI sessions
Connects specifications, tasks, documents, and decisions into a unified context layer

Development Workflow Enhancement#

Task Management: Create and track tasks with acceptance criteria checking
Document Management: Nested folder structure with Markdown + Mermaid diagram support
Semantic Search: Local AI model-based semantic search (offline capable)
Time Tracking: Built-in timer and reporting functionality
Context Links: Support for @task-42 and @doc/patterns/auth reference formats
Validation System: Checks for broken reference links
Template System: Code generation using Handlebars (.hbs) templates
Import System: Import documents/templates from git, npm, or local sources

AI-Native Integration#

Complete MCP Server with AC/plan/notes operations support
Deep integration with Claude Code workflow
Intelligent context delivery with automatic relevant context filtering

Claude Code Skill Commands#

/kn-init - Initialize session and read project documents
/kn-plan <id> - Create implementation plan
/kn-implement <id> - Execute plan and check acceptance criteria
/kn-research - Search codebase and explore patterns
/kn-commit - Create standardized commits
/kn-spec - Create feature specification documents (SDD)
/kn-verify - Run SDD validation and coverage reports
/kn-doc - Create or update documentation
/kn-extract - Extract reusable patterns
/kn-template - List, run, or create code templates

Architecture Design#

Core Principles#

Files as Database: No SQLite, no JSON databases, only Markdown files
Markdown + Frontmatter: Human-readable, machine-parsable standard format
Local-First: Data never leaves the local machine by default, fully self-controlled

Technical Implementation#

Layered architecture: User Layer (CLI/Web UI/MCP Server) → Command Layer → Storage Layer → File System

Project Structure#

.knowns/
├── config.json           # Project configuration
├── tasks/                # Task Markdown files
├── docs/                 # Document Markdown files
└── .versions/            # Version history (hidden)

Use Cases#

Long-term Project Development: Teams needing AI to continuously understand project context
Knowledge Management: Maintaining project specifications, decisions, and best practices
AI-Assisted Programming: Enhancing AI assistant's contextual understanding
Team Collaboration: Future support for self-hosted team sync
Offline Work: Local-first with complete data autonomy

Installation & Usage#

# Install globally with npm
npm install -g knowns

# Or use bun
bun install -g knowns

# Initialize project
knowns init

# Start Web UI
knowns browser

System Requirements#

Node.js >= 20.0.0
Bun required for development build