knowmindknowmind
DokumentationQuickstartAnbindungReferenzFehlerbehebung
DEEN
knowmindknowmind
DocumentationQuickstartIntegrationsReferenceTroubleshooting
DEEN

Integration

Command line

The knowmind command line opens a connection to your workspace from any terminal. It handles sign-in, search and upload, and provides a local MCP bridge for MCP-capable tools such as Claude Code or Cursor.

Audience
Power users and developers who drive knowmind from scripts, pipelines or local MCP clients. Not required for browser-only use.

Prerequisites

  • Node.js 20 or newer (check: node --version)
  • knowmind account with an API token of the form kmt_… — API/CLI access is available on every plan, including the free Privat tier
  • Write permission in your home directory for the token file at ~/.knowmind/config.json

Steps

  1. 1

    Install from the npm registry

    bash
    npm install -g knowmind

    The knowmind command is then available system-wide. Run knowmind --version to see the installed version; the npm registry changelog tracks the latest release.

    Note

    What does this command download?

    Only the command line itself — a small Apache 2.0 licensed binary. No customer content, no memories, no credentials. Content from knowmind workspaces is only available after the sign-in in step 2.

    Outcome: knowmind --version returns a version string.

  2. 2

    Sign in with an API token

    In the knowmind dashboard, under API Tokens, create a token with scope read for read-only access or also write to create and maintain content. Copy the token once.

    bash
    # From version 0.1.25: set token and endpoint
knowmind init --token kmt_… --api https://knowmind.de

# Still a valid alternative
knowmind login --token kmt_…

    The token is saved to ~/.knowmind/config.json with restricted permissions (chmod 600 on Unix). Alternatively pass it through the KNOWMIND_TOKEN environment variable — useful in CI pipelines.

    Outcome: knowmind health returns the service status and a version string.

  3. 3

    Wire it into your IDE

    From version 0.1.23, knowmind install <ide> wires knowmind directly into a supported IDE — it writes the matching MCP configuration so you do not have to author it by hand.

    bash
    npx -y knowmind install <ide>   # e.g. claude-code, cursor, vscode

    Outcome: The IDE lists knowmind as a connected MCP server.

  4. 4

    Commands

    bash
    # Search
knowmind search "When does the Müller GmbH contract expire?"
knowmind search "GDPR training" -k 10 --hops 3

# Create a memory
echo "Short note" | knowmind upload - --title "Keyword"
knowmind upload ./handbook.md --title "Service Handbook"

# Sync content (idempotent, content-hash based)
knowmind sync ./docs --manifest ./.knowmind.manifest

# Status and maintenance
knowmind stats        # number of memories and relations
knowmind health       # service reachability
knowmind status       # heartbeat: reachable, count, response time
knowmind config       # current token prefix and endpoint

    Outcome: On success every command returns exit code 0 and writes the result to stdout.

  5. 5

    Status indicator in your AI tool

    knowmind status --lineprints a single-line status indicator you can wire into your AI tool's status bar. It shows knowmind as a green lamp: steady green when reachable, a green flicker like a hard-drive light while knowmind is working, and red on an outage. The indicator reads from a short-lived cache and never blocks the tool.

    For Claude Code, knowmind init --client claude-code wires up the status bar automatically. An existing custom status bar is left untouched — in that case add the command yourself:

    json
    {
  "statusLine": { "type": "command", "command": "knowmind status --line" }
}

    Outcome: The status bar shows knowmind's state continuously and flickers green whenever the memory is queried.

  6. 6

    Use as an MCP bridge

    If an AI tool supports the Model Context Protocol over stdio (Claude Code, Claude Desktop, Cursor), the CLI can serve as a local bridge. The token stays in the CLI configuration — the AI tool never sees it.

    json
    {
  "mcpServers": {
    "knowmind": {
      "command": "knowmind",
      "args": ["mcp"]
    }
  }
}

    Tool-specific guides: Claude Code, Claude Desktop and Cursor.

Verify the result

The CLI is ready when all three conditions hold:

  • knowmind health returns status: ok.
  • knowmind stats shows the memory and relation count.
  • knowmind search "your question" returns hits from the corpus.

Troubleshooting

Error messageCauseResolution
command not found: knowmindnpm global directory not on PATH.Find the path with npm config get prefix and add it to PATH. On Windows: PowerShell profile or environment variable dialog.
EACCES on npm install -gGlobal directory needs administrator rights.Either install with elevated rights (sudo / "Run as administrator"), or point npm prefix at a user-owned directory: npm config set prefix ~/.npm-global.
knowmind login: token rejectedToken revoked in the dashboard or a copy-paste typo.Create a new token in the dashboard and retry. Watch for surrounding whitespace when copying.
knowmind sync: reports missing permissionToken scope is read only, not write.Edit the token in the dashboard and add scope "write", or create a new token with both scopes.

Related