Skip to main content

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 expose a public Bobbin-owned control-plane service. For the governed semantic-graph program it now also defines an optional internal semantic runtime foundation.

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

6. Internal semantic runtime foundation​

  • bobbin-semantic-api
  • bobbin-control-db
  • bobbin-reconciliation-worker
  • shadow-foundation health/readiness/status surfaces
  • inbox, visibility, audit, projection-state, and reconciliation-worker bootstrap foundations for later slices
  • BOB-RIGHTS-01 rights invalidation + traceable rebuild (jhf-bobbin#518, PLAN_SELVAGEv4.3.1 sections 13/13.1/13.2/26.2, umbrella jhf-selvage#112, W4): scripts/rights_invalidation.py is the single rights lane -- durable, content-addressed, idempotent intake; fail-closed ordering (stale revisions denied with evidence, erased subjects never rebuilt); per-surface graph/vector/context/cache invalidation receipts plus a traceable rebuild receipt; restriction holds that never erase; provider handoff that only ever writes pending_receipt. scripts/vector_rights_bridge.py closes the W8/S2 vector gap with a deterministic, domain-separated bvec- point identity and fail-closed tamper checks. bobbin_graph_worker calls rights_intake_gate before projecting; a denial records the same QUARANTINED failure state as a contract violation (evidence preserved in the inbox). The producer contracts are pinned, not copied: configs/selvage-rights-contract-pin.json + scripts/check_selvage_rights_contract_pin.py.
  • fail-closed K1 isolation-domain walls (jhf-bobbin#517, #546, PLAN_SELVAGEv4.3.1 section 7.3): isolation_domain_ref is a required, closed-catalog field on every structured event, graph node and context-graph request. Ingest quarantines a missing or unknown domain, both graph reads bind tenant hash plus the requested domain on every endpoint, and the row/edge exclusion layers drop anything outside the requested compartment without inventing a value for legacy rows. The single source of truth is configs/isolation-domain-catalog.json (the fifteen-domain plan baseline plus the governed customer_relationship extension). The explicit CRM legacy lane is source-bound and count-gated.

Data Flow​

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

Internal-only resident surfaces​

  • GET /healthz on bobbin-semantic-api
  • GET /readyz on bobbin-semantic-api
  • GET /api/v1/semantic/runtime/status on bobbin-semantic-api

The resident reconciliation worker remains internal-only in this slice. It polls projection_reconciliation_readback, applies bounded control-db admission reconciliation, graph-episode replay, visibility repairs, and checkpoint rebuild execution (reconcile_admission_from_write_intent, replay_graph_episode_from_write_intent, repair_namespace_visibility, repair_checkpoint_visibility, and rebuild_from_checkpoint), writes receipts into projection_reconciliation_receipts, and publishes an atomic status snapshot into the shared runtime-state volume.

Before either resident service starts, the internal one-shot bobbin-graph-schema-init service waits for the graph-store's local, credential-free HTTP healthcheck and then applies and verifies only Bobbin's fixed entity-identity constraint plus German and neutral fulltext indexes through authenticated container-network Neo4j Query API v2 access. Its requests use the admitted single statement request shape, negotiate JSON with Accept: application/json;charset=UTF-8, and send Content-Type: application/json. Rejected requests expose only a fixed schema-operation category, the allowlisted Neo4j code and the bounded phase; Cypher, endpoint, response body and credentials never enter the receipt. Local pre-HTTP failures such as missing auth or an invalid internal endpoint preserve the active operation phase as well, so the remote lifecycle consumer can classify the terminal redacted receipt instead of falling through to an unclassified sequence failure. Final integrity-readback failures preserve the same bounded phase/code chain. The API exposes only the resulting bounded integrity receipt; no endpoint accepts Cypher or publishes arbitrary schema metadata. Schema application has an explicit 45-second total budget inside the 60-second one-shot consumer contract; each query is capped at 10 seconds and retries stop at the deadline, so failure still emits a terminal redacted receipt instead of being killed mid-retry.

These surfaces and the paired control database bind to <internal-runtime-redacted> by default. Any broader exposure stays outside this repository-owned foundation slice and must be admitted later by the runtime owner.

The repository still exposes no public 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

Public Distribution Boundary​

Bobbin is public as source code and documentation, but its runtime role remains operator-owned.

That distinction matters for coordinated public distribution:

  • public source visibility is allowed
  • repo-owned release-surface remediation is verified on main
  • public runtime admission is not implied
  • jhf-weaver must keep Bobbin outside coordinated public_distributable stack-nightly membership until a separate owner admission decision exists

Expected Role Toward jhf-fabric​

Fabric should model this repository as:

  • a standalone supporting tool
  • runtime kind bundle
  • file- and script-described with an optional internal shadow-runtime foundation

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.