MCP tools

Sigil is an MCP server. Any spec-compliant client — Cursor, Continue, Cline, Windsurf, Claude Desktop, Kiro, or your own agent — gets thirteen tools against the same brain the CLI and hooks use.

sigil register           # stdio launcher (default)
sigil register --http    # the daemon's HTTP transport
sigil register --print   # print the config, write nothing

The set

Tool	Group
prime	Session start	Call first. Loads hot context.
search	Retrieval	Facts by natural-language query
search_entity	Retrieval	Entities by name or type
traverse_graph	Traversal	Walk entity relations
get_fact_context	Detail	Everything about one fact
get_entity_context	Detail	Everything about one entity
get_pod	Detail	A pod and its members
list_pods	Discovery	Available pods
list_documents	Discovery	Stored documents
get_document	Discovery	One document, in full
status	Operations	Knowledge base statistics
ingest	Write	Store a whole document
remember	Write	Save atomic facts

---

Session start

prime

Call this first, before answering anything. It loads the hot-context snapshot — the standing instructions, vital facts, and active project context that Claude Code gets for free through its CLAUDE.md import.

Parameter	Type	Default
limit	number	12

Without it, an MCP client starts cold and can only find what it thinks to search for. Standing instructions like “keep explanations short” are relevant to every answer and similar to no query — they will never be retrieved by search. prime is the channel that delivers them. See Hot context.

---

Retrieval

search

Hybrid search over facts — pgvector cosine and tsvector BM25, fused with RRF, re-ranked by activation and co-retrieval.

Parameter	Type	Default
query	string	—	Natural language
limit	number	5	Max facts
namespaces	string[]	—	Filter by namespace
minConfidence	low·medium·high	medium
includeChunks	boolean	false	Raw document chunks — verbose, only when needed
useGraph	boolean	false	Traverse the entity graph for related facts
pointInTime	ISO string	—	Only facts valid at that moment
format	full·compact	full	compact is token-efficient, one line per category
podScope	auto·global·string[]	auto	auto = active project and session pods

podScope: "global" searches the whole brain. Use it when the answer might live in another project.

search_entity

Find entities in the knowledge graph.

Parameter	Type	Default
query	string	—
entityType	string	—
limit	number	10
namespace	string	—

Better than search for “what do I know about X”, where X is a name — the answer isn’t textually similar to the question.

---

Traversal

traverse_graph

Navigate entity relationships.

Parameter	Type	Default
startEntityId	number	—	From search_entity
action	neighbors·path·related	neighbors
targetEntityId	number	—	Required for path
relationType	string	—	Filter by relation
maxDepth	number	2	1–3
limit	number	20

Action	Returns
neighbors	Direct connections
path	Shortest path to targetEntityId
related	Everything reachable within maxDepth

---

Detail

get_fact_context

Full context for one fact: complete content, entities mentioned, relations created, source documents.

Parameter	Type
factId	number	From search results
uid	string	e.g. fact-a1b2c3d4

One of the two.

get_entity_context

Relations, connected facts, and graph position for an entity.

Parameter	Type
entityId	number
name	string
namespace	string

get_pod

A memory pod with its member facts and documents — and, for person pods, their platform metadata.

Parameter	Type
uid	string

---

Discovery

list_pods

Parameter	Type	Default
type	session·person·project·connector_workspace·custom	all
namespace	string	default
status	active·archived	active
limit	number (≤100)	20

list_documents

Documents stored whole, scoped to the current project by default.

Parameter	Type	Default
cwd	string	—	Scopes to that project’s pod. Pass the project you’re working in.
podScope	auto·global·string[]	auto
sourceType	string	—	e.g. docs, notes, code
limit	number	50

get_document

Read a stored document in full.

Parameter	Type	Default
uid	string	—
maxChars	number	40000

Facts first, documents second

Search finds the facts; get_document gets you the source. When an injected fact came from a document, its source uid is shown — fetch the document only when the facts alone don’t answer the question. Pulling a whole document “just in case” is what the fact layer exists to avoid.

---

Operations

status

Documents, chunks, facts, entities, relations.

Parameter	Type
namespace	string

---

Write

remember

Save one or more standalone facts.

Parameter	Type
facts	string[]	One or more self-contained facts. Each element is a separate fact.
namespace	string
cwd	string	Pass the project you’re working in — attaches the facts to its pod so they resurface there
pod	string	Attach to this pod instead of the one derived from cwd. Use when the fact is about a different project.

Every write runs through AUDM, so re-saving something you already know is a no-op rather than a duplicate.

ingest

Store a whole document, and extract facts from it.

Parameter	Type	Default
content	string	—	Raw text. Provide this or filePath or url.
filePath	string	—
url	string	—
title	string	auto
namespace	string	default
sourceType	string	auto	docs, code, notes, …
cwd	string	—	Attaches to that project’s pod
skipFacts	boolean	false	Chunks only — faster
skipEntities	boolean	false	Skip entity linking
wait	boolean	false	Wait for searchable chunks and facts instead of returning a job acknowledgement

---

Making an agent actually use them

MCP has no hook layer. The agent decides when to call, which means the system prompt does the work.

A minimal instruction that works across clients:

You have access to a persistent memory system called Sigil. Call prime at the start of every session. Before answering questions about projects, preferences, or past decisions, call search. When the user shares a preference, decision, or constraint, call remember. When they say “save this doc”, call ingest.

sigil init writes a client-native version of this automatically for Cursor, Codex CLI, and Kiro. For everything else, add it to the client’s rules file — see Integrations.

Two transports

	stdio	HTTP
Registered by	sigil register	sigil register --http
Process	One spawned per client	One long-lived daemon transport
Address	~/.sigil/bin/sigil-mcp	http://127.0.0.1:7777/mcp + bearer token
Survives Node switches	Yes — it’s a shim	Yes — the URL never changes

HTTP is the more portable option for clients that support it. Both reach the same registry, so the tools are identical.

Verifying

sigil doctor --deep     # actually spawns the MCP server and round-trips it
sigil register --print  # what your client should be configured with