Quickstart — Signet Docs

Docs / Getting Started

Quickstart

Get Signet running in about five minutes.

Quickstart

Get Signet running in about five minutes. For the full Configuration reference, see that doc. For CLI commands, see Cli.

Why Signet

Your agent starts every session from zero. It doesn’t know what you worked on yesterday. It doesn’t know your preferences, your projects, or the decisions you’ve already made together. Every session is a first date.

The industry’s answer to this has often been to give agents memory tools — “remember this,” “recall that.” That’s not memory. That’s a filing cabinet the agent sometimes opens. It puts the LLM in charge of micromanaging what to store and when to retrieve it.

Signet takes a different approach. The goal is ambient context selection: turn interactions into durable memory substrate, then learn what should surface automatically when the next session begins.

The distillation layer

At the end of every conversation, Signet reviews the session and distills it. A local LLM breaks the conversation into atomic facts, checks them against what’s already known, and decides whether to add new facts, skip duplicates, or record proposals for more complex changes. Your agent won’t store “prefers dark mode” fourteen times.

The knowledge graph

Named entities — people, projects, tools, concepts — are extracted and linked. When you ask about a project, Signet traverses the graph: the project’s architecture, the people involved, the tools it depends on, the constraints that apply. This structure improves the quality of candidate context instead of treating memory as a flat pile of fragments.

The predictive scorer

A predictive scorer can use that structured candidate pool to learn what context is actually useful in your sessions. The aim is not just storage or retrieval, but selecting the most helpful context automatically, with high precision. The scorer is unique to each user. Your weights never leave your machine.

Crucially, the system should learn from regret, not just reuse. If injected context does not help, that should become negative evidence instead of being silently reinforced forever.

Retrieval

Retrieval blends graph traversal, keyword search, and semantic similarity into a bounded candidate set, then reranks and filters it. The constellation view in the dashboard lets you inspect the agent’s knowledge topology.

Document ingest

Feed any document into the distillation layer. PDFs, specs, reference pages, URLs. They’re chunked, embedded, and indexed alongside your agent’s insights.

Safety guarantees

  • Raw-first: content is persisted before any LLM processing begins
  • Pinned insights are sacred: the distillation layer cannot modify them. Only you can.
  • Everything is recoverable: deletions are soft, with a recovery window and full audit trail

Automatic destructive memory mutations remain conservative and gated in the current implementation. Explicit user/operator repair flows are the reliable path today.

The same agent follows you across Claude Code, OpenCode, and OpenClaw. Same personality, same knowledge, same secrets. Switch tools without starting over.

For deeper technical details, see Architecture. For the long-term vision, see VISION.md.

Prerequisites

  • Node.js 18+ (or Bun 1.0+)
  • One of: Ollama (for local embeddings) or an OpenAI API key
  • macOS or Linux (Windows support planned)

Install

# bun (recommended)
bun add -g signetai

# npm
npm install -g signetai

# or one-line installer
curl -sL https://signetai.sh/install | bash

Running signet setup launches an interactive wizard that walks you through the full setup. You don’t need to read anything else first. Signet records your primary package manager during setup and reuses it for skill installs and update commands.

For agent-driven onboarding, use non-interactive mode:

signet setup --non-interactive \
  --name "My Agent" \
  --harness claude-code \
  --embedding-provider ollama \
  --extraction-provider claude-code

In non-interactive mode, agents should ask the user to choose both providers first, then pass those choices explicitly.

Extraction safety note:

  • intended usage is Claude Code on Haiku, Codex CLI on GPT Mini with a Pro/Max subscription, or local Ollama with at least qwen3:4b
  • on a VPS, set extraction to none unless you explicitly want background LLM calls
  • remote API extraction can rack up extreme fees fast

Setup Wizard

The wizard asks a series of questions:

1. Agent name

Pick a name for your agent — this appears in harness prompts and the dashboard.

2. Harnesses

Select which AI platforms you use. Signet will configure integrations for each:

  • Claude Code — hooks + CLAUDE.md sync
  • OpenCode — plugin + AGENTS.md sync
  • OpenClaw — adapter-openclaw hooks
  • Codex — wrapper install + session hooks

3. Embedding provider

Embeddings power semantic (meaning-based) memory search. Choose:

  • Built-in (recommended) — no extra setup required.
  • Ollama — runs locally, free, no API key needed. Setup checks your binary, service, and model, and guides install/pull when needed.
  • OpenAI — uses the OpenAI embeddings API. Requires OPENAI_API_KEY.
  • Skip — memory still works via keyword search, just no semantic search.

4. Embedding model

For Ollama, nomic-embed-text is a good default. Setup can pull it for you (with confirmation), or you can do it manually:

ollama pull nomic-embed-text

5. Search balance

The alpha setting controls how much weight goes to semantic vs. keyword search. 0.7 (70% semantic, 30% keyword) works well for most people.

6. Git & auto-commit

The wizard can initialize a git repo in $SIGNET_WORKSPACE/ so every change to your agent files is automatically versioned.

After the wizard completes, the Daemon starts automatically and the Dashboard opens at http://localhost:3850.

What Gets Created

$SIGNET_WORKSPACE/
├── agent.yaml           # Your config & manifest
├── AGENTS.md            # Agent identity & instructions
├── SOUL.md              # Personality & tone
├── MEMORY.md            # Generated working memory (starts empty)
├── memory/
│   ├── memories.db      # SQLite memory database
│   └── scripts/         # Optional batch tools (memory.py)
├── skills/
│   ├── remember/        # Built-in: /remember command
│   └── recall/          # Built-in: /recall command
└── .daemon/
    └── logs/            # Daemon logs

