by knowns-dev
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 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.
npx install -g knowns # or npm install -g knowns
knowns init
knowns doc create "Auth Pattern" -d "JWT with guards" -f patterns
knowns task create "Add login" -d "Follow @doc/patterns/auth-pattern" --ac "User can log in"
knowns browser
@doc/... and @task-... references resolve to real files for AI consumption.--plain output allow AI agents to read context directly.knowns search or read linked docs to understand architecture quickly.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.
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 forgets
How it works:
@doc/patterns/auth in task descriptionsKnowns 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, --plain output, guideline templates |
| 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)
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
| 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 |
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.
Please log in to share your review and rating for this MCP.
Explore related MCPs that share similar capabilities and solve comparable challenges
by modelcontextprotocol
A basic implementation of persistent memory using a local knowledge graph. This lets Claude remember information about the user across chats.
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.
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.
by smithery-ai
Provides read and search capabilities for Markdown notes in an Obsidian vault for Claude Desktop and other MCP clients.
by chatmcp
Summarize chat messages by querying a local chat database and returning concise overviews.
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.
by qdrant
Provides a Model Context Protocol server that stores and retrieves semantic memories using Qdrant vector search, acting as a semantic memory layer.
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.
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.