Skip to content

docs(windows): ASR callouts on every shim-invoking docs page#350

Open
Huntehhh wants to merge 1 commit into
buildingjoshbetter:mainfrom
Huntehhh:docs/windows-asr-callouts
Open

docs(windows): ASR callouts on every shim-invoking docs page#350
Huntehhh wants to merge 1 commit into
buildingjoshbetter:mainfrom
Huntehhh:docs/windows-asr-callouts

Conversation

@Huntehhh
Copy link
Copy Markdown
Contributor

@Huntehhh Huntehhh commented May 17, 2026

Summary

Adds Microsoft Defender ASR rule 01443614-cd74-433a-b99e-2ecdc07bfc25 ("Block executable files from running unless they meet a prevalence, age, or trusted list criteria") callouts to every documentation page that recommends a truememory-mcp or truememory-ingest invocation. No code changes.

Branched off origin/main directly — no PR dependencies, ships standalone.

Why

A growing share of hardened Windows-11 baselines run ASR rule 01443614 in Block mode (rather than the default Audit). On those hosts, the truememory-mcp.exe and truememory-ingest.exe console-script shims are silently killed at CreateProcess time — they're setuptools / uv trampolines with per-install unique hashes, so they fail the MS cloud-prevalence check before any user code runs. Users following any of the existing docs pages had no documented escape hatch.

The canonical workaround (already used by mcp_server._setup_claude when it writes the Claude MCP config in #346) is to invoke the equivalent module form through the signed, high-prevalence python.exe wrapper:

python -m truememory.mcp_server --setup
python -m truememory.ingest.cli install

What changed

File Change
docs/cli.md Callout at top, visible alongside both CLI references
docs/guides/debugging.md New "Windows: Risky action blocked / Defender ASR kills truememory-mcp.exe" section under Common Issues — the canonical command list + rationale + tray-quit guidance
docs/setup-cursor.md Per-adapter Troubleshooting bullet linking to debugging.md
docs/setup-codex.md Same
docs/setup-gemini.md Same
docs/setup-hermes.md Same
docs/setup-kimi.md Same
docs/setup-openclaw.md Same
CHANGELOG.md [Unreleased] / Documentation entry

Pattern: every callout names the rule, explains why (per-install unique hash fails MS cloud-prevalence check), and shows the module-form equivalent. The adapter-page callouts link back to debugging.md so the full explanation lives in one canonical place instead of being duplicated 6 times.

Test plan

  • Render the docs locally (or on the GitHub preview) — verify the blockquote in cli.md renders correctly with the embedded code block
  • Click the debugging.md#windows-risky-action-blocked--defender-asr-kills-truememory-mcpexe anchor from any setup-*.md page — confirm the anchor resolves (GitHub-flavoured markdown auto-generates anchors from headings)
  • Skim each setup-*.md to confirm the new bullet doesn't break adjacent formatting

Coordination context

Last of agent-C's planned PRs in the multi-agent TrueMemory hardening sweep. Sibling PRs from the same sweep: #346 (ASR installer fix + shim-migration), #348 (_setup_claude parse-miss + atomic settings.json), #349 (logging hygiene + Popen file-handle cleanup). agent-A's PRs (#344, #345, #347) and agent-B's planned PR-2a/PR-2b cover orthogonal scopes.

Zero code dependencies — this PR can merge in any order relative to the others.

Merge ordering

Order-independent / docs-only. Pure markdown changes under docs/ and CHANGELOG.md. Zero code risk, zero merge conflicts with any other open PR in the sweep.

Depends on: none.

Blocks: none.

Recommended sequence position: anywhere in the queue — can land first, last, or middle without affecting any other PR's merge state.

Adds Microsoft Defender ASR rule 01443614 ("Block executable files
from running unless they meet a prevalence, age, or trusted list
criteria") callouts to every documentation page that recommends a
`truememory-mcp` or `truememory-ingest` invocation.

- docs/cli.md: callout at top (visible alongside both CLI references)
- docs/guides/debugging.md: full "Risky action blocked" section in
  Common Issues with the canonical command list + Claude Desktop
  tray-quit guidance
- docs/setup-cursor.md, docs/setup-codex.md, docs/setup-gemini.md,
  docs/setup-hermes.md, docs/setup-kimi.md, docs/setup-openclaw.md:
  per-adapter Troubleshooting bullet pointing at the debugging.md
  canonical block

Pattern: every callout names the rule, explains why (per-install
unique hash fails MS cloud-prevalence check), and shows the
`python -m truememory.{mcp_server,ingest.cli}` equivalent. The
adapter-page callouts link back to debugging.md so the full
explanation lives in one place.

No code changes. Branched off origin/main directly — no PR
dependencies.

Co-Authored-By: claude-opus-4-7 <wontreply@getfucked.ai>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant