help: background maintenance tasks fail on non-OpenAI-native chat providers (minimax M3 returns thinking-prefixed text, not JSON)

[hasibagen]

---

title: "help: background maintenance tasks fail on non-OpenAI-native chat providers (minimax M3 returns thinking-prefixed text, not JSON)"
labels: "help wanted, documentation"

Context

I'm running memsearch plugin for Claude Code with a Chinese LLM provider called <provider-A> (let's call it this for neutrality). The provider exposes an OpenAI-compatible endpoint at https://<provider>.com/v1/chat/completions, supports function calls, and returns standard OpenAI-format responses.

The summarize and index paths work fine with this provider. The plugin config:

[llm.providers.[provider-A]]
type = "openai"
model = "<provider-A>-chat"
base_url = "https://<provider>.com/v1"
api_key = "env:PROVIDER_API_KEY"

[plugins.claude-code.summarize]
provider = "[provider-A]"
model = "<provider-A>-chat"

→ Stop hook summaries land in .memsearch/memory/YYYY-MM-DD.md as expected.

Problem

Background maintenance tasks (project_review, user_profile, memory_to_skill) fail at runtime with:

RuntimeError: Maintenance LLM did not return valid JSON: Expecting value: line 1 column 1 (char 0)

The state file ~/.memsearch/.maintenance-state.json records:

{
  "claude-code.user_profile": {
    "last_error": "RuntimeError: Maintenance LLM did not return valid JSON: Expecting value: line 1 column 1 (char 0)",
    "last_failed_at": "2026-08-05T07:36:10.405714Z"
  }
}

Root Cause Analysis

Direct curl to the provider's chat completions endpoint (mirror of what memsearch's maintenance.py calls):

curl -X POST "https://<provider>.com/v1/chat/completions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<provider-A>-chat",
    "messages": [{"role": "user", "content": "Return only JSON: {\"action\":\"none\"}"}],
    "max_tokens": 1000,
    "temperature": 0
  }'

The response:

{
  "choices": [{
    "message": {
      "content": "{\"action\":\"none\"}",
      "role": "assistant"
    }
  }],
  "usage": {
    "completion_tokens_details": {"reasoning_tokens": 0}
  }
}

But with smaller max_tokens (default 200), the response gets truncated mid-JSON:

{
  "message": {
    "content": "{\"action\":\"none\"}\""   ← trailing " breaks json.loads
  }
}

And with the default memsearch prompt (which builds a long ## Current Direction / Active Threads / Recent Progress ... template), the model adds a ## Reasoning block in front of the JSON:

## Reasoning
The user is asking me to update PROJECT.md based on recent journals...

## Result
{"action":"none"}

In either case, json.loads(content) in maintenance.py:578 fails because the first non-whitespace character is # (from ## Reasoning) or " (from truncated JSON).

What I Tried (all failed)

Attempt	Result
Set max_tokens=1000	Some prompts still hit ceiling (long journals + big prompt)
Custom prompt via [prompts].project_review and [prompts].user_profile forcing JSON output	Model still adds Chinese-language leading prose
System prompt "Never output think tags, reasoning, or analysis. Output ONLY what the user requests."	Worked for trivial prompts (10 chars), but ignored for real 18k-char prompts
Patch maintenance.py to strip ```json ... ``` fences	Already supported; my provider doesn't wrap in fences
Patch maintenance.py to strip ## Reasoning blocks	Worked for some prompts, but the user-managed codebase (/home/jade/.local/share/uv/tools/memsearch/...) gets overwritten on every uv tool install --force

What I'm Asking For

I'd like some combination of:

1. Pre-validation / tolerant parsing in maintenance.py:

   • Strip leading ## Reasoning / non-JSON prose before json.loads
   • On parse failure, retry the LLM call with a stricter prompt (e.g., "failed: only return JSON, no markdown")
   • Or fall back to action: "none" with the raw text logged to .maintenance-state.json

2. Configurable request params for the maintenance calls:

   • max_tokens (currently hardcoded or per-provider default)
   • response_format: {type: "json_object"} (OpenAI native JSON mode) — opt-in, since not all providers support it
   • extra_body passthrough for provider-specific knobs (e.g. chat_template_kwargs for Groq, thinking for some others)

3. Documentation / examples:

   • A worked example using a non-OpenAI-native provider (DeepSeek, Zhipu, MiniMax, etc.) with the exact recommended config in ~/.memsearch/config.toml
   • A note that summarize is more permissive (plain text) but maintenance is strict JSON, so the failure modes differ

4. Provider-aware defaults:

   • Skip maintenance automatically when the provider name doesn't match a known JSON-strict list (or always run it in strict_json mode with a fallback)

My preferred fix would be (1) lenient parsing + (2) max_tokens + response_format config — the smallest scope that unblocks non-OpenAI-native providers.

Environment

• memsearch 0.4.17
• Plugin installed via marketplace
• Provider: <provider-A> (OpenAI-compatible REST API)
• OS: Linux

Workaround (current)

I disabled all project_review / user_profile / memory_to_skill maintenance tasks via memsearch config set plugins.claude-code.<task>.enabled false. This means I lose the auto-generated PROJECT.md / USER.md / skill-candidates/. I write PROJECT.md by hand when needed.

Happy to send a PR if you can point me to a maintainer preference for the approach (lenient parsing vs. config knob vs. docs).

[Roovelrz]

Hi, @hasibagen , Thanks for the detailed investigation. :)
I agree with your main finding: maintenance responses are currently parsed much more strictly than normal summarization output, so an otherwise valid JSON result fails when a provider adds leading reasoning or trailing text.

