Harnesses

Harnesses are the AI platforms and tools that Signet integrates with through connectors, plugins, and lifecycle hooks.

For the end-to-end process of connecting a harness on one machine to a Signet daemon on another machine, see Remote Harness Connectors.

Path note: $SIGNET_WORKSPACE means your active Signet workspace path. Default is ~/.agents, configurable via signet workspace set <path>.

How Harness Sync Works

When you change $SIGNET_WORKSPACE/AGENTS.md:

1. The Daemon file watcher detects the change (within 2 seconds)
2. The daemon reads the new content
3. It prepends an auto-generated header identifying the source
4. It writes the result to each configured harness location

The header looks like this:

# CLAUDE.md
# ============================================================================
# AUTO-GENERATED from $SIGNET_WORKSPACE/AGENTS.md by Signet
# Generated: 2025-02-17T18:00:00.000Z
# 
# DO NOT EDIT THIS FILE - changes will be overwritten
# Edit the source file instead: $SIGNET_WORKSPACE/AGENTS.md
#
# Related documents:
#   - $SIGNET_WORKSPACE/SOUL.md (Personality & tone)
#   - $SIGNET_WORKSPACE/MEMORY.md (Working memory context)
#   - $SIGNET_WORKSPACE/agent.yaml (Configuration & settings)
#
# Memory commands: /remember <content> | /recall <query>
# ============================================================================

You can also trigger a manual re-sync:

curl -X POST http://localhost:3850/api/harnesses/regenerate

Lossless Working Memory Fidelity (Closure Wave)

This matrix is the source of truth for closure-wave fidelity and degraded mode expectations across harness paths.

Degraded mode rules:

• When a harness/runtime path cannot emit every lifecycle event, Signet must document the missing surface explicitly instead of implying full parity.
• Compaction/session-summary forced-refresh guarantees are currently full in TS daemon and degraded in daemon-rs shadow path.
• Watcher-driven harness identity sync (batched AGENTS.md / USER.md / MEMORY.md propagation, queued reruns during active sync, and generated SIGNET-ARCHITECTURE.md refresh) is currently full in the TS daemon and degraded in the daemon-rs shadow path, which does not yet own that watcher pipeline.
• Prompt-time anti-bleed scoping remains mandatory across all paths.

Claude Code

Claude Code is Anthropic’s official CLI for Claude. It reads configuration from ~/.claude/.

Files managed by Signet

Memory hooks

Signet writes Hooks to ~/.claude/settings.json that fire at session lifecycle events. The hooks call the Signet CLI, which routes requests through the daemon HTTP API:

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "signet hook session-start -H claude-code --project \"$(pwd)\"",
        "timeout": 3000
      }]
    }],
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "signet hook user-prompt-submit -H claude-code --project \"$(pwd)\"",
        "timeout": 7000
      }]
    }],
    "SessionEnd": [{
      "hooks": [{
        "type": "command",
        "command": "signet hook session-end -H claude-code",
        "timeout": 15000
      }]
    }]
  }
}

Prompt-submit timeout note: SIGNET_PROMPT_SUBMIT_TIMEOUT defaults to 5000 (daemon wait budget). Claude Code hook config adds a +2000ms grace buffer when written to settings.json, so the installed UserPromptSubmit timeout default is 7000.

Upgrade note: Claude Code hook timeouts are written to ~/.claude/settings.json at install/update time. Existing installs keep their previous timeout values until you rerun signet connect claude-code (or signet setup) to rewrite hook config.

SessionStart — loads memories and context, outputs them as text that Claude Code injects into the system prompt.

UserPromptSubmit — optionally loads per-prompt context (lighter weight than session start).

SessionEnd — automatically saves a session summary to memory.

Native memory bridge

Signet indexes Claude Code-owned memdir artifacts without rewriting them or turning them into Signet-authored rows. The daemon watches Claude Code entrypoint indexes and memory files under ~/.claude/projects/*/memory/, session memory under ~/.claude/session-memory/, and agent-scoped memory under ~/.claude/agent-memory/ and ~/.claude/agent-memory-local/. Matching content is exposed through Signet recall as native_memory results with Claude Code provenance. Removed native files are soft-deleted from active recall while preserving their artifact rows for lineage.

This replaces the older daemon-local Claude watcher that only read ~/.claude/projects/*/memory/MEMORY.md and pushed chunks back through /api/memory/remember. Claude Code remains the owner of those native files; Signet indexes them as artifacts.

Using /remember and /recall

