Harnesses

Harnesses are the AI platforms and tools that Signet integrates with. Some are external platforms reached through connectors. Forge is the first-party native harness and the reference runtime implementation for the Signet runtime contract.

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

Forge

Forge is Signet’s native terminal harness. Unlike external harness integrations, it does not need hook/config patching because it speaks to the daemon directly as the host runtime.

Management surface

Forge remains a separate product command:

forge

Signet can also manage Forge installs directly:

signet forge install
signet forge update
signet forge status
signet forge doctor

Managed installs place the binary in ~/.config/signet/bin. Add that directory to your PATH if you want forge available in a normal shell.

Managed binary downloads currently support macOS arm64, macOS x64, Linux x64, and Linux arm64. On other platforms, install Forge from source or use a local standalone build.

Install/update commands prompt for an explicit development warning acknowledgement. For automation:

signet forge install --yes
signet forge update --yes

Runtime role

• first-party native harness
• reference implementation of the Signet runtime contract
• direct daemon client for memory, hooks, skills, secrets, and MCP

Forge is still represented as a harness id (forge) in Signet config, setup detection, and dashboard surfaces.

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 using its native hook system (hooks.json) for full lifecycle memory — including per-prompt recall on every user turn. Signet also registers as an MCP server so Codex can call signet_remember and signet_recall as native tools.

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 watches ~/.codex/memories/ and automation-local ~/.codex/automations/*/memory.md files, then exposes matching content through Signet recall as native_memory results with Codex provenance. Removed native files are soft-deleted from active recall while preserving their artifact rows for lineage.

How it works

1. Codex reads ~/.codex/hooks.json at startup and registers three hooks.
2. 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.
3. On every user prompt, Codex fires UserPromptSubmit → calls signet hook user-prompt-submit -H codex --codex-json → Signet returns per-prompt recalled memories as hookSpecificOutput.additionalContext with suppressOutput: true so the context is model-visible but not printed into the user transcript. This is blocking — Codex waits for the hook before sending to the model.
4. On session end, Codex fires Stop → calls signet hook session-end -H codex → Signet extracts memories from the transcript.
5. The MCP server exposes memory_store, memory_search, session_search, and other 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, set SIGNET_DAEMON_URL before running the Codex connector:

SIGNET_DAEMON_URL=http://192.168.0.60:3850 signet setup --harness codex

When SIGNET_DAEMON_URL is set, the Codex connector writes [mcp_servers.signet] url = "<daemon>/mcp" and bakes the same daemon URL into the generated lifecycle hook commands. This keeps on-demand MCP tools and automatic lifecycle memory pointed at the same Signet instance. The 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__*):

• memory_store — save a memory
• memory_search — hybrid recall (vector + keyword)
• session_search — search active or completed session transcripts
• memory_list — list recent memories
• memory_modify — update existing memory
• memory_forget — delete a memory

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 @signet/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 @signet/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_remember, and signet_memory_feedback 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_memory_feedback lets the LLM rate injected memory relevance (-1 to 1) to improve future recall ranking.
• 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:

@signet/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 per-turn hybrid recall (BM25 + vector + KG + predictive scoring).
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.