# Knowit — shared, structured memory for AI coding agents

**Your agent forgets everything between sessions. Knowit fixes that.**

[![npm version](https://img.shields.io/npm/v/knowit)](https://www.npmjs.com/package/knowit)
[![npm downloads](https://img.shields.io/npm/dm/knowit)](https://www.npmjs.com/package/knowit)
[![license](https://img.shields.io/github/license/ismaelkedir/knowit)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/ismaelkedir/knowit?style=social)](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).