I can take this. I previously worked on this maintenance module and its tests in PR #656.

For the first PR, I would keep the scope focused on provider-agnostic response parsing:

• preserve the existing plain JSON and fenced JSON behavior
• use json.JSONDecoder().raw_decode() to extract a complete maintenance JSON object from responses containing leading reasoning or trailing text
• continue validating that action is either none or replace
• keep malformed or genuinely truncated JSON as an explicit failure rather than silently falling back to action: none
• add regression tests for reasoning-prefixed output, trailing text, invalid braces before the result, nested braces in content, and truncated JSON

I agree that configurable max_tokens, response_format, and provider-specific request options could also be useful, but I would leave those for a separate follow-up because they expand the provider and configuration API surface.

This should address the reported MiniMax-style response while also improving compatibility with other OpenAI-compatible providers.

[hasibagen]

Hi, @hasibagen , Thanks for the detailed investigation. :) I agree with your main finding: maintenance responses are currently parsed much more strictly than normal summarization output, so an otherwise valid JSON result fails when a provider adds leading reasoning or trailing text.

I can take this. I previously worked on this maintenance module and its tests in PR #656.

For the first PR, I would keep the scope focused on provider-agnostic response parsing:

• preserve the existing plain JSON and fenced JSON behavior
• use json.JSONDecoder().raw_decode() to extract a complete maintenance JSON object from responses containing leading reasoning or trailing text
• continue validating that action is either none or replace
• keep malformed or genuinely truncated JSON as an explicit failure rather than silently falling back to action: none
• add regression tests for reasoning-prefixed output, trailing text, invalid braces before the result, nested braces in content, and truncated JSON

I agree that configurable max_tokens, response_format, and provider-specific request options could also be useful, but I would leave those for a separate follow-up because they expand the provider and configuration API surface.

This should address the reported MiniMax-style response while also improving compatibility with other OpenAI-compatible providers.

Thank you so much for your work. Is there anything I can do to help?

[Roovelrz]

Thank you! @hasibagen :)

The most helpful thing would be to test the PR with the same provider and maintenance configuration that originally reproduced the issue.

Could you verify whether project_review and user_profile now handle the reasoning-prefixed response successfully? If anything still fails, a redacted copy of the returned message content and the resulting maintenance error would be very useful.

No need to change your provider configuration for the test.

[hasibagen]

Hi @Roovelrz 👋

Thanks for picking this up — I really appreciate the focused scope of the PR. I just finished testing PR #669 against the exact configuration that originally reproduced the issue, and it works. Here's the full write-up so it lands in the thread for future searchers.

