knowit

# Knowit — shared, structured memory for AI coding agents **Your agent forgets everything between sessions. Knowit fixes that.** [](https://www.npmjs.com/package/knowit) [](https://www.npmjs.com/package/knowit) [](LICENSE) [](https://github.com/ismaelkedir/knowit) Knowit is an open-source MCP server + CLI that gives AI coding agents a persistent, queryable project memory — shared across sessions, across teammates, and across every MCP client: Claude Code, Codex, Cursor, Windsurf, VS Code/Copilot, Gemini CLI, Kiro, Cline, Continue, Zed, and JetBrains AI Assistant. Store architecture rules, decisions, and conventions once. Every agent retrieves the relevant context before it plans or edits code — no more re-explaining your codebase every session. ```bash npx knowit install ``` That's it. The wizard configures your MCP clients and initializes a local, git-friendly memory store at `.knowit/knowledge.jsonl`. 🌐 **Website:** [useknowit.dev](https://useknowit.dev) · 📚 **Docs:** [useknowit.dev/docs](https://useknowit.dev/docs) <!-- TODO: hero screenshot of `knowit preview` — docs/assets/preview-hero.png --> ## Why Knowit (and not another memory tool) | | CLAUDE.md / rule files | Generic memory MCPs | **Knowit** | |---|---|---|---| | Survives across sessions | ✅ | ✅ | ✅ | | Structured (types, scopes, confidence) | ❌ free-form text | ❌ blob notes | ✅ rules, decisions, patterns, conventions | | Retrieved per task, not dumped into every prompt | ❌ always in context | ⚠️ varies | ✅ `resolve_context` returns only what matters | | Shared with teammates via git | ⚠️ merge-conflict sprawl | ❌ | ✅ line-delimited JSONL, clean diffs | | Works across every MCP agent | ❌ per-tool files | ⚠️ varies | ✅ 11+ clients, one memory | | Local-first, no hosted dependency | ✅ | ❌ often cloud | ✅ your repo, your data | | Browse/audit what agents remember | ❌ | ❌ | ✅ `npx knowit preview` | ## Contents - [Why Knowit (and not another memory tool)](#why-knowit-and-not-another-memory-tool) - [Why Structured Memory](#why-structured-memory) - [Install](#install) - [Quick Start](#quick-start) - [How It Works](#how-it-works) - [Memory Browser (`knowit preview`)](#memory-browser-knowit-preview) - [Common Use Cases](#common-use-cases) - [CLI](#cli) - [MCP Tools](#mcp-tools) - [Knowledge Model](#knowledge-model) - [Shared Team Memory](#shared-team-memory) - [Semantic Search](#semantic-search) - [Notion Integration](#notion-integration) - [Configuration](#configuration) - [Automatic Update Notifications](#automatic-update-notifications) - [Public Launch Note](#public-launch-note) - [Contributing](#contributing) - [License](#license) ## Why Structured Memory Knowit is designed for operational engineering memory: the durable context agents need while doing code work. That means memory is stored with structure such as: - entry type: `rule`, `architecture`, `pattern`, `decision`, `convention`, `note` - scope: `global`, `team`, `repo`, `domain` - metadata: tags, URLs, confidence, and source information - renderable body blocks: headings, paragraphs, lists, quotes, code, callouts, and link lists This makes it easier for agents to retrieve only the context that matters for the current task, such as: - repo-specific architecture rules before implementing a feature - domain-specific conventions before refactoring a subsystem - team-wide decisions before introducing a new pattern The default project storage is `.knowit/knowledge.jsonl`, a line-delimited JSON file that is readable, reviewable, and friendly to git diffs. Global and custom storage scopes can still use SQLite when you want a private local database or a shared database path. ## Install ```bash npx knowit install ``` Requires Node.js 20+. No global install needed — the wizard runs via `npx` and can install knowit globally for you if you want faster future starts. Knowit's CLI also checks for newer published versions and shows a non-blocking update notice in interactive terminal sessions. ## Quick Start ### 1. Install Knowit into a project ```bash npx knowit install ``` `npx knowit install` is the main setup flow. It can: - initialize the local memory store - register or write the Knowit MCP server configuration for supported clients - update agent instruction files - connect a preferred source - optionally migrate architecture or ADR-style markdown into Knowit This repository intentionally keeps a checked-in `.mcp.json` so Knowit can use itself while developing Knowit. For normal consumer projects, prefer generating MCP config through `knowit install`. ### 2. Tell your agent to use it If you are not using the installer-managed instructions, add this to the client instruction file such as `AGENTS.md`, `CLAUDE.md`, or `.github/copilot-instructions.md`: ```md ## Memory This project uses Knowit as the default persistent knowledge base for AI coding agents. - Before planning or implementing, call `resolve_context` with the task description and repo name. - After finishing a task, call `capture_session_learnings` to store durable rules, decisions, and patterns. - Prefer Knowit over repo-local markdown memory files unless the user explicitly asks for a file. ``` ### MCP client support Knowit uses `npx -y knowit@latest serve` for generated MCP configs when the `knowit` binary is not installed globally. Project installs do not set `KNOWIT_DB_PATH`; they rely on the client working directory and the project-local `.knowit/knowledge.jsonl` store. | Client | Installer behavior | MCP config requirement | |---|---|---| | Claude Code | Runs `claude mcp add` | CLI-managed MCP config | | Codex | Runs `codex mcp add` | CLI-managed MCP config | | Cursor | Writes `.cursor/mcp.json` for project scope or `~/.cursor/mcp.json` for global scope | JSON with `mcpServers` | | Windsurf | Writes `~/.codeium/windsurf/mcp_config.json` | JSON with `mcpServers` | | VS Code / GitHub Copilot | Writes `.vscode/mcp.json` for project scope | JSON with `servers` | | Gemini CLI | Writes `.gemini/settings.json` for project scope or `~/.gemini/settings.json` for global scope | JSON with `mcpServers` | | Kiro | Writes `.kiro/settings/mcp.json` for project scope or `~/.kiro/settings/mcp.json` for global scope | JSON with `mcpServers` | | Cline | Writes `~/.cline/data/settings/cline_mcp_settings.json` | JSON with `mcpServers` | | Continue | Writes `.continue/mcpServers/knowit.yaml` for project scope | YAML MCP block | | Zed | Writes `~/.config/zed/settings.json` | JSON with `context_servers` | | JetBrains AI Assistant | Updates instructions only and prints a warning | Add the generated JSON through Settings > Tools > AI Assistant > Model Context Protocol | ### 3. Start storing and retrieving context ```bash knowit add rule "No direct DB access from controllers" \ "All database access goes through repository classes." \ --scope repo --repo api-gateway --tags architecture,layers knowit resolve "implement user authentication" --repo api-gateway --domain auth ``` ## How It Works Agents interact with Knowit through MCP tools: 1. Before work, the agent calls `resolve_context`. 2. During work, it can search or store targeted knowledge. 3. After work, it calls `capture_session_learnings`. That keeps source code in the repo and long-lived project memory in Knowit. In practice, Knowit is a layer for execution context: - canonical source code stays in the repository - durable engineering memory stays in Knowit - external canonical docs can stay in tools like Notion, with Knowit routing agents to the right source when needed ## Memory Browser (`knowit preview`) See exactly what your agents remember: ```bash npx knowit preview ``` This opens a local, read-only web UI (default `127.0.0.1:4077`) for browsing your knowledge base: - filter by text, entry type, repo, domain, or tag - two-pane list + detail view with rendered body blocks (headings, code, callouts, links) - entry metadata: type, scope, confidence, last updated - automatic light/dark theme, full keyboard navigation - strictly read-only — nothing can be modified from the browser <!-- TODO: screenshot — docs/assets/preview-light.png / preview-dark.png --> Useful for auditing what agents have stored, reviewing team memory before committing `.knowit/knowledge.jsonl`, and demoing the knowledge base. ## Common Use Cases - Store coding rules that agents must follow. - Preserve architecture decisions and tradeoffs. - Capture reusable implementation patterns. - Keep durable memory out of scattered prompts, session history, and ad hoc note files. - Replace repo-local memory sprawl such as extra `ARCHITECTURE.md`, ADR, and process notes. - Share team conventions through one shared SQLite database path. ## CLI ```bash # Setup npx knowit install knowit install # if already installed globally knowit init # Add and search knowledge knowit add rule "Use repository classes" "No direct DB access from controllers." knowit search "repository pattern" knowit resolve "add webhook retry handling" --repo api-gateway --domain billing # Browse entries knowit list --repo api-gateway knowit show <entry-id> knowit stats knowit preview # local web UI for browsing memory # Sources knowit source list knowit source connect notion knowit source show notion # Cloud account commands knowit cloud login --token <token> knowit cloud whoami knowit cloud logout # Import existing markdown knowledge knowit import-md --yes # Convert an existing project SQLite database to JSONL knowit migrate-storage --sqlite-path .knowit/knowit.db --dry-run knowit migrate-storage --sqlite-path .knowit/knowit.db ``` ## MCP Tools | Tool | Purpose | |---|---| | `resolve_context` | Retrieve relevant knowledge before planning a task (returns titles/summaries — tiered retrieval phase 1) | | `get_knowledge` | Fetch full content for entries by ID after `resolve_context` or `search_knowledge` (tiered retrieval phase 2) | | `store_knowledge` | Store one knowledge entry | | `capture_session_learnings` | Batch-store session learnings with deduplication | | `search_knowledge` | Search across one or more sources | | `resolve_source_action` | Decide whether to use Knowit directly or route to another provider | | `connect_source` | Connect a known provider such as `local` or `notion` | | `list_sources` | List configured sources | | `register_mcp_source` | Register an external MCP server as a Knowit source with explicit tool mappings | ## Knowledge Model ### Entry types | Type | Use for | |---|---| | `rule` | Hard constraints the codebase should enforce | | `architecture` | System structure and rationale | | `pattern` | Reusable implementation approaches | | `decision` | Decision records and tradeoffs | | `convention` | Naming, formatting, and style agreements | | `note` | Observations, caveats, and open questions | ### Scopes | Scope | Use for | |---|---| | `global` | Applies everywhere | | `team` | Applies across multiple repos | | `repo` | Specific to one repository | | `domain` | Specific to a bounded area in one repo | Entries also support tags, optional URLs, metadata, confidence scores, and a structured `body` field for reader UIs. `content` remains the plain searchable text; `body` is the renderable version. When `body` is omitted, Knowit derives paragraph blocks from `content`. ## Shared Team Memory Knowit is local-first. In project scope, `.knowit/knowledge.jsonl` is the canonical memory file and can be reviewed in version control like source code. Existing projects with `.knowit/knowit.db` are migrated automatically on first project-scope initialization when `.knowit/knowledge.jsonl` does not exist. You can also run the conversion explicitly: ```bash knowit migrate-storage --sqlite-path .knowit/knowit.db --dry-run knowit migrate-storage --sqlite-path .knowit/knowit.db ``` The command writes `.knowit/knowledge.jsonl` and `.knowit/sources.json`. It refuses to overwrite existing targets unless you pass `--force`. For private global memory or a shared database outside the repo, point everyone at the same SQLite database path. ```bash KNOWIT_DB_PATH=/shared/team/knowit.db npx knowit install --scope global --client claude ``` That gives every developer and every agent the same durable memory source without adding a hosted dependency. ## Semantic Search If you set `OPENAI_API_KEY`, Knowit adds embeddings-backed semantic search. Without it, Knowit still works with text and tag matching. ```bash export OPENAI_API_KEY=sk-... knowit search "how do we handle payment retries" ``` ## Notion Integration Knowit can connect to Notion as an external source and route agents to the right MCP flow when durable docs belong there. ```bash knowit source connect notion ``` ## Configuration | Variable | Description | |---|---| | `KNOWIT_DB_PATH` | Path to the SQLite database for `global` or `custom` storage | | `KNOWIT_STORAGE_SCOPE` | `project`, `global`, or `custom` | | `OPENAI_API_KEY` | Enables semantic search via embeddings | | `KNOWIT_LOG_LEVEL` | `debug`, `info`, `warn`, or `error` | ### Default storage locations | Scope | Path | |---|---| | `project` | `.knowit/knowledge.jsonl` inside the current repo | | `global` | `~/.knowit/knowit.db` | | `custom` | Value of `KNOWIT_DB_PATH` | ## Automatic Update Notifications Knowit's interactive CLI commands use [`update-notifier`](https://www.npmjs.com/package/update-notifier) to let users know when a newer npm release is available. - Notifications are skipped for `knowit serve` so MCP stdio traffic stays clean. - Notifications are also skipped in CI, tests, and non-interactive terminal sessions. - Users can disable them with `NO_UPDATE_NOTIFIER=1` or by passing `--no-update-notifier`. ## Public Launch Note The current public release is focused on the open-source, local-first workflow. Hosted cloud plans are not publicly enabled right now. ## Contributing Issues, README improvements, bug reports, feature requests, and pull requests are welcome. - Repo: [github.com/ismaelkedir/knowit](https://github.com/ismaelkedir/knowit) - Issues: [github.com/ismaelkedir/knowit/issues](https://github.com/ismaelkedir/knowit/issues) - Discussions: [github.com/ismaelkedir/knowit/discussions](https://github.com/ismaelkedir/knowit/discussions) - Contributing guide: [CONTRIBUTING.md](CONTRIBUTING.md) - Code of conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - Security policy: [SECURITY.md](SECURITY.md) If you are trying Knowit in a real project, feedback about agent workflows, missing MCP tools, and setup friction is especially useful. ## License MIT. See [LICENSE](LICENSE).