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.

• Local-first — All data stays in a local SQLite database. No cloud, no API keys.

• $0 cost — Embedding model runs locally. No per-query charges.

• Offline-capable — Full functionality without network access.

• MCP native — Works with Claude Desktop, Cursor, Claude Code out of the box.

Try it now (30 seconds)

npx @knowledgine/cli init --demo --path /tmp/knowledgine-demo
npx @knowledgine/cli search "React performance" --path /tmp/knowledgine-demo/knowledgine-demo-notes

Prerequisites

• Node.js >= 18.17.0 (managed via Volta or fnm recommended)

• 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. The Database section now also includes a per-category storage breakdown (notes, fts, embeddings, graph, events, memory, other, plus freelist and wal when non-zero) so it is easy to see which subsystem dominates the on-disk footprint.

search

knowledgine search "React performance" --path ./my-notes
knowledgine search "architecture decisions" --mode semantic --path ./my-notes
knowledgine search "debugging tips" --mode hybrid --path ./my-notes --format table

• --mode <mode>: Search mode (keyword, semantic, hybrid). Default: keyword

• --format <format>: Output format (plain, table, json). Default: plain

• --limit <n>: Maximum results. Default: 20

• --related <noteId>: Find related notes by note ID

• --demo: Search in demo notes

• --projects <names-or-paths>: Search across multiple knowledgine projects (comma-separated). See Cross-Project Search below.

Cross-Project Search

Search across multiple knowledgine projects in a single query. Results are ranked by FTS5 score (descending). At most 10 projects are searched per query (any extras are dropped with a stderr warning). Project databases are opened sequentially, not in parallel.

You can pass either registered names from .knowledginerc (when configured) or absolute / relative / ~/ paths directly:

# Registered names from .knowledginerc
knowledgine search "auth flow" --projects backend,frontend

# Dynamic paths — no rc registration required
knowledgine search "auth flow" --projects ~/work/<your-repo>,./sibling-repo

# Mixed
knowledgine search "auth flow" --projects backend,/absolute/path/to/repo

Path detection: an argument is treated as a path if it begins with /, ./, ../, ~/, or .. Otherwise it is looked up as a registered project name. When path-detected, registered name lookup is skipped (paths take precedence).

.knowledginerc example:

{
  "projects": [
    { "name": "backend", "path": "/Users/me/code/backend" },
    { "name": "frontend", "path": "/Users/me/code/frontend" },
  ],
}

When to use which:

• Registered names when paths are stable, shared across team members, or you want short CLI invocations.

• Dynamic paths for ad-hoc exploration, CI/scripts with computed paths, or one-off cross-project queries without modifying .knowledginerc.

Constraints:

• Each target project must contain .knowledgine/index.sqlite with schema_version >= 8. When at least one project resolves, any path that lacks the database file is skipped with a stderr warning and the search continues. When none of the supplied entries resolves, the command exits with status 1 and a Case A/B/C/D error message explaining what was wrong.

• Identical basenames across paths produce ambiguous projectName in output; use registered names in .knowledginerc to disambiguate.

• Glob patterns, remote URLs, and dynamic-path support via the MCP server's search_knowledge tool are out of scope (future tickets).

capture

knowledgine capture add "TIL: Use React.memo for expensive components" --path ./my-notes
knowledgine capture add --url https://example.com/article --path ./my-notes
knowledgine capture list --path ./my-notes
knowledgine capture delete <id> --path ./my-notes

ingest

knowledgine ingest --source markdown --path ./my-notes
knowledgine ingest --source github --repo owner/repo --path ./my-notes
knowledgine ingest --source claude-sessions --path ./my-notes
knowledgine ingest --source cline-sessions --path ./my-notes
knowledgine ingest --all --path ./my-notes

# Run the Observer/Reflector agents after ingestion to extract patterns,
# entities and a 6-vector classification. Optional opt-in.
# See docs/agents/observer.md for details.
knowledgine ingest --source markdown --observe --path ./my-notes
knowledgine ingest --source markdown --observe --observe-limit 200 --path ./my-notes

Comparison

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/ingest
└── @knowledgine/core

Configuration

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

.knowledginerc.json

Create a .knowledginerc.json file in your project root for persistent configuration:

{
  "semantic": true,
  "defaultPath": "./my-notes"
}

When defaultPath is set, the --path option can be omitted from all commands (init, start, search, ingest, etc.). knowledgine init automatically writes defaultPath to .knowledginerc.json after the first run.

Troubleshooting

# macOS
xcode-select --install

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

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

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

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

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

Community

• Bug Reports

• Feature Requests

• Discussions

• Contributing

License

MIT — see LICENSE for details.