Noosphere Memory for OpenClaw

OpenClaw plugin for Noosphere memory over HTTP. It provides explicit memory tools, optional prompt-time auto-recall, and an optional shared memory corpus supplement.

Install

Use OpenClaw's plugin installer:

openclaw plugins install npm:@sweetsophia/[email protected] --pin

For the full local Noosphere + OpenClaw setup, first confirm that the coordinated v1.13.3 release exists with all six installer assets. Source merge alone does not publish the image, package, or release assets. Then use the checksum-verifying download form below; it runs the guided 1.13.3 launcher non-interactively for OpenClaw.

It verifies the reviewed launcher and backend before configuring OpenClaw through its protected file secret provider. For the full lifecycle and auditable download, see Installing Noosphere. Guided setup creates a separate OpenClaw WRITE key, never the bootstrap ADMIN key. The key is unrestricted across corpus scopes by default so ordinary saves without restrictedTags work; apply restricted scopes only together with matching integration tags.

# Installer commit: 4468cbb160c1b5eb98d42662229287be013692d7
# Expected SHA-256: 781c1f635082aefaf62910bc2d973e22809ca690ef30a1c3a7143e8c9441e283
(
  set -e
  installer="$(mktemp)"
  trap 'rm -f "$installer"' EXIT
  curl -fsSL https://raw.githubusercontent.com/SweetSophia/noosphere/4468cbb160c1b5eb98d42662229287be013692d7/install.sh -o "$installer"
  printf '%s  %s\n' '781c1f635082aefaf62910bc2d973e22809ca690ef30a1c3a7143e8c9441e283' "$installer" | sha256sum -c -
  NOOSPHERE_VERSION="${NOOSPHERE_VERSION:-1.13.3}" NOOSPHERE_PLUGIN_SPEC="${NOOSPHERE_PLUGIN_SPEC:-npm:@sweetsophia/[email protected]}" bash "$installer" --non-interactive --with openclaw
)

Configuration

Store API keys outside repository files. The plugin accepts a default API key and per-agent keys:

{
  plugins: {
    entries: {
      "noosphere-memory": {
        enabled: true,
        config: {
          baseUrl: "http://127.0.0.1:6578",
          apiKey: { source: "file", provider: "noosphere-memory", id: "/apiKey" },
          autoRecall: true,
          autoProviders: ["noosphere"],
          maxInjectedMemories: 10,
          maxInjectedTokens: 1000,
          recallInjectionPosition: "system-prepend",
          autoRecallTimeoutMs: 5000
        },
        hooks: {
          allowPromptInjection: true
        }
      }
    }
  }
}

For multi-agent installs, prefer environment variables:

NOOSPHERE_API_KEY_CYLENA=noo_...
NOOSPHERE_API_KEY_SHODAN=noo_...

The plugin resolves keys in this order:

1. NOOSPHERE_API_KEY_<AGENT_ID>
2. config.apiKeys[agentId]
3. default config.apiKey / OPENCLAW_NOOSPHERE_API_KEY / NOOSPHERE_API_KEY

Use OPENCLAW_NOOSPHERE_* for OpenClaw-wide defaults on machines that also run Opencode, Kilo Code, or Hermes. The generic NOOSPHERE_* variables remain compatibility fallbacks.

Remote origin binding

Loopback deployments (localhost, 127.0.0.0/8, or ::1) need no additional configuration. For a remote deployment, bind the API credential to the exact HTTPS origin in the protected OpenClaw process environment:

OPENCLAW_NOOSPHERE_TRUSTED_ORIGIN=https://memory.example.com

The value is a single origin: scheme, host, and optional port only—no path, query, fragment, or credentials. NOOSPHERE_TRUSTED_ORIGIN is the compatibility fallback. The OpenClaw-specific variable takes precedence when both are set.

Keep this variable with the API key in the service environment. If you use another administrator-controlled secret/configuration source, it must inject the variable into the protected OpenClaw process environment. Do not put it in plugin configuration: an actor able to change config.baseUrl must not also authorize the replacement destination. Missing, malformed, or mismatched remote origin configuration stops plugin initialization with a configuration error; it never silently redirects authenticated requests to localhost. The client also rejects HTTP redirects so credentialed request bodies cannot cross to another origin.

Tools

• noosphere_recall searches durable memory.
• noosphere_get retrieves one memory result by canonical ref or provider/id.
• noosphere_save creates a draft memory candidate.
• noosphere_article_create creates a curated wiki article.
• noosphere_topics lists visible topics for the caller's scopes.
• noosphere_topic_create creates a topic or subtopic. It requires an ADMIN Noosphere API key because topic taxonomy changes affect every caller.
• noosphere_status checks health/status. Full memory status requires ADMIN.

Scoped API keys can only assign scopes they already have. When a scoped key saves without restrictedTags, Noosphere defaults the saved content to that key's allowed scopes.

A narrow key is a READ or WRITE key whose allowedScopes contain only the agent, project, or corpus segment that should be visible to that caller. Avoid using an ADMIN key or a key with * scope for routine agent recall/save operations.

Auto-Recall

Set autoRecall: true and hooks.allowPromptInjection: true to enable before_prompt_build recall injection. The plugin config is the local enable gate: Noosphere DB settings can further disable or tune auto-recall, but cannot turn it on when the plugin config has autoRecall: false.

Auto-recall resolves the API key per agent for each hook invocation. This keeps prompt-time recall within the same scope boundaries as explicit tool calls.

When memoryCaptureInstructionsEnabled is enabled, the hook keeps the static noosphere_save guidance in the prompt when a successful recall returns no matches. Empty responses that report a provider error still fail open and inject nothing. This closes the clean recall-miss gap where agents previously received no reminder to save genuinely new durable information. The guidance remains advisory; it does not perform an automatic save.

This is the implemented Phase 0 behavior. The opt-in automatic-capture and recall-enrichment phases are tracked in the Automatic Memory Capture and Recall Enrichment ADR.

Corpus Supplement

The shared memory corpus supplement is disabled by default because some OpenClaw hosts do not provide per-agent identity to corpus calls. To intentionally use the default API key for shared corpus access, set:

{
  config: {
    allowDefaultCorpusSupplement: true
  }
}

Use a narrow default key if you enable this. The default corpus key should be READ-only when the shared corpus is used for search only, and its scopes should exclude private agent/project memory that other agents must not see.

Release Tags

Package releases use package-specific tag prefixes so independent packages do not trigger each other's publish jobs:

• v-openclaw-1.13.3 publishes @sweetsophia/[email protected] first, then @sweetsophia/[email protected] after exact integrity readback
• v-opencode-1.13.3 publishes @sweetsophia/[email protected]
• v-kilocode-1.13.3 publishes @sweetsophia/[email protected]
• v-mcp-1.13.3 publishes @sweetsophia/[email protected]
• v-hermes-1.13.3 produces the deterministic Hermes workflow artifact; the trusted release publisher attaches that archive and checksum to v1.13.3 after independent readback

New plugin packages should add their own v-{package}-* tag prefix in CI before they are published.