ShieldCortex

Memory and defence for AI agents: semantic recall, knowledge graph and decay, plus a memory firewall that scans and enforces against prompt injection, credential leaks and poisoning.

ShieldCortex — Persistent Memory & Security for AI Agents

Memory system with built-in security. Gives agents persistent memory (semantic search, knowledge graphs, decay, contradiction detection) and protects it with a 6-layer defence pipeline (prompt injection, credential leaks, poisoning, privilege escalation, PII filtering, behavioural analysis). Skill threat patterns (tool injection, scope escalation, data exfiltration, persistence, supply-chain, agent manipulation, stealth instructions) block at memory-write time, not just on skill-file scans.

This is an enforcing memory boundary, not a passive scanner. Across the read/write boundary it actively: quarantines or blocks poisoned/credential-bearing writes; trust/ACL-filters recalled memory (RESTRICTED isolation, own-only for low-trust callers) before it reaches the agent, on both the prompt hooks and the MCP read tools; runs a tool-output firewall that, in enforce mode, redacts or withholds malicious tool results before the model sees them (advisory by default); and keeps a provenance ledger recording read/write/delete operations with content hashes for forensics. Enforcement that could surprise is opt-in (the tool-output firewall defaults to advisory; shieldcortex config --tool-firewall-enforce turns on blocking).

Provenance & Trust

Signal	Value
Publisher	Drakon Systems Ltd (UK company)
Source code	github.com/Drakon-Systems-Ltd/ShieldCortex — fully open, MIT-0 licence
npm package	npmjs.com/package/shieldcortex — every release git-tagged with a matching GitHub release
npm audit	Clean — npm audit returns 0 vulnerabilities
Downloads	11,000+/month (July 2026)
CI/CD	CI lint/test on every push; releases are version-tagged and published to npm manually by the maintainer
Postinstall script	Declared and bounded: prints setup instructions; on global installs it also smoke-tests the native SQLite binding, seeds default config on first install, and refreshes an OpenClaw hook/plugin that a previous setup already installed. It never adds integrations to a machine that had none, and it is a no-op for CI and local dependency installs. SHIELDCORTEX_SKIP_AUTO_OPENCLAW=1 skips the refresh.
Dependencies	8 runtime deps: better-sqlite3, zod, @modelcontextprotocol/sdk, express, ws, cors, safe-regex2, semver. express/ws/cors serve the bundled localhost-only dashboard/API; nothing dials out unless Cloud sync is explicitly enabled.

Safety & Scope

This section explains every privileged operation the tool performs and why.

• Active interception, not scan-only. Beyond read-only scans, ShieldCortex enforces at the boundary: writes failing the pipeline are quarantined/blocked; recalled memory is trust/ACL-filtered before the agent sees it; in enforce mode the tool-output firewall redacts/withholds malicious tool results; and the OpenClaw before_tool_call interceptor + Iron Dome kill-switch can block operations. Surprising enforcement is opt-in (tool-output firewall defaults to advisory). shieldcortex status and iron-dome status report which controls are active.
• Setup is user-initiated. Installing hooks, registering the MCP server, and migrating data are manual steps the user runs in their terminal, and quickstart asks before each action. The npm postinstall script (disclosed in the trust table above) never adds integrations that weren't already present — on global installs it only prints instructions, checks the native binding, seeds default config on first install, and refreshes an existing OpenClaw hook/plugin install.
• Setup migrates legacy data. The first quickstart/setup run may move or remove legacy config/memory directories (e.g. ~/.claude-cortex/, ~/.claude-memory/) into ~/.shieldcortex/ and copy hook files into place. This happens only on the user-run setup command — never on npm install (the postinstall script does not touch memory or config data beyond seeding defaults on a first-ever global install).
• Destructive forget is bounded and gated. Per-memory and filtered bulk deletes go through a delete ACL (own-only) and are recorded in the audit ledger. Revoke-by-source (forget --fromSource, bulk-delete every memory from one source — for purging a poisoned agent) is disabled by default and only enabled by an out-of-band human action (shieldcortex config --allow-revoke-by-source); even then it is bounded by a trust-hierarchy ACL (you must own the source or out-rank it) and a per-call row cap. A compromised agent cannot mass-delete your memory.
• The bundled dashboard never renders RESTRICTED content. The local visualization API and its WebSocket feed redact credential-class (RESTRICTED) memory content before it reaches the browser — the row stays visible (title/metadata) so you can manage it, but the secret is withheld (view full content via the CLI). Credential patterns in titles/metadata are masked too. This is a display-surface safeguard on top of the on-disk store; it does not weaken the firewall.
• No credentials required for local use. Memory, scanning, and audit work fully offline. Cloud sync is opt-in and requires a user-provided API key via shieldcortex config --cloud-enable --cloud-api-key <key>.
• File access is declared and scoped. Security scans read agent config directories listed in the permissions block above — the same directories the agent itself already has access to. They do not traverse arbitrary directories.
• Writes are contained. All data goes to ~/.shieldcortex/. MCP config edits (setup, copilot, codex commands) modify specific JSON files and confirm before writing.
• Network is off by default. No outbound connections unless Cloud sync is explicitly enabled by the user. The dashboard and worker bind to localhost only.
• Bundled source code. The OpenClaw plugin and cortex-memory handler are shipped in the package for inspection before use.
• Lifecycle event handlers. ShieldCortex registers lifecycle handlers that auto-extract important context from conversations. These are registered in ~/.claude/settings.json during setup and can be removed at any time. They run locally, never phone home.
• Proactive recall. The UserPromptSubmit handler queries local memory on each prompt (<100ms) and surfaces relevant context. Fully local, configurable: shieldcortex config --proactive-recall false.

