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) now also block at memory-write time, not just on skill-file scans.

Provenance & Trust

Safety & Scope

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

• User-initiated only. Setup is a manual step the user runs in their terminal. Nothing auto-executes on install. The quickstart command asks before each action.
• No credentials required for local use. Memory, scanning, and audit work fully offline. Cloud sync (team tier) requires a user-provided API key via shieldcortex config --cloud-enable --cloud-api-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 . 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, Team tier): 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 (Team tier): 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, Team tier). 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

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

# 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

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 (Pro)

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

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

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

shieldcortex config --cloud-enable --cloud-api-key <key>  # Enable cloud sync
shieldcortex cloud sync --full    # Backfill memories + graph to cloud
shieldcortex license activate sc_pro_...  # Activate Pro/Team licence
shieldcortex license status       # Check licence tier

Maintenance

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 Team tier only and off by default.

• 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

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