![\"Knowns\"](\"./images/logo.png\"){kind=logo}
\n\n \n
\n ![\"Go\"](\"https://img.shields.io/badge/go-%3E%3D1.24.2-00ADD8?style=flat-square&logo=go\"){kind=icon}
![\"Release\"](\"https://img.shields.io/github/v/release/knowns-dev/knowns?style=flat-square\")
![\"GitHub](\"https://img.shields.io/github/stars/knowns-dev/knowns?style=flat-square\")
![\"CI\"](\"https://github.com/knowns-dev/knowns/actions/workflows/ci.yml/badge.svg\"){kind=icon}
\n ![\"Platform\"](\"https://img.shields.io/badge/platform-win%20%7C%20mac%20%7C%20linux-lightgrey?style=flat-square\"){kind=icon}
![\"Join](\"https://img.shields.io/badge/Discord-Join-5865F2?style=flat-square&logo=discord&logoColor=white\"){kind=icon}
![\"License\"](\"https://img.shields.io/github/license/knowns-dev/knowns?style=flat-square\")
\n \n
![\"Working](\"https://img.shields.io/badge/Working%20on-Claude-D97757?style=flat-square&logo=claude&logoColor=fff\"){kind=icon}
\n Homepage |\n Tiếng Việt |\n Documentation\n
\n\n\n Give your AI coding assistant structured access to tasks, docs, specs, and decisions - so it stops guessing and starts building.\n
\n\n---\n\nEvery time you start a new AI coding session, you re-explain your architecture, paste docs, repeat conventions, and clarify past decisions. Your AI assistant is powerful - but it forgets everything between sessions.\n\n**Knowns fixes that.** It gives AI assistants like Claude Code, Codex, Cursor, Copilot, OpenCode, and others structured, persistent access to your project's tasks, documentation, specs, acceptance criteria, and architectural decisions. Instead of prompting from scratch, your AI reads what it needs and picks up where you left off.\n\nIf you believe AI should truly understand software projects, consider giving **Knowns** a star.\n\n\n \n ![\"Knowns](\"./images/knowns-full-pipeline-20s.gif\")
\n \n
\n Click the preview to watch the full pipeline demo video.\n
\n\n## Table of Contents\n\n- [Why Knowns?](#why-knowns)\n- [Before & After](#before--after)\n- [What is Knowns?](#what-is-knowns)\n- [Who It's For](#who-its-for)\n- [How It Works](#how-it-works)\n- [Quick Start](#quick-start)\n- [Core Capabilities](#core-capabilities)\n- [What You Can Build](#what-you-can-build-with-knowns)\n- [AI Integrations](#ai-integrations)\n- [Agent Skills Workflow](#agent-skills-workflow)\n- [Installation](#installation)\n- [Documentation](#documentation)\n- [Roadmap](#roadmap)\n- [Development](#development)\n- [Links](#links)\n\n---\n\n## Why Knowns?\n\nAI coding assistants are stateless. Every session starts from zero.\n\nThat means you end up doing the same work over and over:\n\n- **Re-explaining** your architecture and design patterns\n- **Pasting** documentation into chat windows\n- **Repeating** coding conventions and project rules\n- **Clarifying** decisions that were already made last week\n- **Rebuilding** context that took 20 minutes to set up\n\nThe AI doesn't lack intelligence. **It lacks access to what your project already knows.**\n\nKnowns gives it that access.\n\n---\n\n## Before & After\n\n| Without Knowns | With Knowns |\n| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |\n| \"We use the repository pattern with...\" _(paste 50 lines)_ | AI reads `@doc/patterns/repository` automatically |\n| \"Here's the task, the acceptance criteria are...\" _(re-type everything)_ | AI reads the task, its ACs, linked specs, and related docs |\n| \"Remember, we decided last week to...\" _(hope it sticks)_ | Choice is stored as a first-class System Decision with a verifiable lifecycle |\n| \"The auth flow works like this...\" _(explain for the 4th time)_ | AI follows `@doc/architecture/auth` and builds on it |\n| \"Are we done? Let me check the requirements again...\" | AI checks acceptance criteria and validates completion itself |\n| Session starts cold - 10 min of context-setting | Session starts warm - AI already knows the project |\n\n---\n\n## What is Knowns?\n\nKnowns is a **local-first, self-hostable project context layer** for AI-native development.\n\nIt stores your project knowledge in structured, AI-readable files - and exposes them to AI assistants through CLI and [MCP (Model Context Protocol)](https://modelcontextprotocol.io/).\n\n\n ![\"How](\"./images/how-knowns-works.png\")
\n
\n ![\"Knowns](\"./images/architecture.png\")
\n
\n ![\"Knowns](\"./images/workflow.png\")
\n
\n What your AI should have knowns.
\n Built for dev teams who pair with AI.\n