knowmindknowmind
DokumentationQuickstartAnbindungReferenzFehlerbehebung
DEEN
knowmindknowmind
DocumentationQuickstartIntegrationsReferenceTroubleshooting
DEEN

Tasks

Set up automatic maintenance

For knowmind to grow valuable over time, the AI has to query it regularly and write new insights back. This guide shows three levers — from a fully automatic default with no setup to a hard guarantee via hooks.

Audience
Anyone connecting an AI tool (Claude Code, Claude Desktop, Cursor, ChatGPT or a custom agent) to knowmind permanently who wants the AI to maintain the memory on its own — without being reminded every time.

Prerequisites

  • knowmind connected as an MCP server (see your client's integration guide)
  • For lever 2 (knowmind init): knowmind CLI installed and logged in, Node.js 20 or newer
  • For lever 2 with Claude Code: a project folder with .claude/ (created if absent)

The three levers

LeverSetupEffect
MCP instructionsnone — works automaticallyUniversal across every MCP client. Soft: the model follows the instruction, it is not enforced.
knowmind initone command per projectHard, but only in clients with a hook mechanism (e.g. Claude Code). Enforces recall and prompts for saving.
MCP promptsnone — available as slash commandsManual: you invoke them when needed (e.g. /knowmind status).

Steps

  1. 1

    Lever 1: MCP instructions — no setup

    As soon as your client connects to the knowmind MCP server, the server sends an instructions field during the handshake (initialize). The client places that text into the model's system context. It contains the memory-first rule: recall first with knowmind_recall, then answer, and save new insights with knowmind_store_memory.

    This is fully automatic. You configure nothing. The knowmind CLI proxy (variant A of the Claude Code integration) also passes the server's instructions through to the client.

    Outcome: In every new conversation the model takes the rule into account — it calls knowmind_recall more often on its own for factual questions and offers to store insights.

  2. 2

    Lever 2: knowmind init — hard hooks per project

    In clients with a hook mechanism — Claude Code first and foremost — a single command sets up maintenance as a binding rule:

    bash
    # Run inside the project folder
knowmind init

# Preview what would happen without writing anything
knowmind init --dry-run

# Choose the client explicitly (otherwise auto-detected)
knowmind init --client claude-code

    The command detects the client and creates:

    • Claude Code: a UserPromptSubmit hook (calls knowmind_recall before real questions and injects the hits) and a Stop hook (reminds you to save when the turn contained something worth keeping), both registered in .claude/settings.json; plus a memory-first block in CLAUDE.md.
    • Cursor: a rule .cursor/rules/knowmind.mdc with alwaysApply.
    • Generic / Claude Desktop / Codex: prints the memory-first block for manual insertion (no hook mechanism available).

    The command is idempotent (a second run creates no duplicates; inserted blocks carry BEGIN/END markers) and non-destructive (foreign files without a knowmind marker are never overwritten).

    Outcome: knowmind init lists every action with a symbol (+ new, ~ changed, = unchanged, ! skipped). After restarting the client the hooks take effect.

  3. 3

    Lever 3: MCP prompts as slash commands

    The knowmind MCP server provides predefined prompts that appear as slash commands in your client — in Claude Code, for example, as /mcp__knowmind__recall. Invoke them manually to trigger a maintenance action on demand:

    • status — health check plus corpus statistics for the workspace.
    • recall — hybrid recall: pulls the best matches for a question before you continue.
    • store — creates a new memory (title + content).
    • relations — lists the relationships of a memory in the knowledge graph.
    • recall_at_time — point-in-time recall: what did the workspace know on a given date?

    Outcome: The prompts show up in your client's slash-command or prompt picker and trigger the matching tool call.

Note

Honest limit: what can be hard-enforced and what cannot

The MCP instructions (lever 1) are a soft, model-dependent lever — the client hands them to the model, but no client enforces a specific behavior with them. A hard guarantee comes only from a hook mechanism (lever 2), and not every client has one: in Claude Desktop and ChatGPT, for instance, only levers 1 and 3 apply, nothing is technically enforceable there. For those clients the memory-first block in the custom instructions is the closest available approximation.

Verify the result

Automatic maintenance is working when:

  • A factual question in the chat leads to a visible knowmind_recall call without you asking for it.
  • After a turn with new insights, the AI offers to save them — or does so when prompted by the gate if the Stop hook is active.
  • For Claude Code: knowmind init created two hook entries in .claude/settings.json, and .claude/hooks/ contains knowmind_recall.mjs and knowmind_capture.mjs.
  • knowmind stats shows a rising memory count over time.

Troubleshooting

Error messageCauseResolution
AI does not call knowmind_recall on its ownInstructions are soft; the model judges relevance per turn. With some models/clients the rule fires less often.Set up the hard hook with knowmind init (lever 2) if the client supports it. Otherwise ask explicitly: “Search knowmind first for …”.
knowmind init: file exists without knowmind markerA target file (e.g. your own hook script) already exists but carries no knowmind marker. It is not overwritten for safety.The message is expected behavior. Add the knowmind entry manually if needed, or rename the foreign file and run knowmind init again.
settings.json is not valid JSONThe existing .claude/settings.json cannot be parsed — init leaves it untouched.Fix the JSON error in .claude/settings.json, then run knowmind init again.
Hooks do not take effect after knowmind initThe client loads hooks only at startup.Restart the AI client. For Claude Code, start a new session.

Related