Trusted task: let it work. Hijack: a plain-English card. Catastrophe: a hard stop.

What a catch looks like

shieldcortex scan "ignore previous instructions"

ShieldCortex Scan Result
──────────────────────────────────────────────────
  Result:      QUARANTINE
  Source:      cli:shieldcortex-scan (attested)
  Provenance:  cli (trusted, L2 not applied)
  Trust:       0.90
  Sensitivity: PUBLIC
  Anomaly:     0.00
  Reason:      Quarantined: Instruction injection detected (confidence: 0.8)
  Threats:     instruction_injection
  Patterns:    hidden_instruction

That string was caught and quarantined. Nothing was stored as a memory, and the exit code is non-zero so a script or CI job can act on it. How scan results work.

What you get

• Memory firewall. ShieldCortex does not replace OpenClaw, Hermes, or Claude memory. Writes that go through it are scanned before they stick. Recognised injection and leaked credentials are quarantined or blocked.
• Tool gate. On Claude Code, OpenClaw, and Hermes, once Action Guard is on, a trusted task runs, a suspicious call gets a plain-English card, and a catastrophic command is a hard stop.
• Inspect. shieldcortex dashboard is a local view: Home, Needs you, Memory, Protection, Settings. The Skill & package scanner (formerly X-Ray) is a Protection tab. Memory has Search & browse, Map, Recall, Needs a check, Timeline, Replay, and Files. Needs you lists held-back items, memory pairs that disagree or look duplicated, and new scanner findings. It is not an approval inbox: held actions are still answered in Telegram or OpenClaw. Its counts are labelled when they are partial: pair counts stop at 20 of each kind and the disagreement check compares only the 200 most important memories, a list that failed to refresh shows its last known count, and scanner findings cover the whole computer even when a project is selected. Prompt-time recall into Claude Code is not automatic. What it needs. In prompt-time recall (the UserPromptSubmit hook), turns detected as a cron job, subagent or liveness probe, or pinned to one of those lanes, get narrower recall than the owner's chat, and rows labelled PERSONAL (private-life notes the classifier recognised or a backfill raised) are withheld from them. This is not universal isolation: a private note the classifier missed and labelled PUBLIC can still reach those lanes, and SessionStart context, MCP tool reads and dashboard previews are not lane-scoped. Recall lanes.

Install

Requires Node 22.14+ or 24+. Upgrading from 4.x? Read Upgrading to 5 first. Node 20, Node 23, and what npm does.

npm install -g shieldcortex
shieldcortex setup
shieldcortex doctor

For manual storage and memory hygiene, run shieldcortex maintain. It consolidates STM above its cap (applied by default: this is the first phase of shieldcortex consolidate, not Dream Mode; it promotes, deletes decayed STM, evicts older unpinned memories from an over-limit tier, and deletes or downvotes near-identical long-term copies, so run --dry-run first), backfills missing vectors when the embedding model is cached, vacuums a database with enough free pages, then runs doctor's Memories, Semantic coverage and Disk checks and sends any remaining FAIL to the configured Action Guard webhook (the same FAIL set at most once a day). A database lock held by another live ShieldCortex process, whether seen before opening or at lock acquisition, skips consolidation, embedding and vacuum. It exits 1 while a FAIL remains. Use --dry-run to preview without changing database contents or config; SQLite may create shared-memory sidecar files. Use --json for a structured report. Audit-log retention is not part of maintain yet (#579), and nothing schedules it yet.

setup is the onboarding command: it prints one host table and asks before wiring each host. shieldcortex setup claude skips the table and runs the Claude Code install without asking. That install can write ~/.claude/CLAUDE.md, ~/.claude.json and ~/.claude.json.bak-shieldcortex if it replaces the file, ~/.claude/settings.json and ~/.claude/settings.json.bak-shieldcortex if it replaces the file, and ~/.claude/hooks/cortex-memory/ unless any detected hook root already has a cortex-memory directory. If that hook installer runs against a writable OpenClaw root, it can also copy the OpenClaw hook, install or register the realtime plugin, snapshot and rewrite openclaw.json, and may restart the gateway. Two older names still work. quickstart takes the same targets as setup's guided path, without hook flags or uninstall. install is not the wizard: it runs that same Claude Code install as setup claude, and is kept for existing scripts and the --without-* hook opt-outs. Within 5.x, update with shieldcortex update.