Data handling, privacy & consent

ShieldCortex is local-first: memory, scanning, and audit run entirely on your machine — no account, no network, no telemetry by default. Because the tool can auto-capture conversation content, here is exactly what it reads, stores, and (only if you opt in) transmits.

• What it reads. With the lifecycle handlers enabled (opt-in at setup), ShieldCortex reads your agent session transcripts — both your prompts and the assistant's replies — to auto-extract memorable context. PreCompact (before context compaction) reads the recent transcript; the SessionEnd and Stop handlers are off by default; the OpenClaw integration extracts from assistant output and explicit keyword triggers. SessionStart does not read transcripts (it only loads existing local memory and scans project rule files).

• What it stores, and for how long. Saved and auto-extracted memories are written to a local SQLite database at ~/.shieldcortex/memories.db — title and content verbatim — and persist across sessions until you remove them (decay/consolidation prune low-value entries over time). Nothing is stored remotely unless you enable Cloud sync. Delete a memory with the forget tool, or remove the database to wipe everything.

• Secrets & credentials. Every write — manual or auto-extracted — passes the defence pipeline first; high-confidence credential patterns (keys/tokens across 11+ providers) and content classified RESTRICTED are blocked or quarantined before storage, not saved as live memory. This is a strong filter, not a guarantee: low-confidence or low-entropy secrets can still be stored. On sensitive work, review what auto-memory captures and disable auto-extraction (shieldcortex config --openclaw-auto-memory false; the Claude Code handlers can be removed from ~/.claude/settings.json).

• Triggers capture surrounding context. Keyword auto-save triggers (e.g. "remember this", "don't forget") capture the nearby text, which may include more than you intend — treat them as "save the recent context," not "save exactly this line." They're capped (auto-extracts never outrank explicit saves) and run through the same credential/injection scan.

• Subprocess execution. The OpenClaw integration spawns short-lived npx mcporter subprocesses (via execFile, no shell) to talk to your local ShieldCortex MCP server over stdio. No remote code is fetched or executed.

• Cloud sync — off by default, opt-in, explicit. No data leaves your machine unless you run shieldcortex config --cloud-enable --cloud-api-key <key>. When enabled:

  • Audit telemetry (/v1/audit/ingest): scan metadata only — trust scores, threat indicators, categories, timings, device name. No memory content.
  • Memory sync (/v1/sync/memories, Enterprise licence — grandfathered Team keys also unlock it): transmits full memory title + content of PUBLIC/INTERNAL memories so they sync across your team. CONFIDENTIAL/RESTRICTED memories are excluded by default; switch to metadata-only with the contentMode control.
  • Quarantine sync (Enterprise licence): flagged content is sent with detected credentials redacted.
  • OpenClaw realtime plugin (optional): scans live input and output locally. When it flags something, only threat metadata (type, scores, timestamps — never the input text itself) is forwarded, and only when Cloud sync is enabled. Flagged-content previews are kept in your local audit log; they are never transmitted.

  Raw conversation/input text is never transmitted by the audit, threat, or interceptor paths — they carry metadata only. The single exception is Memory sync above, which uploads the content of memories you chose to store (PUBLIC/INTERNAL, off by default, Enterprise licence). You can disable any of the above at any time, and the realtime plugin and lifecycle handlers can be removed entirely.

What it does NOT do

• Does not read SSH keys, AWS credentials, GPG keys, or /etc/ files
• Does not send data to external servers (unless Cloud sync is explicitly enabled)
• Does not modify .bashrc, .zshrc, .profile, or shell configs
• Does not use eval(), child_process.exec(), or dynamic code execution
• Does not bypass, disable, or override any agent safety mechanisms
• Does not auto-approve actions or skip verification prompts
• Does not mine cryptocurrency, trade tokens, manage wallets, or initiate purchases
• Does not make purchases, place orders, or move money on the user's behalf

CLI Reference

Getting Started

bash

shieldcortex quickstart          # Detect integrations, guide setup
shieldcortex setup               # Register MCP server for current project
shieldcortex doctor              # Diagnose registration issues
shieldcortex status              # Show protection status
shieldcortex uninstall           # Remove from project

