/settings

name: settings
description: Configure agent settings — memory backend (builtin/QMD), search mode, temporal decay, citations. Triggers on /agent:settings, "configurar agente", "agent settings", "memory settings", "setup QMD", "configurar QMD", "configurar memoria".
user-invocable: true
argument-hint: [setting]

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:**

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

2. **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

3. **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:

   {
     "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.

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

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

5. **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