Custom agents, scripts & CI

If it can run a shell command, it can use Sigil. That’s the whole integration story for anything not covered elsewhere.

sigil search "JWT auth setup"
sigil remember --bg "we use jose, not jsonwebtoken"
sigil ingest ./DESIGN.md

No SDK, no client library, no MCP config. sigil is discovered on PATH the same way git and node are.

Giving an agent memory

Add this to whatever your agent uses for system instructions:

You have a persistent memory available as the `sigil` command.

- Before answering about projects, past decisions, or user preferences:
    sigil search "<the question>"
- When the user shares a preference, decision, or constraint:
    sigil remember --bg "<short self-contained fact>"
- To store a document whole:
    sigil ingest <path|url>
- Batch multiple facts into one call:
    sigil remember --bg "fact one" "fact two" "fact three"

Facts must be short and self-contained — they are retrieved months later
with none of this conversation around them.

That’s it. Any agent with a Bash tool now shares a brain with Claude Code, Cursor, and everything else on the machine.

Always --bg from inside an agent turn

A save runs a chain of LLM calls — classify, extract, AUDM. --bg returns immediately and completes in a detached process, so the agent isn’t blocked. Failures are recorded to the hook error log and surfaced by sigil doctor.

Namespaces for agent writes

An agent writing on its own behalf should usually write to its own namespace, so its output is distinguishable from yours:

sigil remember --namespace=triage-bot "Prod issue #4412 was a connection-pool exhaustion under retry storm"

Then read across both:

sigil search "connection pool" --all-namespaces

Or set defaults.searchNamespaces so this install always reads both. See Pods and namespaces.

Pod targeting from a script

cd /workspace/payments-api
sigil remember "The webhook signature check rejects clock skew over 5 minutes"

Sigil derives the project pod from the working directory, and keys it on the git remote — so a fact written by a cloud agent in /workspace/payments-api lands in the same pod as one written on your laptop in ~/work/payments-api.

When the fact is about a different project than the directory you’re in:

sigil remember --pod=srver "F0 boots via direct kernel boot + virtio-blk"

CI pipelines

- name: Record the release decision
  run: |
    sigil remember --bg \
      "Release ${{ github.ref_name }} shipped ${{ steps.date.outputs.today }}" \
      "It included the retry-queue migration"

- name: Ingest the changelog
  run: sigil ingest ./CHANGELOG.md --wait

Use --wait on ingest in CI. Without it the process exits before the queue drains, and you can’t tell success from silence.

For a non-interactive setup step:

sigil init --url "$SIGIL_DATABASE_URL"
sigil doctor

sigil doctor exits non-zero after five unacknowledged hook errors in 24 hours, so it’s usable as a health gate.

Reading memory in a script

# what does the brain know?
sigil search "deploy process" --limit=5

# machine-readable
sigil export --format=json --namespace=engineering | jq '.facts[].content'

# the ranking breakdown, for debugging
sigil why "deploy process"

MCP for structured agents

If your agent framework prefers typed tools over shell output, Sigil’s MCP server works the same way it does for any client:

sigil register --http --print

The HTTP transport is the better fit for a long-running agent — one URL that never changes, rather than a process spawned per call.

{
  "type": "http",
  "url": "http://127.0.0.1:7777/mcp",
  "headers": { "Authorization": "Bearer <token>" }
}

Remote agents

An agent on a VPS can share your brain two ways:

Point it at the same Postgres. Simplest. The connection string is the credential.

sigil init --url "postgres://user:pass@host/sigil?sslmode=require"

Pair it as a device. Scoped, revocable, and it doesn’t need database access at all.

# on your machine (master)
sigil pair create --name triage-vps --role writer --ns triage --ttl 600

# on the VPS
sigil join <master-node-id> <code> --name triage-vps

See Multi-device.

Device-scoped facts

An agent on a server will learn things that are only true there — paths, ports, hardware. Scope them so they don’t pollute your laptop’s memory:

sigil visibility <fact-id> device

Sigil’s extractor catches obvious cases automatically. See Provenance and visibility.

What a good agent fact looks like

# no — meaningless without the conversation
sigil remember --bg "fixed it"

# no — transient
sigil remember --bg "the build is currently failing"

# yes
sigil remember --bg "Prod incident 2026-03-14 was connection-pool exhaustion triggered by a retry storm; fixed by capping retries at 3 with jitter"

Agents are worse at this than people, because they’re summarizing rather than asserting. The instruction “short and self-contained — retrieved months later with none of this conversation around it” does most of the work.