@fidelius-ai/openclaw-memory

v2026.2.23

Published

24 days ago

OpenClaw Fidelius cognitive memory plugin with auto-recall/capture

0High
0Medium
0Low

timatfidelius

openclaw openclaw-plugin memory cognitive-memory fidelius ai agent-memory

Fidelius Memory

OpenClaw plugin that replaces the built-in memory system with 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

# 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:

{
  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

Session start (session_start): SDK pre-warm, session-state reset, optional workspace sync kickoff
Before agent turn (before_agent_start): lazy SDK init, auth-link handling, parallel reflect + policy snapshot fetch
Prompt build (before_prompt_build): inject twin policy preamble, workspace context, and cached behavior guidance
Per-tool (before_tool_call / after_tool_call): action gating, decision tracking, tool outcome capture, recent-result buffering
Per-LLM call (llm_input / llm_output): LLM usage and analytics tracking
Message flow (message_sending / message_received): outgoing simulation and inbound memory prefetch
Session/agent end (session_end / agent_end): ingest, tool outcome flush, decision outcome drain, feedback emission
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

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

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

# 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:

# 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 |