Memory

bash

# Memory is typically used via MCP server, not CLI directly.
# The MCP server exposes: store, recall, search, forget, consolidate, graph.
shieldcortex graph backfill      # Build knowledge graph from stored memories
shieldcortex stats               # Memory statistics

Security Scanning

bash

shieldcortex scan "text"                    # Scan text through defence pipeline
shieldcortex scan-skill path/to/SKILL.md    # Scan one instruction file for threats
shieldcortex scan-skills                    # Scan all discovered agent instruction files
shieldcortex audit                          # Full security audit (memory, env, MCP configs, rules files)
shieldcortex iron-dome status               # Iron Dome behavioural protection status

Cortex — Mistake Learning

bash

shieldcortex cortex capture --task "..." --mistake "..." --fix "..."  # Log a mistake
shieldcortex cortex preflight --task "deploy to production"           # Pre-task check
shieldcortex cortex review                                            # Pattern analysis
shieldcortex cortex list                                              # View mistake log
shieldcortex cortex stats                                             # Category breakdown

Dashboard & Services

bash

shieldcortex dashboard           # Open local web dashboard (localhost:3001)
shieldcortex api                 # Start API server
shieldcortex worker              # Background sync + heartbeat worker
shieldcortex service start|stop|status  # Manage background service

Integrations

bash

shieldcortex openclaw setup      # Set up OpenClaw realtime plugin
shieldcortex copilot setup       # Set up VS Code / Cursor MCP server
shieldcortex codex setup         # Set up Codex CLI MCP server
shieldcortex config --openclaw-auto-memory true   # Enable auto-memory in OpenClaw
shieldcortex config --proactive-recall true|false  # Enable/disable proactive recall

Cloud & Licensing

bash

shieldcortex config --cloud-enable --cloud-api-key <key>  # Enable cloud sync
shieldcortex cloud sync --full    # Backfill memories + graph to cloud
shieldcortex license activate <key>  # Activate an Enterprise (or legacy) licence key
shieldcortex license status       # Check licence tier

Maintenance

bash

shieldcortex update              # Self-update (npm package + OpenClaw plugin + skill)

What Gets Scanned

scan-skills discovers and scans:

• SKILL.md, HOOK.md, handler.js (Claude Code / OpenClaw skills)
• .cursorrules, .windsurfrules, .clinerules (editor rules)
• CLAUDE.md, copilot-instructions.md (agent instructions)
• .aider.conf.yml, .continue/config.json (tool configs)
• Searches: ~/.claude/skills/, ~/.openclaw/skills/, ~/.openclaw/hooks/, project directories

audit checks:

• Memory files — ~/.claude/projects/, ~/.cursor/memories/, ~/.windsurf/memories/
• Environment — .env files for leaked credentials (read-only check, never writes)
• MCP configs — ~/.claude/mcp.json, ~/.openclaw/mcp.json, ~/.cursor/mcp.json, project-level equivalents
• Rules files — CLAUDE.md, .cursorrules, copilot-instructions.md for injection patterns

What Gets Uploaded to Cloud

Cloud sync is off by default. Audit metadata sync is included on the cloud free tier; full memory/graph replication requires an Enterprise licence (grandfathered Team keys keep working).

• Uploaded when Cloud sync is enabled by the user: selected memory records, related embeddings/metadata, and knowledge-graph entities/relationships required for sync.
• Not uploaded by default: local agent configs, MCP configs, raw rules files, shell configs, SSH keys, secrets, .env contents, or arbitrary project files.
• Security scan results stay local unless the user explicitly exports or syncs data through a Cloud-enabled workflow.
• No cloud traffic at all occurs unless the user explicitly enables Cloud sync and provides a valid API key.

Licence Tiers

Public tiers are Free and Enterprise ([e-mail]). Every local feature is Free; grandfathered Pro/Team keys keep working.

Feature	Free	Enterprise
Memory (store/recall/search/graph)	✅	✅
Proactive recall (auto-inject on prompts)	✅	✅
Defence pipeline (scan, Iron Dome)	✅	✅
Audit & scan-skills	✅	✅
Dashboard	✅	✅
Custom injection patterns	✅	✅
Custom Iron Dome policies	✅	✅
Custom firewall rules	✅	✅
Audit export	✅	✅
Deep skill scanning	✅	✅
Cortex (mistake learning)	✅	✅
Cloud audit sync (metadata, 500 scans/mo, 7-day retention)	✅	✅
Cloud memory/graph sync	❌	✅
Team management	❌	✅
Shared patterns	❌	✅

Links

• Docs: https://shieldcortex.ai/docs
• Source: https://github.com/Drakon-Systems-Ltd/ShieldCortex
• npm: https://www.npmjs.com/package/shieldcortex
• Issues: https://github.com/Drakon-Systems-Ltd/ShieldCortex/issues
• Changelog: https://shieldcortex.ai/changelog