npm package: @fidelius-ai/openclaw-memory
Description: OpenClaw Fidelius cognitive memory plugin with auto-recall/capture
Latest version: 2026.2.23

# Fidelius Memory

OpenClaw plugin that replaces the built-in memory system with [Fidelius AI](https://fidelius.ai)'s cognitive memory backend. Provides semantic recall, auto-capture, personality profiling, and a digital twin system that enables confidence-bounded autonomous agent behavior.

## Quick Start

```bash
# Switch to Fidelius memory (interactive setup with OAuth device flow)
openclaw memory use fidelius

# Verify connection
openclaw fidelius health

# Search memories from CLI
openclaw memory search "last meeting with Alex"

# Revert to built-in memory
openclaw memory use builtin
```

## Features

- **Auto-Recall** — Injects relevant memories before each agent turn via contextual reflect with automatic reflect fallback
- **Auto-Capture** — Ingests conversations after each agent run with graph integration
- **Session Capture** — Captures previous session on `/new` or `/reset` commands
- **Personality Profiling** — Dynamic personality injection adapted to conversation tone, channel, and recipient
- **Workspace Sync** — Writes personality insights to `SOUL.md` and `USER.md` with file locking and daily caps
- **Feedback Loop** — Detects explicit and implicit user corrections via regex heuristics and sends typed reinforcement signals
- **Digital Twin** — Server-decided policy gating with cached policy snapshots, per-tool action gating, message simulation, and decision/tool outcome feedback loops
- **LLM Observability** — Per-session LLM input/output tracking and analytics
- **Offline Queue** — JSONL-backed retry queue for failed ingests with configurable retry intervals
- **OAuth2 Authentication** — Device flow, authorization code (mobile), messaging-link, token relay
- **Safe Runtime Context** — `app_context` is bounded and sanitized before contextual recall requests

## Configuration

Set via `openclaw config set plugins.entries.fidelius-memory.config.<key> <value>` or directly in `~/.openclaw/config.json5`:

```json5
{
  plugins: {
    entries: {
      "fidelius-memory": {
        enabled: true,
        config: {
          url: "https://api.fidelius.ai/v1",
          timeout: 30000,
          maxRetries: 2,

          autoRecall: true,
          autoCapture: true,
          citations: "auto",

          ingest: {
            confidenceThreshold: 0.6,
            tags: [],
            maxMessagesPerIngest: 50,
          },

          profile: {
            enabled: true,
            workspaceSync: {
              enabled: true,
              targets: ["SOUL.md", "USER.md"],
              mode: "auto",
              minConfidence: 0.7,
              maxWritesPerDay: 3,
            },
          },

          feedback: {
            enabled: true,
          },

          sessionCapture: {
            enabled: true,
            maxMessages: 15,
          },

          compactionCapture: {
            enabled: true,
            messageThreshold: 40,
            extraction: {
              enabled: true,
              minMessages: 10,
              maxMessages: 0,
            },
          },

          offline: {
            enabled: true,
            maxQueueSize: 100,
            retryIntervalMs: 60000,
            maxRetries: 5,
          },

          twin: {
            enabled: true,
            policyGate: {
              timeoutMs: 5000,
              cacheFreshTtlMs: 60000,
              cacheStaleTtlMs: 300000,
            },
            feedback: {
              captureOutcomes: true,
            },
            toolOutcomeCapture: {
              enabled: true,
              maxBufferSize: 200,
              excludeTools: [],
            },
            diagnosticTools: {
              enabled: false,
            },
          },

          workspace: {
            enabled: true,
            timeoutMs: 500,
            includeReadme: true,
            includeCommits: true,
            commitCount: 5,
          },

          llmObservability: {
            enabled: true,
            analytics: true,
          },

          oauth: {
            clientId: "fid_pub_openclaw",
            issuerUrl: "https://auth.fidelius.ai",
            mobileCallbackUri: "openclaw://oauth-callback",
          },
        },
      },
    },
  },
}
```

### Configuration Reference

| Key                                        | Type                           | Default                      | Description                                          |
| ------------------------------------------ | ------------------------------ | ---------------------------- | ---------------------------------------------------- |
| `url`                                      | string                         | `https://api.fidelius.ai/v1` | Fidelius API base URL                                |
| `timeout`                                  | number                         | `30000`                      | Request timeout in ms                                |
| `maxRetries`                               | number                         | `2`                          | SDK retry count                                      |
| `autoRecall`                               | boolean                        | `true`                       | Inject memory context in `before_agent_start`        |
| `autoCapture`                              | boolean                        | `true`                       | Ingest conversation payloads on lifecycle boundaries |
| `citations`                                | `"auto" \| "on" \| "off"`      | `"auto"`                     | Citation output mode                                 |
| `ingest.confidenceThreshold`               | number                         | `0.6`                        | Ingest confidence threshold                          |
| `ingest.tags`                              | string[]                       | `[]`                         | Default ingest tags                                  |
| `ingest.maxMessagesPerIngest`              | number                         | `50`                         | Max messages per ingest payload                      |
| `profile.enabled`                          | boolean                        | `true`                       | Enable profile sync behaviors                        |
| `profile.workspaceSync.enabled`            | boolean                        | `true`                       | Enable workspace file sync                           |
| `profile.workspaceSync.targets`            | string[]                       | `["SOUL.md", "USER.md"]`     | Workspace files to sync                              |
| `profile.workspaceSync.mode`               | `"auto" \| "propose" \| "off"` | `"auto"`                     | Write/propose/off behavior                           |
| `profile.workspaceSync.minConfidence`      | number                         | `0.7`                        | Confidence floor for writes                          |
| `profile.workspaceSync.maxWritesPerDay`    | number                         | `3`                          | Daily write cap per target                           |
| `feedback.enabled`                         | boolean                        | `true`                       | Enable correction-feedback emission                  |
| `sessionCapture.enabled`                   | boolean                        | `true`                       | Enable capture on `before_reset`                     |
| `sessionCapture.maxMessages`               | number                         | `15`                         | Max messages captured on reset                       |
| `compactionCapture.enabled`                | boolean                        | `true`                       | Enable pre-compaction workflows                      |
| `compactionCapture.messageThreshold`       | number                         | `40`                         | Message-count threshold tag for compaction ingest    |
| `compactionCapture.extraction.enabled`     | boolean                        | `true`                       | Enable pre-compaction extraction run                 |
| `compactionCapture.extraction.minMessages` | number                         | `10`                         | Minimum messages before extraction                   |
| `compactionCapture.extraction.maxMessages` | number                         | `0`                          | Extraction max messages (`0` means unbounded)        |
| `offline.enabled`                          | boolean                        | `true`                       | Enable offline retry queue                           |
| `offline.maxQueueSize`                     | number                         | `100`                        | Queue capacity                                       |
| `offline.retryIntervalMs`                  | number                         | `60000`                      | Queue retry interval                                 |
| `offline.maxRetries`                       | number                         | `5`                          | Max retries per queued item                          |
| `twin.enabled`                             | boolean                        | `true`                       | Enable twin hooks and policy gate                    |
| `twin.policyGate.timeoutMs`                | number                         | `5000`                       | Policy fetch timeout                                 |
| `twin.policyGate.cacheFreshTtlMs`          | number                         | `60000`                      | Fresh cache TTL                                      |
| `twin.policyGate.cacheStaleTtlMs`          | number                         | `300000`                     | Stale-while-revalidate TTL                           |
| `twin.feedback.captureOutcomes`            | boolean                        | `true`                       | Capture decision outcomes for relay                  |
| `twin.toolOutcomeCapture.enabled`          | boolean                        | `true`                       | Enable `after_tool_call` outcome buffer              |
| `twin.toolOutcomeCapture.maxBufferSize`    | number                         | `200`                        | Max outcomes retained per session scope              |
| `twin.toolOutcomeCapture.excludeTools`     | string[]                       | `[]`                         | Tool names excluded from outcome capture             |
| `twin.diagnosticTools.enabled`             | boolean                        | `false`                      | Enable diagnostic tool set                           |
| `workspace.enabled`                        | boolean                        | `true`                       | Enable workspace snapshot prompt context             |
| `workspace.timeoutMs`                      | number                         | `500`                        | Workspace snapshot timeout                           |
| `workspace.includeReadme`                  | boolean                        | `true`                       | Include README in workspace snapshot                 |
| `workspace.includeCommits`                 | boolean                        | `true`                       | Include recent commits in workspace snapshot         |
| `workspace.commitCount`                    | number                         | `5`                          | Number of commits to include                         |
| `llmObservability.enabled`                 | boolean                        | `true`                       | Enable LLM observability hooks                       |
| `llmObservability.analytics`               | boolean                        | `true`                       | Enable analytics output                              |
| `oauth.clientId`                           | string                         | `fid_pub_openclaw`           | OAuth client ID                                      |
| `oauth.issuerUrl`                          | string                         | `https://auth.fidelius.ai`   | OAuth issuer base URL                                |
| `oauth.mobileCallbackUri`                  | string                         | `openclaw://oauth-callback`  | Mobile OAuth callback URI                            |

## Tools

The plugin registers **22 agent tools**:

- **12 always-on tools**
- **10 diagnostic tools** gated by `twin.enabled && twin.diagnosticTools.enabled` (default: `false`)

### Always-On Tools

| Tool                 | Description                                                                                                         |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `memory_search`      | Semantic memory search across Fidelius networks                                                                     |
| `memory_get`         | Retrieve details for a source from the latest recall context                                                        |
| `memory_feedback`    | Forward user correction signals to Fidelius                                                                         |
| `memory_decisions`   | Search decision patterns, update outcomes, or trace decision lineage (actions: `search`, `update_outcome`, `trace`) |
| `memory_workflows`   | Search learned workflow patterns                                                                                    |
| `memory_social`      | Search contacts, fetch a contact, or update relationship fields (actions: `search`, `get`, `update`)                |
| `memory_episodes`    | Search or list episodic memories (actions: `search`, `list`)                                                        |
| `memory_profile`     | Show personality profile, force evaluation, or read self-schema (actions: `status`, `evaluate`, `self_schema`)      |
| `memory_twin_policy` | Fetch twin policy snapshot for a context                                                                            |
| `twin_gate_check`    | Explicit preflight check for planned external actions                                                               |

### Diagnostic Tools

| Tool                   | Description                                                                                                 |
| ---------------------- | ----------------------------------------------------------------------------------------------------------- |
| `memory_recall`        | Deep memory recall with graph traversal/reranking controls                                                  |
| `memory_twin_analysis` | Simulate actions, check drift, or evaluate counterfactuals (actions: `simulate`, `drift`, `counterfactual`) |
| `memory_ce`            | Generate memory-grounded implementation plans                                                               |

## Digital Twin System

The twin subsystem enforces server-evaluated policy decisions and applies them consistently across tool and message flows.

### Runtime Modes

| Mode          | Behavior                       |
| ------------- | ------------------------------ |
| `"twin"`      | Least restrictive runtime mode |
| `"assisted"`  | Intermediate runtime mode      |
| `"assistant"` | Most restrictive runtime mode  |

Mode is determined by the server based on confidence scoring. It cannot be overridden by client configuration.

### Action Gating

Twin action gating is server-decision-first:

- The server policy response provides `actionDecision` (`allow`, `hedge`, `block`) and `overallConfidence`
- The client caches a normalized policy snapshot and uses stale-while-revalidate cache windows
- Fresh cache TTL defaults to 60s (`twin.policyGate.cacheFreshTtlMs`)
- Stale cache TTL defaults to 5m (`twin.policyGate.cacheStaleTtlMs`)
- `routeAction()` is a pure switch on `snapshot.actionDecision` (no client-side score blending)
- Fail-safe behavior is restrictive: server-unreachable snapshots resolve to block with confidence `0`

### Message Simulation

Outgoing messages on messaging channels pass through `message_sending` hook simulation:

- Twin simulate scores the candidate message for alignment
- When rewrite suggestions are provided, the first suggestion is applied
- Low-alignment warnings are logged for observability

### Lifecycle

1. **Session start** (`session_start`): SDK pre-warm, session-state reset, optional workspace sync kickoff
2. **Before agent turn** (`before_agent_start`): lazy SDK init, auth-link handling, parallel reflect + policy snapshot fetch
3. **Prompt build** (`before_prompt_build`): inject twin policy preamble, workspace context, and cached behavior guidance
4. **Per-tool** (`before_tool_call` / `after_tool_call`): action gating, decision tracking, tool outcome capture, recent-result buffering
5. **Per-LLM call** (`llm_input` / `llm_output`): LLM usage and analytics tracking
6. **Message flow** (`message_sending` / `message_received`): outgoing simulation and inbound memory prefetch
7. **Session/agent end** (`session_end` / `agent_end`): ingest, tool outcome flush, decision outcome drain, feedback emission
8. **Reset/compaction** (`before_reset` / `before_compaction`): state invalidation, session capture, queue flush, extraction

## Lifecycle Hooks

The plugin registers **19 hook registrations across 13 event names**.

| Event                 | Registrations | Actions                                                                        |
| --------------------- | ------------- | ------------------------------------------------------------------------------ |
| `before_tool_call`    | 1             | Twin action gating and block/hedge enforcement                                 |
| `after_tool_call`     | 2             | Tool outcome capture; recent tool result buffering                             |
| `llm_input`           | 1             | LLM observability input tracking                                               |
| `llm_output`          | 1             | LLM observability output tracking                                              |
| `message_sending`     | 1             | Outgoing twin simulation/rewrite                                               |
| `message_received`    | 1             | Inbound memory prefetch                                                        |
| `before_prompt_build` | 3             | Twin policy preamble; workspace prompt context; cached behavior guidance       |
| `session_start`       | 1             | SDK pre-warm, state reset, workspace sync/manual-edit checks                   |
| `session_end`         | 1             | Conversation ingest, tool outcome flush, session close notification            |
| `before_agent_start`  | 1             | SDK init/auth link, parallel contextual reflect + policy fetch                 |
| `agent_end`           | 3             | Decision outcome drain; tool outcome flush; ingest + feedback + workspace sync |
| `before_reset`        | 2             | Twin state invalidation; differential session capture                          |
| `before_compaction`   | 1             | Queue flush and pre-compaction extraction                                      |

## CLI Commands

```bash
openclaw fidelius auth login [--signup]    # Authenticate via OAuth device flow
openclaw fidelius auth status              # Show authentication status
openclaw fidelius auth logout              # Revoke tokens and clear storage

openclaw fidelius status                   # Show connection status and queue info
openclaw fidelius health                   # Check backend connectivity and latency
openclaw fidelius reflect <query>          # Search memories from CLI
openclaw fidelius queue [--flush]          # Show or flush offline retry queue

openclaw fidelius profile apply-workspace  # Force apply personality to workspace files
openclaw fidelius profile preview-workspace-diff  # Preview workspace changes without writing

openclaw fidelius sharing status           # Show active sharing permissions
openclaw fidelius sharing manage           # Open consent management in browser

openclaw fidelius setup --self-hosted      # Register OAuth app with self-hosted instance

openclaw memory use fidelius [options]     # Switch to Fidelius memory
openclaw memory use builtin                # Revert to built-in memory
openclaw memory provider                   # Show active memory provider
openclaw memory status [--json] [--deep]  # Show status (--deep tests connectivity)
openclaw memory search <query> [options]  # Search from CLI
openclaw memory index                      # No-op (indexing is server-side)

/twin                                      # Slash command: show digital twin status
```

## Authentication

The plugin supports multiple OAuth2 flows:

| Flow                          | Use Case                                                      |
| ----------------------------- | ------------------------------------------------------------- |
| **Device flow**               | CLI login (`fidelius auth login`)                             |
| **Authorization code + PKCE** | Mobile apps via gateway BFF                                   |
| **Messaging link**            | In-chat auth for messaging channels (Telegram, Discord, etc.) |
| **Token relay**               | Mobile token forwarding via WebSocket                         |

Tokens are stored in `~/.openclaw/` (or legacy `~/.clawdbot/`) and automatically refreshed via the SDK's `onTokenRefresh` callback.

### Required OAuth Scopes

| Scope            | Used By                                                                                    |
| ---------------- | ------------------------------------------------------------------------------------------ |
| `memory:reflect` | Recall/search tools (`memory_search`, `memory_recall`, `memory_episodes`, `memory_ce`)     |
| `memory:write`   | Feedback and decision outcome tools (`memory_feedback`, `memory_decisions:update_outcome`) |
| `memory:read`    | Decision/workflow/social/profile tools                                                     |
| `memory:shared`  | Shared memory access                                                                       |
| `graph:read`     | Counterfactual/trace and graph-backed operations                                           |
| `offline_access` | Refresh token support                                                                      |

## HTTP Routes & Gateway Methods

| Endpoint/Method                       | Type       | Purpose                                                                                                                                               |
| ------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/fidelius/policy-invalidated`    | HTTP POST  | Policy cache invalidation webhook (HMAC-SHA256 verified, event-id deduplication, revision-based stale-event rejection, scoped cache clear/invalidate) |
| `/api/fidelius/messaging-callback`    | HTTP GET   | OAuth callback for messaging-channel authentication                                                                                                   |
| `fidelius:token-relay`                | Gateway WS | Accept token from mobile app                                                                                                                          |
| `ext:fidelius-memory:mobile-auth-url` | Gateway WS | Generate OAuth authorization URL for mobile                                                                                                           |
| `ext:fidelius-memory:oauth-callback`  | Gateway WS | Exchange authorization code from mobile                                                                                                               |

Webhook auth headers for `/api/fidelius/policy-invalidated`:

- `x-fidelius-signature`: `sha256=<hex hmac>` of `<timestamp>.<rawBody>`
- `x-fidelius-timestamp`: unix timestamp used in signature payload
- `x-fidelius-event-id`: optional idempotency key for deduplication window

## Services

| Service ID            | Description                                                                                                            |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `fidelius-memory`     | Core service: token loading, SDK client init, offline queue, twin action gate, taxonomy cache, correction signal cache |
| `fidelius-sleep-time` | Idle-triggered policy consolidation with drift detection                                                               |

## File Structure

```text
extensions/fidelius-memory/
  index.ts
  README.md
  DIGITAL_TWIN_ARCHITECTURE.md

  cli/            # Command and slash-command registration
  core/           # Config schema, runtime context, SDK lifecycle, shared helpers
  hooks/          # Lifecycle hook registrars
  tools/          # Agent tools (always-on + diagnostic)
  twin/           # Twin action gate, policy formatting, caches, decision tracking
  workspace/      # Workspace snapshot + SOUL/USER sync
  feedback/       # Feedback emit/cooldown logic
  http/           # HTTP routes and gateway method registration
  services/       # Plugin services
  observability/  # LLM observability handlers
  setup/          # Setup wizard and consent helpers
  oauth/          # OAuth flows, discovery, token store
  scripts/        # Build/schema generation scripts
  skills/         # Optional skill docs for runtime usage
```

## Dependencies

| Package             | Purpose                                               |
| ------------------- | ----------------------------------------------------- |
| `@fidelius-ai/sdk`  | Fidelius API client (memory, twin, profile, sessions) |
| `@clack/prompts`    | Interactive CLI prompts for setup and auth flows      |
| `@sinclair/typebox` | Tool parameter schemas                                |
| `proper-lockfile`   | File locking for workspace sync writes                |
| `zod`               | Config schema validation and JSON schema generation   |

## Testing

```bash
# Run all fidelius-memory extension tests
pnpm vitest run --config vitest.extensions.config.ts extensions/fidelius-memory/

# Run focused module tests
pnpm vitest run --config vitest.extensions.config.ts extensions/fidelius-memory/twin/action-gate.test.ts
pnpm vitest run --config vitest.extensions.config.ts extensions/fidelius-memory/hooks/reset-compaction.test.ts
pnpm vitest run --config vitest.extensions.config.ts extensions/fidelius-memory/http/policy-invalidated-route.test.ts
pnpm vitest run --config vitest.extensions.config.ts extensions/fidelius-memory/workspace/sync.test.ts
```

## Self-Hosted Setup

For self-hosted Fidelius instances:

```bash
# Register an OAuth app
openclaw fidelius setup --self-hosted

# Or configure manually
openclaw config set plugins.entries.fidelius-memory.config.url "https://your-instance.com/v1"
openclaw config set plugins.entries.fidelius-memory.config.oauth.clientId "your-client-id"
openclaw config set plugins.entries.fidelius-memory.config.oauth.issuerUrl "https://your-instance.com"

# Then authenticate
openclaw fidelius auth login
```

## Environment Variables

| Variable                                     | Purpose                                                   |
| -------------------------------------------- | --------------------------------------------------------- |
| `FIDELIUS_OAUTH_CLIENT_ID`                   | Override default OAuth client ID                          |
| `FIDELIUS_ISSUER_URL`                        | Override default OAuth issuer URL                         |
| `FIDELIUS_POLICY_INVALIDATION_SECRET`        | HMAC shared secret for policy invalidation webhook        |
| `FIDELIUS_POLICY_INVALIDATION_TOLERANCE_SEC` | Max allowed timestamp skew in seconds (default: `300`)    |
| `FIDELIUS_POLICY_INVALIDATION_EVENT_TTL_SEC` | Event dedupe retention window in seconds (default: `600`) |
| `OPENCLAW_STATE_DIR`                         | Override state directory for token storage                |