1. Background — what I had already tried (all unsuccessful)

Before filing the issue I had spent considerable time on the provider side, trying to make MiniMax-M3 return clean JSON. None of these survived:

Attempt	Result
Custom project_review / user_profile prompt files with "MUST be a single JSON object, no thinking/reasoning prefix, start with {" instructions	LLM still emitted ## Reasoning / ## Result markdown headers
Setting max_tokens=1000, temperature=0	Eliminated truncation but did not eliminate the reasoning prefix
Requesting thinking: false	MiniMax endpoint rejected it / no stable effect
Adding <think> stripping logic locally	Worked once, then drifted as the provider changed wrapper text
Injecting via OpenAI SDK extra_body, system prompt override, custom HTTP transport	Reliable injection path into the actual memsearch call site could not be found; all patches reverted

I had effectively given up on the provider side and worked around the bug by setting both tasks to enabled = false, which is why no .maintenance-state.json activity appeared for several days. The proper fix had to live in memsearch itself, which is what your PR does.

2. Test setup (no provider config changed)

I installed your patch against the version that originally shipped to me and re-enabled both tasks without touching the provider section. The relevant config (redacted only for the API key) is exactly what I had when the issue was filed:

[llm.providers.minimax]
type = "openai"
model = "MiniMax-M3"
base_url = "https://api.minimaxi.com/v1"
api_key = "env:MINIMAX_API_KEY"

[plugins.claude-code.summarize]
enabled = true
provider = "minimax"
model = "MiniMax-M3"

[plugins.claude-code.project_review]
enabled = true                  # was false; re-enabled for the test
provider = "minimax"
model = "MiniMax-M3"
min_interval_hours = 24
input_dir = ".memsearch/memory"
output_file = ".memsearch/PROJECT.md"

[plugins.claude-code.user_profile]
enabled = true                  # was false; re-enabled for the test
provider = "minimax"
model = "MiniMax-M3"
min_interval_hours = 24
input_dir = ".memsearch/memory"
output_file = ".memsearch/USER.md"

Patched src/memsearch/maintenance.py (commit 83118e3) and applied the same edit to my installed copy.

3. Regression tests

$ python -m pytest tests/test_maintenance.py -v
Pytest: 22 passed

All 10 new cases pass, including the ones that most closely match the MiniMax response shape:

• test_parse_task_response_accepts_reasoning_before_json ✅
• test_parse_task_response_accepts_trailing_text_after_json ✅ (both '"' and "\n\nDone." suffixes)
• test_parse_task_response_skips_invalid_braces_before_result ✅
• test_parse_task_response_prefers_final_maintenance_object ✅ — this one is great, the LLM sometimes embeds an example response in its own reasoning before the actual result
• test_parse_task_response_preserves_braces_inside_content ✅ — important because my replacement content has code snippets with {...}
• test_parse_task_response_rejects_truncated_json ✅
• test_parse_task_response_rejects_invalid_action ✅
• The existing plain and fenced JSON cases still pass — no regression

4. End-to-end test against live MiniMax-M3

Ran both tasks with force=True to bypass the 24-hour throttle:

$ python -c "from memsearch.maintenance import run_due_tasks; ..."
=== RESULTS ===
  task=project_review action=replace skipped=False
    reason='Recent journals add durable state: qmd plugin cycle, qmd embed root cause
            (node-llama-cpp HEAD to huggingface.co), cognee path 1 env vars confirmed,
            basic-memory cleanup pending, and 4-layer architecture details captured.
            Targeted updates to existing sections.'
  task=user_profile  action=replace skipped=False
    reason='Recent journals establish stable user identity, workflow patterns,
            communication preferences, and tool/environment constraints.'

State file after the run:

{
  "claude-code.project_review": {
    "last_action": "replace",
    "last_success_at": "2026-08-06T11:33:57Z",
    "output_file": "/home/mind/nut/edu/ai/.memsearch/PROJECT.md"
  },
  "claude-code.user_profile": {
    "last_action": "replace",
    "last_success_at": "2026-08-06T11:33:57Z",
    "output_file": "/home/mind/nut/edu/ai/.memsearch/USER.md"
  }
}

