Knowns
by
A CLI‑first knowledge layer that gives AI persistent memory of project context, enabling tasks, linked documentation, and built‑in time tracking while keeping everything version‑controlled in a local .knowns folder.
Knowns Overview
What is Knowns about?
Knowns provides a persistent, file‑based knowledge store for development teams that work with AI assistants. By creating tasks and documentation through a command‑line interface (or a web UI) and linking them with @doc/... or @task-... references, the AI can automatically read the required context without repetitive explanations.
How to use Knowns?
- Install the CLI globally (or run via npx):
npx install -g knowns # or npm install -g knowns - Initialize a project:
knowns init - Create documentation:
knowns doc create "Auth Pattern" -d "JWT with guards" -f patterns - Create tasks and reference docs:
knowns task create "Add login" -d "Follow @doc/patterns/auth-pattern" --ac "User can log in" - Open the Web UI for a Kanban board and doc browser:
knowns browser - Interact with the AI by telling it to work on a task; it reads the task and linked docs automatically.
Key features of Knowns
- Task Management: Create, edit, list, and track tasks with acceptance criteria.
- Documentation System: Hierarchical markdown docs stored locally, versioned with Git.
- Context Linking:
@doc/...and@task-...references resolve to real files for AI consumption. - AI Integration: MCP server and
--plainoutput allow AI agents to read context directly. - Built‑in Time Tracking: Start/stop timers on tasks and generate reports.
- Web UI: Kanban board, document browser, dark mode.
- CLI‑first Design: Full functionality via terminal; web UI is optional.
Use cases of Knowns
- Developer‑AI Pair Programming: Provide the AI with persistent project knowledge so it can generate code, write tests, or refactor without repeated explanations.
- Onboarding: New team members can query
knowns searchor read linked docs to understand architecture quickly. - Documentation Sync: Keep docs and tasks in sync; updates to a doc automatically affect all linked tasks.
- Project Auditing: Use time‑tracking reports to see how much effort was spent on each feature.
- Remote Teams: Share a self‑hosted sync server (planned) for visibility while retaining a local‑first workflow.
FAQ from the Knowns
Q: Do I need an internet connection? A: Only for installing the CLI or publishing to npm. Once installed, all data lives locally.
Q: How does AI access my docs?
A: The MCP server or knowns <command> --plain streams plain text files, which AI agents can read directly.
Q: Can I use Knowns with other AI providers? A: Yes. The plain‑text output works with any model; the MCP integration is optimized for Claude Desktop but is not mandatory.
Q: Is the data stored in the cloud?
A: No. All files are stored in the .knowns/ folder of your repository, giving you full Git‑based version control.
Q: How do I contribute?
A: Fork the repo, run npm install, then use npm run dev to start development. Follow the guidelines in docs/developer-guide.md.
Knowns's README
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:
- 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.
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 |
| AI Integration | MCP Server, --plain output, guideline templates |
| Web UI | Kanban board, doc browser, dark mode |
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
# Documentation
knowns doc create "Title" -d "Description" -f "folder"
knowns doc "doc-name" --plain # View doc (shorthand)
knowns doc "doc-name" --info --plain # Check size/tokens first
knowns doc "doc-name" --toc --plain # Get table of contents
knowns doc "doc-name" --section "2" --plain # Read specific section
# Time & Search
knowns time start <id> && knowns time stop
knowns search "query" --plain
# AI Guidelines
knowns agents guideline # Output guidelines to stdout
knowns agents sync # Sync CLAUDE.md, AGENTS.md (minimal)
knowns agents sync --full # Sync with full embedded guidelines
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 |
| Web UI | Kanban board and document browser |
| MCP Integration | Claude Desktop setup |
| Configuration | Project structure and options |
| AI Workflow | Guide for AI agents |
| 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
For design principles and long-term direction, see Philosophy.
For technical details, see Architecture and Contributing.
Knowns Reviews
Login Required
Please log in to share your review and rating for this MCP.
Similar MCP Servers like Knowns
Explore related MCPs that share similar capabilities and solve comparable challenges
Memory
Officialby modelcontextprotocol
A basic implementation of persistent memory using a local knowledge graph. This lets Claude remember information about the user across chats.
Cognee
by topoteretes
Provides dynamic memory for AI agents through modular ECL (Extract, Cognify, Load) pipelines, enabling seamless integration with graph and vector stores using minimal code.
Basic Memory
by basicmachines-co
Enables persistent, local‑first knowledge management by allowing LLMs to read and write Markdown files during natural conversations, building a traversable knowledge graph that stays under the user’s control.
Obsidian Model Context Protocol
by smithery-ai
Provides read and search capabilities for Markdown notes in an Obsidian vault for Claude Desktop and other MCP clients.
Mcp Server Chatsum
by chatmcp
Summarize chat messages by querying a local chat database and returning concise overviews.
Minima
by dmayboroda
Provides on‑premises conversational retrieval‑augmented generation (RAG) with configurable Docker containers, supporting fully local execution, ChatGPT‑based custom GPTs, and Anthropic Claude integration.
Mcp Server Qdrant
Officialby qdrant
Provides a Model Context Protocol server that stores and retrieves semantic memories using Qdrant vector search, acting as a semantic memory layer.
MCP Memory Service
by doobidoo
Provides a universal memory service with semantic search, intelligent memory triggers, OAuth‑enabled team collaboration, and multi‑client support for Claude Desktop, Claude Code, VS Code, Cursor and over a dozen AI applications.
Context Portal
by GreatScottyMac
Provides a project‑specific memory bank that stores decisions, progress, architecture, and custom data, exposing a structured knowledge graph via MCP for AI assistants and IDE tools.