knowledgine

Developer Knowledge Infrastructure — extract structured knowledge from your markdown notes for AI coding tools.

日本語

Why knowledgine?

Developers accumulate valuable knowledge in markdown notes — debugging sessions, architectural decisions, problem-solution pairs, and hard-won lessons. That knowledge stays siloed in files, invisible to AI coding assistants.

knowledgine bridges that gap. It scans your markdown files, detects patterns (problem-solution pairs, code snippets, learnings), and stores them in a local SQLite database with FTS5 full-text search. An MCP server exposes that knowledge to any MCP-compatible AI tool, so your assistant can retrieve the right context exactly when you need it.

Prerequisites

• Node.js >= 18.17.0
• pnpm >= 9 (for contributing / local builds)
• Native build tools for better-sqlite3:
  • macOS: xcode-select --install
  • Linux (Ubuntu/Debian): sudo apt-get install build-essential python3
  • Windows: npm install --global windows-build-tools

Quick Start

Three steps from install to working MCP integration.

1. Install

npm install -g @knowledgine/cli

2. Index your notes

knowledgine init --path ./my-notes

This scans all markdown files and builds .knowledgine/index.sqlite with FTS5 full-text search. No model download required.

To enable semantic search (optional, downloads ~23MB model):

knowledgine init --path ./my-notes --semantic
# or upgrade an existing index:
knowledgine upgrade --semantic --path ./my-notes

3. Connect your AI tool

knowledgine setup --target claude-desktop --path ./my-notes

This generates the MCP configuration for your AI tool. Add --write to write it directly:

knowledgine setup --target claude-desktop --path ./my-notes --write

Restart your AI tool to activate. Verify with:

knowledgine status --path ./my-notes

Commands

init

knowledgine init --path ./my-notes
knowledgine init --path ./my-notes --semantic

• --path <dir>: Root directory to scan (default: current directory)
• --semantic: Enable semantic search (downloads embedding model and generates embeddings)

upgrade

knowledgine upgrade --semantic --path ./my-notes

• --semantic: Download embedding model and generate embeddings for all indexed notes
• --path <dir>: Root directory (default: current directory)

setup

knowledgine setup --target claude-desktop --path ./my-notes
knowledgine setup --target cursor --path ./my-notes --write

• --target <tool>: Target AI tool (claude-desktop, cursor)
• --path <dir>: Root directory of indexed notes
• --write: Write configuration to file (default: dry-run, shows config only)

status

knowledgine status --path ./my-notes

Shows database stats, model availability, MCP configuration status, and overall readiness.

MCP Tools

Once connected, the following tools are available to your AI assistant.

MCP Client Setup

Claude Desktop

Use knowledgine setup for automatic configuration, or manually add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or ~/.config/claude/claude_desktop_config.json (Linux):

{
  "mcpServers": {
    "knowledgine": {
      "command": "npx",
      "args": ["-y", "@knowledgine/cli", "start", "--path", "/path/to/notes"]
    }
  }
}

Cursor

Use knowledgine setup --target cursor for automatic configuration, or manually add to .cursor/mcp.json in your project root (recommended) or ~/.cursor/mcp.json for global use.

Using ${workspaceFolder} to automatically point to the current project:

{
  "mcpServers": {
    "knowledgine": {
      "command": "npx",
      "args": ["@knowledgine/cli", "start"],
      "env": {
        "KNOWLEDGINE_ROOT_PATH": "${workspaceFolder}"
      }
    }
  }
}

For detailed setup instructions, variable expansion reference, and troubleshooting, see the Cursor Setup Guide.

Architecture

@knowledgine/cli
├── @knowledgine/mcp-server
│   └── @knowledgine/core
└── @knowledgine/core

Configuration

knowledgine uses sensible defaults. You can override them by passing options to init or start, or by editing the generated config.

Troubleshooting

Native build failure (better-sqlite3)

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt-get install build-essential python3

# Windows
npm install --global windows-build-tools

Embedding model download failure

If init --semantic or upgrade --semantic fails to download the model, text search (FTS5) still works. Retry with:

knowledgine upgrade --semantic --path ./my-notes

MCP connection issues

1. Verify setup: knowledgine status --path ./my-notes
2. Re-generate config: knowledgine setup --target claude-desktop --path ./my-notes --write
3. Restart your AI tool after writing the config
4. Check that the path in the config matches your notes directory

Feedback

We'd love to hear from you:

• Bug reports: Open an issue
• Feature requests: Open an issue
• Questions & discussions: GitHub Discussions

Contributing

See CONTRIBUTING.md for development setup, commit conventions, and pull request guidelines.

License

MIT — see LICENSE for details.