Knowit — shared, structured memory for AI coding agents

Your agent forgets everything between sessions. Knowit fixes that.

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.

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 · 📚 Docs: useknowit.dev/docs

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 Structured Memory
• Install
• Quick Start
• How It Works
• Memory Browser (knowit preview)
• Common Use Cases
• CLI
• MCP Tools
• Knowledge Model
• Shared Team Memory
• Semantic Search
• Notion Integration
• Configuration
• Automatic Update Notifications
• Public Launch Note
• Contributing
• 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

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

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:

## 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

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:

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

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

# 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:

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.

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.

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.

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 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
• Issues: github.com/ismaelkedir/knowit/issues
• Discussions: github.com/ismaelkedir/knowit/discussions
• Contributing guide: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md
• Security policy: 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.