If you selected Claude Code:

  • ~/.claude/CLAUDE.md — auto-synced from AGENTS.md
  • ~/.claude/settings.json — hooks for session start/end

If you selected OpenCode:

  • ~/.config/opencode/AGENTS.md — auto-synced
  • ~/.config/opencode/plugins/signet.mjs — bundled plugin with remember/recall tools

What Signet Does

Once running, Signet gives you a persistent agent identity that works across all your AI tools. The core features:

  • Memory pipeline — conversations are processed automatically by Pipeline V2, which extracts meaningful facts and decisions using a configured extraction backend. The safe intended setups are Claude Code on Haiku, Codex on GPT Mini, or local Ollama with at least qwen3:4b. Set the extraction provider to none if you want Signet without background extraction. Memories accumulate over time and are recalled in future sessions.
  • Hybrid search — recall combines semantic and keyword search so you find relevant memories even when phrasing varies.
  • Connectors — platform adapters for Claude Code, OpenCode, and OpenClaw keep your agent config in sync across tools.
  • Analytics — the dashboard tracks memory growth, session activity, and pipeline health over time.
  • Document ingest — feed local files or URLs into the memory pipeline to give your agent persistent knowledge about a codebase, spec, or doc.
  • Diagnostics — built-in health checks and pipeline status endpoints help you spot issues fast.
  • SDK — embed Signet into your own apps via @signet/sdk.
  • Secrets — API keys stored encrypted at rest, never exposed to agents directly.
  • Skills — installable instruction packages that extend agent behavior.
  • Auth — token-based access control for local, team, and hybrid deployments. See Auth for details.

Basic Usage

Check status

signet status

Shows daemon state, file health, and memory count.

Open the dashboard

signet dashboard

Opens http://localhost:3850 in your browser. From here you can edit your agent config, browse memories, view analytics, and manage skills. You can also reach it directly in your browser any time the daemon is running.

Save a memory

Use the CLI or /remember command in any connected harness:

# CLI
signet remember "nicholai prefers bun over npm"
signet remember "critical memory" --critical
signet remember "tagged memory" -t project,signet

# In harness
/remember nicholai prefers bun over npm
/remember critical: never commit secrets to git
/remember [project,signet]: daemon runs on port 3850

The critical: prefix or --critical flag pins a memory so it never decays. The [tag1,tag2]: prefix or -t flag adds searchable tags.

You can also let the pipeline do this automatically — at the end of a session, Pipeline V2 reads the conversation and extracts memories on its own. Manual /remember is for things you want to ensure are captured.

Search memories

# CLI
signet recall "coding preferences"
signet recall "signet" --type decision -l 5

# In harness
/recall coding preferences
/recall signet architecture
/recall what did we decide about authentication

View daemon logs

signet daemon logs
signet daemon logs -n 100

Stop/start the daemon

signet daemon stop
signet daemon start
signet daemon restart

Managing Secrets

Store API keys and other sensitive values encrypted at rest:

# Add a secret (value is never echoed)
signet secret put OPENAI_API_KEY

# List stored secrets (names only)
signet secret list

# Remove a secret
signet secret delete GITHUB_TOKEN

Secrets are encrypted with libsodium using a machine-bound key. Agents never see secret values directly.

Managing Skills

Skills are packaged instructions in $SIGNET_WORKSPACE/skills/. They extend what your agent can do.

# See what's installed
signet skill list

# Search the skills.sh registry
signet skill search browser

# Install a skill
signet skill install browser-use

# Remove a skill
signet skill remove weather

Install as a System Service

To have Signet start automatically on boot:

cd packages/daemon
bun run install:service

macOS (launchd):

launchctl load ~/Library/LaunchAgents/ai.signet.daemon.plist

Linux (systemd):

systemctl --user enable signet.service
systemctl --user start signet.service

Editing Your Agent

Your agent identity lives in two key files:

$SIGNET_WORKSPACE/AGENTS.md — What the agent knows and how it should behave. This is the file that syncs to all your harnesses.

$SIGNET_WORKSPACE/SOUL.md — Personality, voice, values. Mostly for your own reference or for harnesses that load it separately.

Edit them directly in your editor or via the dashboard’s config editor. Changes sync to harnesses automatically within 2 seconds.

Auth and Team Deployments

By default, Signet runs in local mode with no auth required on requests. In the default local setup, the daemon also binds to localhost only, which keeps that unauthenticated mode local by default. For team deployments or self-hosted remote access, Signet supports token-based auth with roles and scopes. See Auth and Self-Hosting for setup details.

Troubleshooting

Daemon won’t start

Check if port 3850 is in use:

lsof -i :3850

Remove a stale PID file if needed:

rm $SIGNET_WORKSPACE/.daemon/pid
signet daemon start

Embeddings not working

Make sure Ollama is running:

ollama serve &
ollama pull nomic-embed-text

Or check that OPENAI_API_KEY is set in your environment (or stored as a secret and referenced in agent.yaml).

Changes not syncing to Claude Code

Make sure ~/.claude/ exists and you have the harness configured:

ls ~/.claude/CLAUDE.md
signet status

Dashboard not loading

curl http://localhost:3850/health
signet daemon logs

Next Steps