If npm skipped the package's lifecycle scripts (for example --ignore-scripts, or ignore-scripts=true in an npm config), ShieldCortex's postinstall did not run. On a global install that step wires no host. It prints the next step, checks that the database engine loads, writes a default ~/.shieldcortex/config.json when none exists, refreshes an OpenClaw integration that is already present, and on macOS restarts a dashboard service still running an older build. Skipping it does not skip onboarding: run shieldcortex setup, then shieldcortex doctor. Without that config file, prompt-time recall stays off until you turn it on. What postinstall does.

Semantic search downloads a small embedding model on first use. For air-gapped hosts or a mirror, see Offline embedding cache. It covers the embedding model only, not every network feature.

Where it can block

Action Guard stays off until you turn it on. That shared setting is the tool gate for Claude Code and OpenClaw. A bare sudo shieldcortex protect turns it on and pins that posture. Policy lock. The Hermes plugin does not read the shared setting; it has its own (below).

| Host | Memory scan | Tool gate | |---|---|---| | Claude Code | yes | bound (PreToolUse) | | OpenClaw | yes | bound (before_tool_call) | | Hermes | via the local API | bound (pre_tool_call) | | Codex, Cursor, Copilot, MCP | if the agent calls the tools | not a gate | | LangChain, Python SDK | if you call scan or save | not a gate | | Claude SDK browser / computer toolsets (TypeScript) | no | observe by default; mode: 'enforce' refuses or holds for approval (shieldcortex/toolsets, 5.8+) |

shieldcortex doctor prints the same split: memory + tool gate for a host that can deny, and memory only, not a gate, for one that cannot. It shows the live Guard posture for Claude Code and OpenClaw. For Hermes it only reports whether the plugin copy is present. It will not print "protected" for a host that cannot deny.

Hermes gates tool calls once you run hermes plugins enable shieldcortex and the local API (shieldcortex api) is up. The enabled plugin enforces by default, whatever the shared Action Guard setting says: it blocks unless SHIELDCORTEX_ENFORCE opts it out (0, false, no, off or advisory). Hermes has no approval prompt, so a call Action Guard would hold for approval is blocked while enforcing. Advisory mode still blocks Action Guard's hard-block verdicts and recognised calls that would change the guard's own state or config (a plain read of its config with ls, cat, head, tail, wc, stat, du, grep or jq and plain arguments is not one of them; a read with an environment prefix, an option the guard cannot prove harmless, a redirection, nested execution or an interpreter still is). While the API is unreachable, its bounded fallback scan blocks the self-protection and catastrophic shapes it recognises in every mode, and recognised dangerous shapes while enforcing (the default). In advisory mode, only the recognised self-protection and catastrophic shapes are blocked by the fallback. Hermes plugin. Codex, Cursor, VS Code, and other MCP hosts get a memory server the model may call. That server is a scanner, not a deny.

If the Claude Code PreToolUse hook fails to load, a bounded fallback still blocks recognised catastrophic commands, even with the guard off. While the hook is broken those patterns also stop routine recursive force-deletes. Calls that do not match stay fail-open. Full note.

The optional enforce-when-ready posture runs the dangerous tier in shadow until this install's own audit shows the guard is operable and reviewed evidence for the running version exists. No such evidence ships yet, so today it stays in shadow and says so. What's new in 5.4.

shieldcortex policy-evidence (5.5+) reports what each runtime's own self-report says it is enforcing, as local self-reports rather than attestation. What's new in 5.5.

Approval cards (5.6+) say what a held action does, why it was held and who asked, in plain English, without the raw command. Database, cluster and cloud teardown commands now ask for approval (5.6+). What's new in 5.6.

shieldcortex/toolsets (5.8+) sits in front of a Claude SDK browser-use or computer-use driver and by default records what each click, keystroke, navigation and page read would trigger without changing what runs; mode: 'enforce' refuses the riskiest calls outright, holds risky ones (such as irreversible clicks after a page read) for your approval, and lets the rest run. Quickstart.

Free and Cloud

Two different apps.

• Local (shieldcortex dashboard) runs on your machine. The Skill & package scanner (formerly X-Ray) lives here, under Protection.
• Cloud is the fleet view: Shield, Capture, Recall, Library, Graph, Replay, Review, Quarantine, Dome, Devices, Keys. Default chrome is glass (Shield). Cloud does not ship X-Ray.

Free cloud: 500 scans/month, 7-day retention, 1 member. Enterprise (fleets, SSO, full replica): [email protected].

How to connect a box.

Links

• Docs
• Dashboard guide
• Changelog
• Updating
• Security ([email protected])
• Contributing
• Licence: MIT. Every local feature is free.