In Claude Code sessions, use these commands directly:

/remember nicholai prefers bun over npm
/recall coding preferences

These work via the built-in skills in $SIGNET_WORKSPACE/skills/. The skill instructions tell Claude how to call the Signet daemon API.

MCP Tools

Claude Code also gets native MCP tool access to Signet memory via the signet-mcp stdio server, registered in ~/.claude/settings.json:

{
  "mcpServers": {
    "signet": {
      "type": "stdio",
      "command": "signet-mcp",
      "args": []
    }
  }
}

This gives Claude Code direct access to memory_search, session_search, memory_store, memory_get, memory_list, memory_modify, and memory_forget tools.

Prerequisites

• Claude Code installed and in PATH
• ~/.claude/ directory exists

Codex

Codex is OpenAI’s terminal coding agent (codex-rs). Signet integrates with Codex through a generated Codex plugin bundle when the installed Codex CLI supports plugin marketplaces. The plugin declares Signet metadata, skills, and MCP configuration. Until Codex exposes plugin lifecycle hooks, Signet also installs compatibility hooks.json entries for session start, prompt submit, and session end. Older Codex versions fall back to direct hook and MCP config patching.

Files managed by Signet

Native memory bridge

Signet indexes Codex-owned memory artifacts without rewriting them or turning them into Signet-authored memory rows. The daemon polls Codex memory files with content hashes under ~/.codex/memories/, including memory_summary.md, MEMORY.md, rollout summaries, skill memories, ad-hoc extension notes, and automation-local ~/.codex/automations/*/memory.md files. Matching content is indexed as codex_native_memory source artifacts with path, hash, line range, and rollout-id metadata when present. Removed native files are soft-deleted from active recall while preserving their artifact rows for lineage.

When Codex native memories are enabled, Signet’s Codex prompt hook reduces automatic injection of Codex-owned memory rows. Prompt-time context stays focused on high-value Signet material: cross-harness history, source-backed documents, ontology, explicit recalls, and accepted decisions. Explicit recall still uses daemon-side dedupe keyed by session_key, agent_id, and context_epoch.

How it works

1. signet setup --harness codex feature-detects codex plugin support.
2. On supported Codex installs, Signet writes a local plugin marketplace bundle and registers signet@signet-local in ~/.codex/config.toml.
3. While plugin lifecycle hooks are not available, Codex also reads compatibility hooks from ~/.codex/hooks.json.
4. On session start, Codex fires SessionStart → calls signet hook session-start -H codex --codex-json → Signet returns identity + memories as hookSpecificOutput.additionalContext with suppressOutput: true, injected into the model’s context window without printing the hook payload to the user transcript.
5. On every user prompt, Codex fires UserPromptSubmit → calls signet hook user-prompt-submit -H codex --codex-json → Signet returns bounded entity current-view context only when the prompt mentions a known entity or active alias. Empty matches return no additional context. This is blocking — Codex waits for the hook before sending to the model.
6. On session end, Codex fires Stop → calls signet hook session-end -H codex → Signet extracts memories from the transcript.
7. The MCP server exposes signet_recall, signet_source_search, signet_session_search, signet_save_note, and compatibility memory_* tools that Codex can invoke directly during sessions.

Codex SessionStart hook timeout defaults to 20 seconds: the Signet CLI waits up to SIGNET_SESSION_START_TIMEOUT (15000 ms by default) for the daemon, and the generated Codex hook config adds 5 seconds of harness grace. Codex UserPromptSubmit defaults to 7 seconds: SIGNET_PROMPT_SUBMIT_TIMEOUT (5000 ms by default) plus 2 seconds of harness grace. Rerun signet setup or signet connect codex after upgrading to rewrite an existing ~/.codex/hooks.json.

For a remote Signet daemon, pass --url and --api-key when installing the Codex connector:

signet api-key create --name "work laptop codex" --connector codex --agent-id <agent-name>
signet connect codex --url http://192.168.0.60:3850 --api-key sig_sk_...

Use --agent-id when creating the API key to bind the remote Codex install to one Signet agent. The key scope becomes the default agent for Codex hook/MCP requests, and requests for another agent are rejected by daemon auth scope.

Codex also has a native-plugin-oriented npm installer name for machines where you do not want to install the full Signet CLI first:

npx -y @signetai/codex-plugin install --url http://192.168.0.60:3850 --api-key sig_sk_...

When SIGNET_DAEMON_URL or --url is set, the Codex connector writes the plugin MCP URL, or compatibility [mcp_servers.signet] url = "<daemon>/mcp" when plugin support is unavailable, and bakes the same daemon URL into generated lifecycle hook commands. This keeps on-demand MCP tools and automatic lifecycle memory pointed at the same Signet instance. When an API key is provided, Codex MCP and lifecycle hook calls send it as bearer auth. The URL value must be the daemon origin only, for example http://192.168.0.60:3850 or https://signet.internal:3850, with no path, query string, fragment, or embedded credentials.

Codex matches the session-start, prompt-submit, and session-end path, but it does not currently expose the same compaction lifecycle fidelity as Claude Code or OpenCode.

Supported hooks

MCP tools

When the Signet MCP server is registered, Codex gains access to these tools (namespaced as mcp__signet__*):

• signet_recall — explicit Signet recall for cross-harness history and accepted decisions
• signet_source_search — search source-backed Signet artifacts and docs
• signet_session_search — search active or completed session transcripts
• signet_save_note — write a small explicit note into Codex native memory extensions
• memory_search, memory_store, session_search, and other legacy memory_* tools — compatibility aliases

MCP tools do not replace hooks. MCP gives Codex on-demand tools during a session; hooks provide automatic identity injection, prompt-time recall, and session-end extraction.

Extraction provider

Codex can be selected as the extraction provider in agent.yaml. When set, the pipeline uses the Codex CLI (similar to the claude-code provider) to run extraction and decision passes against Codex’s configured model rather than a local Ollama instance.

Prerequisites

• Codex (codex-rs) installed and in PATH
• Signet daemon running (signet daemon start)

OpenCode

OpenCode is an open-source AI coding tool. Signet integrates via a bundled plugin and AGENTS.md sync.

Files managed by Signet

Plugin Bundle

During signet install, the connector writes a self-contained signet.mjs file to ~/.config/opencode/plugins/ and registers ./plugins/signet.mjs in the OpenCode config so the runtime loads it consistently at startup.

The plugin is built from @signet/opencode-plugin source and bundled into a single ESM file at build time (stored as a string constant in plugin-bundle.ts). This means the plugin has no external dependencies at runtime.

The previous approach (memory.mjs in the OpenCode root directory) is considered legacy. The connector automatically migrates away from it during install by deleting the old file and scrubbing any memory.mjs references from the config’s plugin or plugins arrays.

Config File Detection

The connector searches for an OpenCode config file in this order:

1. ~/.config/opencode/opencode.json
2. ~/.config/opencode/opencode.jsonc
3. ~/.config/opencode/config.json

The first one found is used. If none exist, opencode.json is created as the default. JSONC files (with // comments and trailing commas) are parsed correctly — the connector strips comments and trailing commas before parsing.

MCP Tools

OpenCode also gets MCP tool access via a local server entry registered in the config file during install:

{
  "mcp": {
    "signet": {
      "type": "local",
      "command": ["signet-mcp"],
      "enabled": true
    }
  }
}

The plugin handles lifecycle hooks; MCP provides on-demand memory tools.

Supported hooks

Prerequisites

• OpenCode installed
• ~/.config/opencode/ directory exists

Oh My Pi (oh-my-pi)

Oh My Pi uses a managed Signet runtime extension installed by @signetai/connector-oh-my-pi. The extension forwards lifecycle events to the daemon and injects hidden Signet context into the session when needed.

Files managed by Signet

Managed extension

During setup or connect, the connector writes a bundled signet-oh-my-pi.js file into the Oh My Pi extensions directory. If PI_CODING_AGENT_DIR is set, Signet uses that agent directory. Otherwise it writes to ~/.omp/agent/extensions/.

The install path is idempotent and only manages signet-oh-my-pi.js. Older Signet-managed .mjs installs are removed automatically on the next setup or sync run.

Runtime behavior

• Existing unrelated Oh My Pi extensions are left untouched.
• Signet refuses to overwrite a colliding unmanaged signet-oh-my-pi.js.
• Daemon or network failures are fail-open, so prompt handling, compaction, session switches, and shutdown continue even if Signet is unavailable.
• The extension persists hidden session-context and recall injections through before_agent_start, marks them with attribution: "agent", and keeps them out of transcript reconstruction so memory-backed answers remain attributable without consuming user-attributed Copilot requests.
• It does not currently add /remember or /recall tools, and it does not sync AGENTS.md into Oh My Pi.

Supported hooks

pi (pi)

pi uses a managed Signet runtime extension installed by @signetai/connector-pi. The extension forwards lifecycle events to the daemon and injects hidden Signet context into the session when needed.

Files managed by Signet

Managed extension

During setup or connect, the connector writes a bundled signet-pi.js file into the pi extensions directory. If PI_CODING_AGENT_DIR is set, Signet uses that agent directory. Otherwise it writes to ~/.pi/agent/extensions/.

Runtime behavior

• Existing unrelated pi extensions are left untouched.
• Signet refuses to overwrite a colliding unmanaged signet-pi.js.
• Daemon or network failures are fail-open, so prompt handling, compaction, session switches, and shutdown continue even if Signet is unavailable.
• Automatic recall: On every user prompt, the extension automatically fetches relevant memories from the daemon and injects them as hidden messages (display: false) into the agent’s context. These injections are kept out of transcript reconstruction.
• Manual commands: /recall <query> and /remember <content> let users explicitly search and store memories. The /recall command displays results in the UI only — it does not inject them into the conversation context. /signet-status shows connection and memory stats.
  • /remember <content> — save a memory
  • /remember critical: <content> — save as pinned (never decays)
  • /remember [tag1, tag2]: <content> — save with tags
  • /remember critical: [tag1, tag2]: <content> — pinned with tags (critical prefix must come first)
• Agent tools: signet_recall, signet_source_search, signet_session_search, and signet_remember are registered as LLM-callable tools. When the agent calls signet_recall, the results (including memory IDs) are returned into the conversation context via the tool response. signet_source_search searches provenance-backed artifacts separately from ordinary memory recall; signet_session_search searches active or completed session transcripts.
• Hidden inject messages use display: false and role: "custom". Pi converts custom messages to role: "user" for the LLM, so the X-Initiator header (which determines Copilot billing attribution) is set based on the last message’s role — extensions cannot override it via an attribution field as Oh My Pi can.
• Does not sync AGENTS.md into pi.

Configuration

Configuration is optional and loaded from ~/.pi/agent/extensions/signet.json (or $PI_CODING_AGENT_DIR/extensions/signet.json if set). The SIGNET_ENABLED environment variable overrides the file setting.

Optional ~/.pi/agent/extensions/signet.json:

{
  "enabled": false
}

Environment Variable (overrides file config):

Examples:

# Use config file defaults
pi

# Disable Signet for a single session
SIGNET_ENABLED=false pi

# Create a config file to disable by default
echo '{"enabled": false}' > ~/.pi/agent/extensions/signet.json

Supported hooks

OpenClaw

OpenClaw is the flagship harness for the lossless working-memory model. The plugin path gives the closest match to the full LCM runtime, while the legacy hook path remains compatibility-only. signet sync auto-migrates legacy-only Signet installs to the plugin path, and signet doctor warns when a config is still stuck on legacy-only mode.

Files managed by Signet

Workspace configuration

Signet sets OpenClaw-family configs to your active Signet workspace. Change it with:

signet workspace set ~/.openclaw/workspace

Common compatible workspace targets include:

• ~/.openclaw/workspace
• ~/.clawdbot/workspace
• ~/clawd
• ~/.moltbot/workspace

OpenClaw config value:

{
  "agents": {
    "defaults": {
      "workspace": "$SIGNET_WORKSPACE"
    }
  }
}

OpenClaw checks these config locations (in order):

• ~/.openclaw/openclaw.json
• ~/.clawdbot/clawdbot.json
• ~/.moltbot/moltbot.json

@signetai/adapter-openclaw

The adapter package provides a full lifecycle integration:

import createPlugin from '@signetai/adapter-openclaw';

const signet = createPlugin({
  enabled: true,
  daemonUrl: 'http://localhost:3850'  // default
});

Session start — inject memories into system prompt:

const result = await signet.onSessionStart({
  harness: 'openclaw',
  sessionKey: session.id
});
// result.inject → prepend to system prompt

Pre-compaction — get summary guidelines:

const guide = await signet.onPreCompaction({
  harness: 'openclaw',
  messageCount: messages.length
});
// guide.summaryPrompt → use as compaction instruction

Compaction complete — save the generated summary:

await signet.onCompactionComplete({
  harness: 'openclaw',
  summary: generatedSummary,
  sessionKey: session.id
});

When OpenClaw only exposes compaction metadata to the plugin hook, the runtime may read the latest compaction summary back from sessionFile before calling the daemon so the temporal DAG still receives the real artifact.

Manual memory operations:

await signet.remember('nicholai prefers bun', { who: 'openclaw' });
const results = await signet.recall('coding preferences');

MEMORY.md synthesis

The daemon synthesis worker is the primary runtime path for keeping MEMORY.md current. OpenClaw may still drive synthesis on a schedule by:

1. Calls GET /api/hooks/synthesis/config to check if synthesis should run
2. Calls POST /api/hooks/synthesis to get the synthesis prompt
3. Runs the prompt through the configured model
4. Posts the result to POST /api/hooks/synthesis/complete

Both paths write through the same merge-safe head record, so the rendered MEMORY.md stays shared across harnesses instead of becoming OpenClaw-specific.

Hooks directory

During setup, Signet creates $SIGNET_WORKSPACE/hooks/agent-memory/ with:

• HOOK.md — hook documentation
• handler.js — event handler (for older hook-based integration)
• package.json — package metadata

Package Distinction: adapter vs connector

Signet provides two separate packages for OpenClaw integration:

@signetai/connector-openclaw

Purpose: Setup and installation

This is a setup-time package that:

• Patches OpenClaw config files (openclaw.json, clawdbot.json, moltbot.json)
• Sets agents.defaults.workspace to your active Signet workspace
• Enables the signet-memory internal hook entry
• Installs hook handler files under $SIGNET_WORKSPACE/hooks/agent-memory/

Installed during signet setup when OpenClaw is selected.

@signetai/adapter-openclaw

Purpose: Runtime plugin

This is a runtime plugin that OpenClaw loads to:

• Call the Signet daemon API for /remember, /recall operations
• Handle lifecycle hooks (session start, compaction, etc.)
• Inject memories into the system prompt

Has a peer dependency on openclaw — only usable within the OpenClaw process.

Hermes Agent

Hermes Agent is an open-source terminal AI agent by Nous Research. Signet integrates as a pluggable memory provider via Hermes’s MemoryProvider ABC, deploying a Python plugin that bridges all Signet daemon hooks into the Hermes lifecycle.

Files managed by Signet

How it works

1. signet setup (with hermes-agent selected) copies the Python plugin into both ~/.hermes/plugins/signet/ and, when discovered, <hermes-repo>/plugins/memory/signet/.
2. The connector writes install markers, daemon connection env vars to ~/.hermes/.env, and activates the provider by setting memory.provider: signet in Hermes config.
3. At session start, Hermes calls initialize() on the plugin, which fires POST /api/hooks/session-start to load identity, memories, and system prompt injection from the daemon.
4. On each user turn, queue_prefetch() fires POST /api/hooks/user-prompt-submit for entity current-view context when the prompt mentions a known entity or active alias.
5. At session end, on_session_end() sends the accumulated transcript via POST /api/hooks/session-end for async pipeline extraction.

Tools exposed to the agent

Supported hooks

Delegation support

When Hermes delegates to subagents, the parent’s on_delegation() hook stores the task+result pair as a Signet memory tagged ["delegation", "subagent"].

Prerequisites

• Hermes Agent installed (repo with plugins/memory/ directory)
• Signet daemon running (signet start)
• signet setup --harness hermes-agent
• signet doctor hermes reports daemon health, plugin freshness, config activation, and Hermes tool routing

Adding a New Harness

To integrate Signet with a harness not listed here:

1. Identity sync — simply watch for $SIGNET_WORKSPACE/AGENTS.md changes and copy the content to wherever your harness reads agent instructions.

2. Memory access — call the daemon’s HTTP API:

   • POST /api/memory/remember to save memories
   • POST /api/memory/recall to search memories

3. Lifecycle hooks — call the hooks API at session events:

   • POST /api/hooks/session-start at session start
   • POST /api/hooks/pre-compaction before compaction
   • POST /api/hooks/compaction-complete after compaction

4. Check daemon health — always verify GET /health returns 200 before making other calls.

See API.md for full endpoint documentation and HOOKS.md for hook integration details.

Working-Memory Fidelity Matrix

All harnesses target the same model:

• one agent
• many sessions / branches
• one shared root MEMORY.md head, with optional agent-local MEMORY.md overrides for named agents
• structured retrieval first
• transcripts as fallback / deep history
• compaction artifacts feeding the same temporal DAG

Where they differ is lifecycle fidelity:

The docs should be read literally. If a hook surface is absent here, that mode is degraded rather than silently assumed.

Harness Status

Check which harnesses are configured:

signet status

Or via API:

curl http://localhost:3850/api/harnesses

Or in the dashboard under the Harnesses section.