settings

Agent Settings

View and modify the agent's configuration stored in agent-config.json.

Show current settings

If no argument given, read and display agent-config.json:

cat ${CLAUDE_PLUGIN_ROOT}/agent-config.json 2>/dev/null || echo '(no config — using defaults)'

Show defaults:

• Memory backend: builtin (SQLite + FTS5 + BM25 + temporal decay + MMR)
• Citations: auto
• Temporal decay: enabled (half-life 30 days)
• MMR: enabled (lambda 0.7)
• Heartbeat: every 30 min, active hours 08:00-23:00
• Dreaming: nightly at 3 AM

Available settings

Memory backend: builtin or qmd

builtin (default):

• SQLite + FTS5 full-text search with BM25 ranking
• Temporal decay for dated files (older = less relevant)
• MMR diversity re-ranking
• Works out of the box, no external tools needed

qmd (enhanced):

• External tool by @tobi: https://github.com/tobi/qmd
• Local embeddings via node-llama-cpp (no API keys needed)
• Vector search with semantic understanding
• Reranking for better result quality
• Requires qmd binary installed

Setting up QMD

1. Check if qmd is installed:

``bash qmd --version 2>/dev/null && echo "QMD available" || echo "QMD not found" ``

1. If not installed, guide the user:

``` Install QMD (local-first search tool, no API keys needed):

bun install -g qmd # or download from https://github.com/tobi/qmd/releases ```

1. Configure the backend:

Write agent-config.json via Bash (NOT the Write tool — agent-config.json is on the always-on protected-paths list; direct Write is refused with exec-gate: write to protected path refused (workspace-agent-config)).

Step 3a — Read current config with the Read tool: Read("agent-config.json"). If it doesn't exist, treat as {}.

Step 3b — Merge in-memory in your reasoning: take the existing object, replace the memory key with the QMD block: ``json { "memory": { "backend": "qmd", "citations": "auto", "qmd": { "searchMode": "vsearch", "includeDefaultMemory": true, "limits": { "maxResults": 6, "timeoutMs": 15000 } } } } `` Preserve every other top-level key from the existing config.

Step 3c — Write the full merged object via Bash heredoc with validate + atomic mv (substitute <FULL_MERGED_JSON> with the JSON literal from your reasoning): `` Bash('cat > agent-config.json.tmp << "JSON_EOF" && <FULL_MERGED_JSON> JSON_EOF node -e \'JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"))\' agent-config.json.tmp \ && mv agent-config.json.tmp agent-config.json \ && echo "wrote agent-config.json" \ || { rm -f agent-config.json.tmp; echo "ABORTED: invalid JSON or filesystem error"; exit 1; }') ``

The user gets ONE Bash permission prompt. By design — agent-config.json controls security-sensitive settings, so writes go through deliberate user consent. The "JSON_EOF" (double-quoted delimiter) form disables shell expansion inside the body, so any literal $ or backtick in the JSON stays untouched. cat > ... << "JSON_EOF" && puts the heredoc write itself in the && chain so a cat failure short-circuits the rest (otherwise a cat that fails to open the tmp file would leave any pre-existing tmp content intact, node would validate stale content, and mv would clobber the destination with old data). The node -e 'JSON.parse(...)' step rejects malformed JSON before the atomic mv — your existing config can never be clobbered by a truncated or syntactically broken write.

1. If qmd is in a non-standard path, set the command:

``json "qmd": { "command": "/path/to/qmd", ... } ``

1. Reload the MCP server:

`` /mcp ``

Search modes (QMD only)

| Mode | Description | Speed | Quality | |---|---|---|---| | search | Basic vector + BM25 hybrid | Fast | Good | | vsearch | Vector search with reranking | Medium | Excellent | | query | Full query expansion + rerank | Slow | Best |

Default: vsearch (recommended).

Temporal decay (builtin only)

Controls how dated files (memory/YYYY-MM-DD.md) lose relevance over time:

• halfLifeDays: 30 — a 30-day-old file scores at 50% of a today's file
• Set to a larger number (e.g., 90) to keep older memories relevant longer
• Set temporalDecay: false to disable

Citations

• auto — show citations in direct chats, suppress in groups
• on — always show
• off — never show

Modifying settings

To change a setting:

1. Read current agent-config.json with the Read tool (or treat as {} if it doesn't exist).
2. Compute the full updated object IN YOUR REASONING — preserve every other top-level key, only change the field(s) the user asked about.
3. Write back via Bash heredoc with validate + atomic mv (NOT the Write tool — agent-config.json is on the always-on protected-paths list; direct Write is refused). Substitute <FULL_UPDATED_JSON> with your computed object:

`` Bash('cat > agent-config.json.tmp << "JSON_EOF" && <FULL_UPDATED_JSON> JSON_EOF node -e \'JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"))\' agent-config.json.tmp \ && mv agent-config.json.tmp agent-config.json \ && echo "wrote agent-config.json" \ || { rm -f agent-config.json.tmp; echo "ABORTED: invalid JSON or filesystem error"; exit 1; }') ` The double-quoted "JSON_EOF" delimiter disables shell expansion in the body — JSON literals pass through verbatim, no escaping needed. cat > ... << "JSON_EOF" && puts the heredoc write itself in the && chain so a cat failure short-circuits the rest. The node -e 'JSON.parse(...)' step rejects malformed JSON BEFORE the atomic mv`, so a truncated or syntactically broken write can never clobber your config.

1. Run /mcp to apply.

Heartbeat settings

Active hours

Restrict heartbeat to the user's active window:

{
  "heartbeat": {
    "schedule": "*/30 * * * *",
    "activeHours": {
      "start": "08:00",
      "end": "23:00",
      "timezone": "America/Santiago"
    }
  }
}

Outside these hours, the heartbeat cron still fires but the agent should skip silently.

Dreaming schedule

{
  "dreaming": {
    "schedule": "0 3 * * *",
    "timezone": "America/Santiago"
  }
}

HTTP bridge + WebChat (optional)

The HTTP bridge is an optional local server that exposes the agent over HTTP — for webhooks, status checks, and a browser-based chat UI (WebChat).

Off by default. Enable with:

{
  "http": {
    "enabled": true,
    "port": 18790,
    "host": "127.0.0.1",
    "token": ""
  }
}

Settings:

• enabled — turn the server on/off (default: false)
• port — port to listen on (default: 18790)
• host — bind address (default: 127.0.0.1 — localhost only; change only if you know what you're doing)
• token — Bearer token for authenticated endpoints. Empty = no auth (fine for localhost-only). Set a value when exposing via tunnel (ngrok, Cloudflare, Tailscale).

Using WebChat

1. Enable the HTTP bridge (above).
2. Run /mcp to reload.
3. Open http://localhost:18790 in a browser.
4. Type. The agent sees messages as real user input — personality, memory, and commands all work the same as in WhatsApp or the CLI.

Endpoints exposed when http.enabled: true:

• GET / — WebChat UI
• GET /health — liveness (no auth)
• GET /v1/status — agent status
• GET /v1/skills — installed skills
• POST /v1/webhook — ingest webhooks
• GET /v1/webhooks — drain webhook queue
• POST /v1/chat/send — send a chat message
• GET /v1/chat/history — chat history
• GET /v1/chat/stream — real-time replies (SSE)

To turn WebChat off without losing other HTTP features, just close the browser tab. To turn the whole bridge off, set http.enabled: false and run /mcp.

Security note

Bind to 127.0.0.1 unless you know your network is safe. I