Skip to main content

Architecture

Documentation Map​

Architecture

System Overview​

jhf-bobbin (Helpifyr Bobbin) is an operator bundle that adds a semantic memory layer to an existing OpenClaw deployment.

It does not replace OpenClaw and it does not run as its own resident control-plane service.

Main Components​

1. OpenClaw host​

  • agent runtime
  • workspace context
  • channel/runtime orchestration
  • memory-core fallback

2. Mem0 plugin layer​

  • community openclaw-mem0 fork
  • active semantic memory slot when enabled
  • recall/capture behavior routed through OpenClaw plugin loading

3. Embedding runtime​

  • LocalAI
  • OpenAI-compatible embeddings API
  • embedding model aliasing for the Mem0 path

4. Vector store​

  • Qdrant
  • collection bootstrap
  • payload filtering and indexed semantic lookup

5. Operator tooling from this repo​

  • bootstrap/install/reapply scripts
  • config patchers
  • rollback helpers
  • smoke and verification scripts
  • Fabric-facing metadata export and selfcheck

Data Flow​

flowchart LR
  A["OpenClaw agent turn"] --> B["openclaw-mem0 plugin"]
  B --> C["LocalAI /v1/embeddings"]
  B --> D["Qdrant collection"]
  D --> B
  B --> A
  A --> E["workspace markdown context"]
  A --> F["memory-core fallback"]

External And Internal Interfaces​

Internal​

  • OpenClaw config and extension path
  • memory slot switching between memory-core and openclaw-mem0
  • workspace markdown context files

External​

  • LocalAI HTTP endpoints
  • Qdrant HTTP endpoints
  • optional OpenAI-compatible LLM endpoint for the Mem0 LLM path

The repository itself exposes no HTTP API, webhook, queue, or MCP server.

Dependency Structure​

Hard​

  • existing OpenClaw host
  • LocalAI
  • Qdrant
  • Python 3
  • Bash
  • Docker/Compose for the main Linux path

Optional​

  • external Qdrant instead of local Qdrant
  • alternate OpenAI-compatible LLM endpoint
  • macOS local host mode

Failure Boundaries​

OpenClaw failure boundary​

  • wrong config paths, config shape drift, or slot drift break installation and runtime wiring
  • recovery path: reapply config, verify slot, or fall back to memory-core

Plugin failure boundary​

  • community fork drift or patch mismatch breaks Mem0 behavior
  • recovery path: reinstall pinned plugin ref and rerun patch/reapply flow

LocalAI failure boundary​

  • missing readiness, wrong model alias, or broken embeddings endpoint degrades semantic memory
  • recovery path: recover LocalAI runtime, verify model endpoint, rerun smoke checks

Qdrant failure boundary​

  • missing collection, wrong dimensions, or failed search path breaks memory persistence/recall
  • recovery path: rerun collection bootstrap and endpoint checks

Operator-tooling failure boundary​

  • script errors or stale docs break reproducibility, not the already running runtime by themselves
  • recovery path: repair repo-local scripts/docs and rerun bounded verification

Operating Assumptions​

  • Linux is the reference platform
  • macOS support should remain bounded and low-complexity
  • installer and reapply paths must remain reproducible from this repository
  • rollback to memory-core must remain possible
  • default CI must remain repo-local and not mutate a live host

Role In The Helpifyr Ecosystem​

This repository is a supporting tool, not a core product runtime.

Its job inside the Helpifyr landscape is to:

  • standardize semantic memory enablement for OpenClaw-based operations
  • document and verify runtime dependencies
  • provide machine-readable metadata for Fabric and later wiki aggregation

Expected Role Toward jhf-fabric​

Fabric should model this repository as:

  • a standalone supporting tool
  • runtime kind bundle
  • file- and script-described rather than service-discovered

Fabric should be able to read:

  • repository identity
  • capabilities
  • dependency lists
  • update and compatibility signals
  • gaps and integration blockers

Fabric should not directly control:

  • full host installation
  • reapply after update
  • rollback to memory-core
  • destructive Qdrant operations

Update-Safe Principle​

Never rely on one-off live mutations as the sole source of truth.

The expected install, reapply, rollback, and verification behavior must remain reconstructible from this repository.

AGPLv3. See ../LICENSE (LICENSE).

Learn more at helpifyr.com.