Both PROJECT.md (11.9 KB) and USER.md (4.4 KB) were written with high-quality content — the LLM's reasoning text was correctly discarded and only the trailing JSON {"action":"replace", "reason": "...", "content": "..."} was honored. No silent fallback to action: none, no truncation, no provider-config workaround required.

5. Verification points you specifically asked about

"Could you verify whether project_review and user_profile now handle the reasoning-prefixed response successfully?"

✅ Both verified. I left the original MiniMax-M3 config completely untouched; the only change was enabling the two tasks and applying your patch. The reasoning-prefixed responses are now parsed correctly into proper maintenance JSON.

"If anything still fails, a redacted copy of the returned message content and the resulting maintenance error would be very useful."

Nothing fails anymore, so no error to redact. For documentation purposes the LLM's raw response in the failing case was essentially:

## Reasoning
The recent journals cover <thinking about what changed> ...

## Result
{"action":"replace","reason":"Recent journals add durable state: ...","content":"# Project Memory\n..."}

The leading ## Reasoning block plus any inline brace noise from the thinking was exactly what the old json.loads() choked on, and your raw_decode() scan now handles it.

6. Recommendation

👍 +1 on merging as-is. I agree with your call to defer max_tokens / response_format / extra_body to a follow-up — that surface is bigger and should be designed alongside the provider configuration story rather than bolted onto this parser fix.

If it helps, I'm happy to also submit a tiny follow-up PR that re-enables enabled = true defaults in the docs example for OpenAI-compatible providers (with a one-line note that reasoning-prefixed responses are now tolerated), since the previous workaround of disabling both tasks is no longer needed for any provider I know of.

Thanks again for the clean fix — this unblocks background maintenance for every non-OpenAI-native provider that adds reasoning text. 🚀

[hasibagen]

Quick follow-up while testing PR #669 — I discovered the same parsing pattern exists in src/memsearch/skills.py::_parse_distill_response (line 182 in 0.4.17), which serves the memory_to_skill background task. It uses an independent parser with the same strict json.loads(text) call and the same failure mode against reasoning-prefixed output from MiniMax-M3.

I have applied the exact same raw_decode()-scan approach locally to _parse_distill_response (adapted to look for the skills field instead of action), and the 7 unit tests I wrote (plain / fenced / reasoning / trailing / invalid-braces / braces-in-body / truncated) all pass. So the fix is mechanically identical to PR #669.

When you have bandwidth for a follow-up PR (separate from #669, to keep that one focused), the same diff shape would apply — only the target dict key changes from action to skills. Happy to send that PR myself if useful, just let me know.

Also noting: even with the parser fix, the live memory_to_skill invocation against MiniMax-M3 still fails because the LLM emitted a project_review-shaped response (action/reason/content) instead of the memory_to_skill shape ({"skills": [...]}). The patch correctly rejects that as a schema mismatch ("response must contain a 'skills' list"), so this is a prompt-strength issue, not a parser issue — but worth knowing that reasoning-prefixed responses are not the only failure mode for that task.

[Roovelrz]

Hi, @hasibagen , Thank you for the extremely thorough testing and write-up. :)

Verifying both project_review and user_profile against the original MiniMax-M3 configuration is especially helpful. It confirms that the focused parser change addresses the original issue without requiring provider-specific configuration changes.

A reviewer has identified one additional edge case in #669 involving nested JSON objects. I’m going to tighten the candidate selection and add regression coverage for that before the PR is finalized. This remains a small parser-level adjustment and does not change the scope or the behavior you verified.

Good catch on _parse_distill_response as well. I agree that memory_to_skill should stay separate from #669. It has the same parsing pattern, but its own skills schema and prompt behavior, so a follow-up PR will be much easier to review and test independently.

Since you already have the adapted parser change and regression tests working locally, please feel free to send that follow-up PR. Your live test also makes an important distinction clear: reasoning-prefixed valid JSON is a parser issue, while returning an action-shaped object instead of a skills list is correctly rejected as a schema mismatch and should be treated separately as a prompt issue.

Thanks again for testing this so thoroughly and for separating those failure modes clearly.