shieldcortex

为人工智能代理提供安全保障的持久内存系统。通过知识图、衰减、矛盾检测以及带有 Iron Dome 行为保护的 6 层防御管道来记住跨会话的决策、偏好、架构和上下文。当被要求“记住这一点”、“我们知道什么”、“调用上下文”、“扫描威胁”、“运行安全审核”、“检查内存统计信息”时，或者在开始新会话并需要先前的上下文时使用。

## 概述（中文）

为人工智能代理提供安全保障的持久内存系统。通过知识图、衰减、矛盾检测以及带有 Iron Dome 行为保护的 6 层防御管道来记住跨会话的决策、偏好、架构和上下文。当被要求“记住这一点”、“我们知道什么”、“调用上下文”、“扫描威胁”、“运行安全审核”、“检查内存统计信息”时，或者在开始新会话并需要先前的上下文时使用。

## 原文

# ShieldCortex — Persistent Memory & Security for AI Agents

Give your agent a brain that persists between sessions and protect it from memory poisoning attacks.

## Safety & Scope

- This skill documents a local memory/security tool. It does not auto-install packages or silently execute shell commands.
- Any install command shown here is a manual setup step for the user to approve and run explicitly.
- Local ShieldCortex usage does not require credentials. API keys are optional and only needed for ShieldCortex Cloud.
- Only scan instruction files or other prompts when the user has named the path or clearly asked for that review.
- `shieldcortex install` writes local MCP configuration; it does not deploy a remote service or request background privileges.

## When to Use This Skill

- You want to remember things between sessions (decisions, preferences, architecture, context)
- You need to recall relevant past context at the start of a session
- You want knowledge graph extraction from memories (entities, relationships)
- You need to protect memory from prompt injection or poisoning attacks
- You want credential leak detection in memory writes
- You want to audit what has been stored in and retrieved from memory
- You want to scan instruction files (SKILL.md, .cursorrules, CLAUDE.md) for threats

## Setup

Install the npm package globally, then configure the MCP server, only when the user explicitly wants ShieldCortex enabled:

```bash
npm install -g shieldcortex
shieldcortex install
```

Python SDK also available:

```bash
pip install shieldcortex
```

## Core Workflow

### Session Start

At the start of every session, retrieve prior context:

1. Call `start_session` to begin a new session and get relevant memories
2. Or call `get_context` with a query describing the current task

### Remembering

Call `remember` immediately when any of these happen:

- **Architecture decisions** — "We're using PostgreSQL for the database"
- **Bug fixes** — capture root cause and solution
- **User preferences** — "Always use TypeScript strict mode"
- **Completed features** — what was built and why
- **Error resolutions** — what broke and how it was fixed
- **Project context** — tech stack, key patterns, file structure

Parameters:
- `title` (required): Short summary
- `content` (required): Detailed information
- `category`: architecture, pattern, preference, error, context, learning, todo, note
- `importance`: low, normal, high, critical
- `project`: Scope to a specific project (auto-detected if omitted)
- `tags`: Array of tags for categorisation

### Recalling

Call `recall` to search for past memories:

- `mode: "search"` — query-based semantic search (default)
- `mode: "recent"` — most recent memories
- `mode: "important"` — highest-salience memories

Filter by `category`, `tags`, `project`, or `type` (short_term, long_term, episodic).

### Forgetting

Call `forget` to remove outdated or incorrect memories:

- Delete by `id` for a specific memory
- Delete by `query` to match content
- Always use `dryRun: true` first to preview what will be deleted
- Use `confirm: true` for bulk deletions

### Session End

Call `end_session` with a summary to trigger memory consolidation. This promotes short-term memories to long-term and runs decay on old, unaccessed memories.

## Knowledge Graph

ShieldCortex automatically extracts entities and relationships from memories.

