{"id":34862580,"url":"https://github.com/knowns-dev/knowns","last_synced_at":"2026-04-22T05:08:19.962Z","repository":{"id":330627638,"uuid":"1122851911","full_name":"knowns-dev/knowns","owner":"knowns-dev","description":"The memory layer for AI-native development — giving AI persistent understanding of your software projects.","archived":false,"fork":false,"pushed_at":"2026-03-27T07:30:43.000Z","size":18799,"stargazers_count":136,"open_issues_count":3,"forks_count":21,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-27T08:16:09.512Z","etag":null,"topics":["ai","ai-agents","ai-native","ai-workflow","cli","context-management","developer-tools","devex","knowledge-base","llm","memory-layer","open-source"],"latest_commit_sha":null,"homepage":"http://knowns.sh","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/knowns-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"howznguyen","open_collective":"knowns","ko_fi":"howznguyen","buy_me_a_coffee":"howznguyen"}},"created_at":"2025-12-25T16:52:27.000Z","updated_at":"2026-03-27T02:11:51.000Z","dependencies_parsed_at":null,"dependency_job_id":"3c609232-8b27-43a9-a03f-7e6166565126","html_url":"https://github.com/knowns-dev/knowns","commit_stats":null,"previous_names":["knowns-dev/knowns"],"tags_count":48,"template":false,"template_full_name":null,"purl":"pkg:github/knowns-dev/knowns","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knowns-dev%2Fknowns","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knowns-dev%2Fknowns/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knowns-dev%2Fknowns/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knowns-dev%2Fknowns/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/knowns-dev","download_url":"https://codeload.github.com/knowns-dev/knowns/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knowns-dev%2Fknowns/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291132,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","ai-native","ai-workflow","cli","context-management","developer-tools","devex","knowledge-base","llm","memory-layer","open-source"],"created_at":"2025-12-25T21:29:55.679Z","updated_at":"2026-04-22T05:08:19.956Z","avatar_url":"https://github.com/knowns-dev.png","language":"TypeScript","funding_links":["https://github.com/sponsors/howznguyen","https://opencollective.com/knowns","https://ko-fi.com/howznguyen","https://buymeacoffee.com/howznguyen"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./images/cover.svg\" alt=\"Knowns — The memory layer for AI-native development\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n# Knowns\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://go.dev/\"\u003e\u003cimg src=\"https://img.shields.io/badge/go-%3E%3D1.24.2-00ADD8?style=flat-square\u0026logo=go\" alt=\"Go\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/knowns\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/knowns.svg?style=flat-square\" alt=\"npm\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/knowns-dev/knowns/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/knowns-dev/knowns/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"#installation\"\u003e\u003cimg src=\"https://img.shields.io/badge/platform-win%20%7C%20mac%20%7C%20linux-lightgrey?style=flat-square\" alt=\"Platform\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/knowns-dev/knowns?style=flat-square\" alt=\"License\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003e Turn stateless AI into a project-aware engineering partner.\n\n\u003e [!WARNING]\n\u003e Knowns is under active development. APIs, database schemas, and configuration formats may change between releases. Review the known limitations and security considerations before deploying to production.\n\n\u003e [!IMPORTANT]\n\u003e **v0.13+: Rewritten in Go.** To support AI Agent Workspaces (process management, live terminal, git worktree isolation), Knowns has been rewritten in Go as a native binary. CLI commands and `.knowns/` data format are fully backward-compatible. Install via `npm i -g knowns` still works (auto-downloads platform binary).\n\n**Knowns is the memory layer for AI-native software development — enabling AI to understand your project instantly.**\n\nInstead of starting from zero every session, AI works with structured, persistent project context.\n\nNo repeated explanations.  \nNo pasted docs.  \nNo lost architectural knowledge.\n\nJust AI that already understands your system.\n\n⭐ If you believe AI should truly understand software projects, consider giving **Knowns** a star.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./images/task-workflow.gif\" alt=\"Knowns task workflow demo\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n## Table of Contents\n\n- [Why Knowns?](#why-knowns)\n- [What is Knowns?](#what-is-knowns---really)\n- [Core Capabilities](#core-capabilities)\n- [How It Works](#how-it-works)\n- [Installation](#installation)\n- [What You Can Build](#what-you-can-build-with-knowns)\n- [Quick Reference](#quick-reference)\n- [Claude Code Skills Workflow](#claude-code-skills-workflow)\n- [Documentation](#documentation)\n- [Roadmap](#roadmap)\n- [Development](#development)\n- [Links](#links)\n\n---\n\n## Why Knowns?\n\nAI is powerful — but fundamentally **stateless**.\n\nEvery session forces developers to:\n\n- Re-explain architecture\n- Paste documentation\n- Repeat conventions\n- Clarify past decisions\n- Rebuild context\n\nThis breaks flow and limits AI’s effectiveness.\n\n### AI doesn't lack intelligence.\n\n### It lacks the right context.\n\n**Knowns fixes that.**\n\n---\n\n## What is Knowns - Really?\n\nKnowns provides **persistent, structured project understanding** so AI can operate with full awareness of your software environment.\n\nThink of it as your project's **external brain**.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./images/knowledge-graph.svg\" alt=\"Knowns Knowledge Graph\" width=\"100%\"\u003e\n\u003c/p\u003e\n\nKnowns connects:\n\n- Specs\n- Tasks\n- Documentation\n- Decisions\n- Team knowledge\n\nSo AI doesn’t just generate code — it understands what it’s building.\n\n---\n\n## Core Capabilities\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./images/capabilities.svg\" alt=\"Knowns Core Capabilities\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n### 🧠 Persistent Project Memory\n\nGive AI long-term understanding of your codebase and workflows.\n\n### 🔗 Structured Knowledge\n\nConnect specs, tasks, and docs into a unified context layer.\n\n### ⚡ Smart Context Delivery\n\nAutomatically provide relevant context to AI — reducing noise and token usage.\n\n### 🤝 AI-Native Workflow\n\nTransform AI from a tool into a true engineering collaborator.\n\n### 🔐 Self-Hostable\n\nKeep your knowledge private and fully under your control.\n\n## What's New In v0.18.0\n\n- Workspace-aware browser mode: run `knowns browser` outside a repo, scan for projects, and switch workspaces from the UI without restarting the server.\n- AST code intelligence: index Go, TypeScript, JavaScript, and Python symbols with `knowns code ingest`, keep them fresh with `knowns code watch`, and inspect relationships with `knowns code search`, `knowns code deps`, and `knowns code symbols`.\n- Code graph support: the browser graph can now include indexed code nodes and dependency edges alongside tasks, docs, and memories.\n- Chat runtime upgrades: the chat UI includes stronger tool-output rendering, timeline/history navigation, and clearer OpenCode runtime status.\n\n---\n\n## How It Works\n\nKnowns sits **above your existing tools** and makes them readable by AI.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./images/architecture.svg\" alt=\"Knowns Architecture\" width=\"100%\"\u003e\n\u003c/p\u003e\n\nYour stack stays the same.\n\nBut now:\n\n- Specs → understood\n- Tasks → connected\n- Docs → usable\n- Decisions → remembered\n\nAI stops guessing — and starts contributing.\n\n---\n\n## Installation\n\n### Pre-built binaries\n\n```bash\n# Homebrew (macOS/Linux)\nbrew install knowns-dev/tap/knowns\n```\n\n```bash\n# Shell installer (macOS/Linux)\ncurl -fsSL https://knowns.sh/script/install | sh\n\n# Or with wget\nwget -qO- https://knowns.sh/script/install | sh\n\n# Install a specific version\ncurl -fsSL https://knowns.sh/script/install | KNOWNS_VERSION=0.18.0 sh\n```\n\n```powershell\n# PowerShell installer (Windows)\nirm https://knowns.sh/script/install.ps1 | iex\n\n# Install a specific version\n$env:KNOWNS_VERSION = \"0.18.0\"; irm https://knowns.sh/script/install.ps1 | iex\n```\n\nThe shell installer on macOS/Linux and the PowerShell installer on Windows both auto-run `knowns search --install-runtime` after installing the binary. If that step fails, rerun it manually.\n\n### Uninstall\n\n```bash\n# Shell uninstaller (macOS/Linux)\ncurl -fsSL https://knowns.sh/script/uninstall | sh\n```\n\n```powershell\n# PowerShell uninstaller (Windows)\nirm https://knowns.sh/script/uninstall.ps1 | iex\n```\n\nThe uninstall scripts only remove installed CLI binaries and PATH entries added by the installer. They leave project `.knowns/` folders untouched.\n\n```bash\n# npm — installs platform-specific binary automatically\nnpm install -g knowns\n\n# npx (no install)\nnpx knowns\n```\n\n### From source (Go 1.24.2+)\n\n```bash\n# Install to GOPATH/bin\ngo install github.com/howznguyen/knowns/cmd/knowns@latest\n\n# Or clone and build\ngit clone https://github.com/knowns-dev/knowns.git\ncd knowns\nmake build        # Output: bin/knowns\nmake install      # Install to GOPATH/bin\n```\n\n### Get started\n\n```bash\nknowns init\nknowns browser --open   # Start Web UI and open browser\n```\n\n---\n\n## What You Can Build With Knowns\n\n| Feature             | Description                                        |\n| ------------------- | -------------------------------------------------- |\n| **Task Management** | Create, track tasks with acceptance criteria       |\n| **Documentation**   | Nested folders with markdown + mermaid support     |\n| **Semantic Search** | Search by meaning with local AI models (offline)   |\n| **Time Tracking**   | Built-in timers and reports                        |\n| **Context Linking** | `@task-42` and `@doc/patterns/auth` references     |\n| **Validation**      | Check broken refs with `knowns validate`           |\n| **Template System** | Code generation with Handlebars (`.hbs`) templates |\n| **Import System**   | Import docs/templates from git, npm, or local      |\n| **Memory System**   | 3-layer memory (project/working/global) for AI recall |\n| **AI Integration**  | Full MCP Server with AC/plan/notes operations      |\n| **AI Workspaces**   | Multi-phase agent orchestration with live terminal |\n| **Code Intelligence** | AST indexing, code search, and dependency graph   |\n| **Web UI**          | Kanban board, doc browser, mermaid diagrams        |\n| **Knowledge Graph** | Visual graph of tasks, docs, memories, and optional code relationships |\n\n---\n\n## Quick Reference\n\n```bash\n# Tasks\nknowns task create \"Title\" -d \"Description\" --ac \"Criterion\"\nknowns task list --plain\nknowns task \u003cid\u003e --plain                    # View task (shorthand)\nknowns task edit \u003cid\u003e -s in-progress -a @me\nknowns task edit \u003cid\u003e --check-ac 1          # Mark AC as done\n\n# Documentation\nknowns doc create \"Title\" -d \"Description\" -f \"folder\"\nknowns doc \"doc-name\" --plain               # View doc (shorthand)\nknowns doc \"doc-name\" --smart --plain       # Auto-handle small/large docs\nknowns doc \"doc-name\" --section \"2\" --plain # Read specific section\n\n# Templates\nknowns template list                        # List available templates\nknowns template run \u003cname\u003e --name \"X\"       # Generate from template\nknowns template create \u003cname\u003e               # Create new template\n\n# Imports\nknowns import add \u003cname\u003e \u003csource\u003e           # Add import\nknowns import sync                          # Sync all imports\nknowns import list                          # List imports\n\n# Time, Search \u0026 Validate\nknowns time start \u003cid\u003e \u0026\u0026 knowns time stop\nknowns search \"query\" --plain\nknowns validate                             # Check broken refs\n\n# Code intelligence\nknowns code ingest\nknowns code search \"oauth login\" --neighbors 5\nknowns code deps --type calls\nknowns code symbols --kind function\n\n# AI Guidelines\nknowns agents --sync                        # Sync/generate instruction files\nknowns sync                                 # Sync skills + instruction files\n```\n\n---\n\n## Claude Code Skills Workflow\n\nWhen using Claude Code with Knowns, use skills (slash commands) for a guided workflow:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./images/workflow.svg\" alt=\"Knowns AI Workflow\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n```\n/kn-init     → Read project docs, understand context\n/kn-plan     → Take task, gather context, create plan (wait for approval)\n/kn-implement → Follow plan, check ACs, track progress\n/kn-commit   → Commit with conventional format\n```\n\n### Example Session\n\n```\nYou: /kn-init\nClaude: [Reads README, ARCHITECTURE, checks task backlog]\n        \"Project uses NestJS with CQRS pattern. 3 tasks in-progress...\"\n\nYou: /kn-plan 42\nClaude: [Takes task, reads refs, searches docs]\n        \"Task #42: Add user authentication\n\n         ## Implementation Plan\n         1. Review @doc/patterns/auth\n         2. Create AuthModule with JWT strategy\n         3. Add login/register endpoints\n         4. Write unit tests\n\n         Approve this plan?\"\n\nYou: Yes\n\nYou: /kn-implement 42\nClaude: [Follows plan, generates code, checks ACs]\n        \"✓ AC1: User can login - DONE\n         ✓ AC2: JWT token returned - DONE\n         ✓ AC3: Tests pass - DONE\n\n         All acceptance criteria complete. Ready to commit?\"\n\nYou: /kn-commit\nClaude: [Creates conventional commit]\n        \"feat(auth): add JWT authentication\n\n         - Add AuthModule with passport JWT strategy\n         - Add login/register endpoints\n         - Add unit tests (94% coverage)\"\n```\n\n### All Skills\n\n| Skill                | Description                                             |\n| -------------------- | ------------------------------------------------------- |\n| `/kn-init`           | Initialize session - read docs, load memory, understand project |\n| `/kn-plan \u003cid\u003e`      | Take task, gather context, create implementation plan           |\n| `/kn-implement \u003cid\u003e` | Execute plan, track progress, check acceptance criteria         |\n| `/kn-research`       | Search codebase, find patterns, explore before coding           |\n| `/kn-commit`         | Create conventional commit with verification                    |\n| `/kn-spec`           | Create specification document for features (SDD)                |\n| `/kn-go \u003cspec\u003e`      | Full pipeline from approved spec (no review gates)              |\n| `/kn-verify`         | Run SDD verification and coverage report                        |\n| `/kn-review`         | Multi-perspective code review (P1/P2/P3 severity)               |\n| `/kn-doc`            | Create or update documentation                                  |\n| `/kn-extract`        | Extract reusable patterns into docs, templates, and memory      |\n| `/kn-template`       | List, run, or create code templates                             |\n| `/kn-debug`          | Debug errors and failures with memory-backed triage             |\n\n---\n\n## Documentation\n\n| Guide                                          | Description                                |\n| ---------------------------------------------- | ------------------------------------------ |\n| [Command Reference](./docs/commands.md)        | All CLI commands with examples             |\n| [Workflow Guide](./docs/workflow.md)           | Task lifecycle from creation to completion |\n| [Reference System](./docs/reference-system.md) | How `@doc/` and `@task-` linking works     |\n| [Semantic Search](./docs/semantic-search.md)   | Setup and usage of AI-powered search       |\n| [Templates](./docs/templates.md)               | Code generation with Handlebars            |\n| [Web UI](./docs/web-ui.md)                     | Kanban board, doc browser, and knowledge graph |\n| [MCP Integration](./docs/mcp-integration.md)   | Claude Desktop setup with full MCP tools   |\n| [Configuration](./docs/configuration.md)       | Project structure and options              |\n| [Developer Guide](./docs/developer-guide.md)   | Technical docs for contributors            |\n| [User Guide](./docs/user-guide.md)             | Getting started and daily usage            |\n| [Multi-Platform](./docs/multi-platform.md)     | Cross-platform build and distribution      |\n\n---\n\n## Roadmap\n\n### AI Agent Workspaces ✅ (Active)\n\nMulti-phase agent orchestration — assign tasks to AI agents with git worktree isolation, live terminal streaming, and automatic phase progression (research → plan → implement → review).\n\n### Self-Hosted Team Sync 🚧 (Planned)\n\nOptional self-hosted sync server for shared visibility without giving up local-first workflows.\n\n- **Real-time visibility** — See who is working on what\n- **Shared knowledge** — Sync tasks and documentation across the team\n- **Full data control** — Self-hosted, no cloud dependency\n\n---\n\n## Development\n\nRequires **Go 1.24.2+** and optionally **Node.js + pnpm** for UI development.\n\n```bash\nmake build              # Build binary → bin/knowns\nmake dev                # Build with race detector\nmake test               # Run unit tests\nmake test-e2e           # Run CLI + MCP E2E tests\nmake test-e2e-semantic  # E2E tests including semantic search\nmake lint               # Run golangci-lint\nmake cross-compile      # Build for all 6 platforms\nmake ui                 # Rebuild embedded Web UI (requires pnpm)\n```\n\n### Project structure\n\n```\ncmd/knowns/          # CLI entry point\ninternal/\n  cli/               # Cobra commands\n  models/            # Domain models\n  storage/           # File-based storage (.knowns/)\n  server/            # HTTP server, SSE, WebSocket\n    routes/          # REST API handlers\n    workspace/       # Agent orchestrator, process manager, worktree\n  mcp/               # MCP server (stdio)\n  search/            # Semantic search (ONNX)\nui/                  # Embedded React UI (built assets)\ntests/               # E2E tests\n```\n\n## Links\n\n- [npm](https://www.npmjs.com/package/knowns)\n- [GitHub](https://github.com/knowns-dev/knowns)\n- [Discord](https://discord.knowns.dev)\n- [Changelog](./CHANGELOG.md)\n\nFor design principles and long-term direction, see [Philosophy](./PHILOSOPHY.md).\n\nFor technical details, see [Architecture](./ARCHITECTURE.md) and [Contributing](./CONTRIBUTING.md).\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eWhat your AI should have knowns.\u003c/strong\u003e\u003cbr\u003e\n  Built for dev teams who pair with AI.\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknowns-dev%2Fknowns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fknowns-dev%2Fknowns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknowns-dev%2Fknowns/lists"}