- `graph_query` — traverse from an entity, returns connected entities up to N hops
- `graph_entities` — list known entities, filter by type (person, tool, concept, file, language, service, pattern)
- `graph_explain` — find the path connecting two entities

Use the knowledge graph to understand relationships between concepts, technologies, and decisions across the project.

## Memory Intelligence

- `consolidate` — merge duplicate/similar memories, run decay. Use `dryRun: true` to preview
- `detect_contradictions` — find conflicting memories (e.g., "use Redis" vs "don't use Redis")
- `get_related` — find memories connected to a specific memory ID
- `link_memories` — create explicit relationships (references, extends, contradicts, related)
- `memory_stats` — view total counts, category breakdown, decay stats

## Security & Defence

Every memory write passes through a 6-layer defence pipeline:

1. Input Sanitisation — strips control characters and null bytes
2. Pattern Detection — regex matching for known injection patterns
3. Semantic Analysis — embedding similarity to attack corpus
4. Structural Validation — JSON/format integrity checks
5. Behavioural Scoring — anomaly detection over time
6. Credential Leak Detection — blocks API keys, tokens, private keys (25+ patterns, 11 providers)

### Iron Dome

Behavioural security layer that controls what agents can do, not just what they remember:

- `iron_dome_activate` — activate with a profile: `school`, `enterprise`, `personal`, or `paranoid`
- `iron_dome_status` — check active profile, trusted channels, and approval rules
- `iron_dome_check` — gate an action (e.g., send_email, delete_file) before execution
- `iron_dome_scan` — scan text for prompt injection patterns

Profiles control action gates (what actions require approval), channel trust (which instruction sources are trusted), and approval rules.

### Security Tools

- `audit_query` — query the forensic audit log of all memory operations
- `defence_stats` — view defence system statistics (blocks, allows, quarantines)
- `quarantine_review` — review and manage quarantined memories (list, approve, reject)
- `scan_memories` — scan existing memories for signs of poisoning
- `scan_skill` — scan an instruction file for hidden threats (SKILL.md, .cursorrules, CLAUDE.md, etc.)

## Universal Memory Bridge

ShieldCortex can act as a security layer for any memory backend — not just its own. Use `ShieldCortexGuardedMemoryBridge` to wrap any memory system with the full defence pipeline:

```javascript
import { ShieldCortexGuardedMemoryBridge, MarkdownMemoryBackend } from 'shieldcortex';

const bridge = new ShieldCortexGuardedMemoryBridge({
  backend: new MarkdownMemoryBackend('~/.my-memories/'),
});

// All writes pass through the 6-layer defence pipeline
await bridge.write({ title: 'Decision', content: 'Use PostgreSQL' });
```

Built-in backends: `MarkdownMemoryBackend`, `OpenClawMarkdownBackend`. Implement the backend interface for custom storage.
ShieldCortex does not auto-discover remote backends or obtain their credentials; the host application must wire that in explicitly.

## Project Scoping

- `set_project` — switch active project context
- `get_project` — show current project scope
- Use `project: "*"` for global/cross-project memories

## Best Practices

1. **Remember immediately** — call `remember` right after a decision is made or a bug is fixed, not at the end of the session
2. **Use categories** — architecture, pattern, preference, error, context, learning
3. **Set importance** — mark critical decisions as `importance: "critical"` so they resist decay
4. **Recall at session start** — always call `get_context` or `start_session` first
5. **End sessions properly** — call `end_session` with a summary to trigger consolidation
6. **Review contradictions** — periodically run `detect_contradictions` to catch conflicting information
7. **Scope by project** — memories are automatically scoped to the current project directory

## Troubleshooting

**Memory not found in recall:**
- Try `mode: "search"` with different query phrasing
- Check `set_project` — you may be searching the wrong project scope
- Use `includeDecayed: true` to find memories that have faded

**Memory blocked by firewall:**
- The defence pipeline detected a potential threat (injection, credential leak)
- Check `audit_query` for the specific block reason
- Review with `quara