Teach & forget

Teach the pack your business knowledge: definitions, the names your team uses, and decisions your data does not record. Ingestion is asynchronous. It chunks, embeds, indexes and organizes the content. The Action reaches a final status only when the content can be retrieved. Wait for that, not only for the upload to succeed.

Before you write to a pack, confirm the change with the pack’s owner. A wrong page can make every future answer wrong. See Improving answers for the confirm-then-teach pattern.

Teach a pack something

MCP

teach ingests text or a file into one pack and returns a teach Action.

Input	Type	Required	Meaning
packId	string	Yes	The pack’s id or slug, from list_packs.
content	object	Yes	Either { kind: "text", text }, or { kind: "file", upload: { filename, content, mimeType }, note? } with base64 content, or { kind: "file", artifactId, note? } for a file already stored as an artifact. A file may be a photo (png, jpeg, webp, heic).
content.note	string	No	With a file: what it shows, up to 2000 characters.
idempotencyKey	string	No	A key you choose for this attempt, up to 200 characters. If you repeat it on a retry, you get back the Action the first attempt created.

Returns the queued or running Action immediately. Call action_get with its actionId until the status is final. A succeeded teach lists the documents it produced in output.contentRecordIds. To undo one, pass its id to forget.

Permission: teach needs contribute access on the pack.

“Teach the growth-metrics pack that an active wallet is an address with a swap in the last 30 days.”

CLI

edisyl teach <pack> --text "<fact>"
edisyl teach <pack> --file <path>

Takes exactly one of --text or --file, and returns a queued Action.

edisyl teach my_pack --text "Active wallets are addresses with a swap in 30d."
edisyl teach my_pack --file ./spec.pdf --wait
edisyl teach my_pack --file ./screen.heic --note "SV 125 HMI showing E-102 after a stopper jam"
cat notes.md | edisyl teach my_pack --file -

Flag	Behavior
--text "<fact>"	A direct statement to teach. Cannot be used with --file.
--file <path>	A file to ingest, or - to read it from stdin. Documents (PDF, Office, text) and photos or screenshots (.png, .jpg, .webp, .heic) are accepted. The MIME type comes from the file extension. A HEIC photo is converted to JPEG for display. The original is kept.
--note "<text>"	With --file: what the file shows, in your own words. Stored with the file. For a photo, this is the text that search matches.
--wait	Wait until the Action reaches a final status.
--timeout <duration>	How long --wait waits. Default 5m.
--id-only	Print the bare Action id for scripting.
-j, --json	Machine-readable output.

The maximum size is 50 MiB. A --file over 8 MiB is sent in parts, and each part is retried separately. If the connection drops, only one part is sent again, not the whole file. Below that, and for --text and stdin, the limit is 37.5 MiB.

Follow indexing with edisyl action watch <action-id>. The Action returns a content source id. To find the content record ids it produced, run edisyl action trace <action-id>.

A topic can be answered fully from knowledge, fully from data, or from a mix. You choose this balance when you author the pack. The tool does not decide it for you.

Forget a document

forget is the exact opposite of teach. It removes one ingested document and all knowledge that came from it. A bad page is fully removed, not just hidden. forget takes the content record id, not the Action id. It returns an Action immediately.

MCP

forget removes one document, or withdraws one curated question-and-query pair the pack answers from.

Input	Type	Required	Meaning
packId	string	Yes	The pack’s id or slug.
kind	document or ground_truth	No	document (the default) forgets one ingested document. ground_truth withdraws one curated question-and-query pair. Use it when the query runs without errors but answers a different question than its text says.
contentRecordId	string (UUID)	For document	The document to forget, from a teach’s output.contentRecordIds or an ask’s evidence[].knowledgeId.
groundTruthId	string (UUID)	For ground_truth	The row to withdraw. A row is always retired by its id.
dataSourceId	string (UUID)	No	With ground_truth: the data source the row belongs to.
reason	string	No	Why the row is wrong, in one sentence, up to 500 characters. Stored on the archived row as the record of the decision.
reAsk	boolean	No	With ground_truth. With the default false, the objectives the row answered are held for a person to handle. true returns them to pending. Pass true only if the cause of the wrong row is already fixed.
idempotencyKey	string	No	A key you choose for this attempt. A retry with the same key returns the same Action.

Returns the queued or running Action. Call action_get until the status is final.

Retiring a ground truth also removes it from the fast-answer index. The objectives it answered are held for a person. Any distilled document based on it is withdrawn. Pass reAsk: true only when you know why the row was wrong and the cause is fixed.

“Forget the document that says an active wallet needs two swaps.”

CLI

edisyl forget <pack> <content-record-id>

edisyl pack documents list <pack>        # every document with its record id
edisyl action trace <teach-action-id>    # the records one teach produced

forget has no flags of its own. It creates an Action and returns immediately. Follow it with edisyl action watch <action-id>. You can withdraw a ground truth only over MCP.

Read a document an answer cited

MCP

read_document returns the markdown and title of a document an ask answer cited. Use it when the user wants to see a source, asks where a claim came from, or wants a quote checked against the original. It takes an id, not a question. To find something, use ask.

Input	Type	Required	Meaning
knowledgeId	string (UUID)	Yes	The ref of one knowledge citation in the answer’s output.citations.
offset	integer	No	Where to start reading, in characters. Default 0. Pass the previous response’s nextOffset to continue.
figure	string	No	An asset: reference from the document’s content. Returns that figure as an image. offset is then ignored.
figurePage	integer	No	A page number of the original file, such as a PDF page. Returns the figure printed there.

Returns the document’s markdown and title. A long document is returned one page at a time. While nextOffset is not null, call again with it as offset. It opens only documents you can read. notFound: true means the id does not match a document you can open. For example, the document was forgotten, or it was cited from another organization’s public pack.

“Show me the document that defines active wallets.”

CLI

edisyl pack documents list <pack>
edisyl pack documents list <pack> --status FAILED

The CLI lists a pack’s documents. It cannot read one. Each row shows its source, status, arrival time, and content record id (what forget takes). Documents that failed to extract are listed too. The documentCount from pack get does not include them. If the list is longer than the count, the extra rows are documents that failed.

Flag	Behavior
--status <status>	Only documents in this status: EXTRACTING, EXTRACTED, PROCESSING, READY, INDEXED, or FAILED.
--limit <n>	Up to 100. Default 50.
--offset <n>	Skip this many documents.

Make a pack’s figures searchable

CLI only

figures refresh re-reads the stored PDF and Office originals in a pack’s knowledge base with image extraction on. A vision model describes each figure. Each document is rewritten in place to include its figures and their descriptions in its text. The document is then re-indexed, and search can find the figures. Nothing is re-uploaded.

Each figure costs one vision call. Run --dry-run first. It counts the documents, estimates their figures and the cost, and spends nothing.

edisyl figures refresh <pack> [--dry-run] [--kb <kb>] [--force]

edisyl figures refresh my_pack --dry-run
edisyl figures refresh my_pack
edisyl figures refresh my_pack --kb manuals --force

Flag	Behavior
--dry-run	Measure what would be re-read and what it could cost, and spend nothing.
--kb <kb>	One of the pack’s knowledge bases, by slug or UUID. Defaults to the pack’s only knowledge base.
--force	Also re-read documents that already include figures.

refresh creates an Action and returns immediately. Follow it with edisyl action watch <action-id>.

Download a figure an answer rests on

CLI only

An answer that uses a figure lists it under “Figures” with its reference: <knowledge-base-id>/<content-record-id>/<sha256>. figures get downloads that image. The download uses your access. You get the figure only if you can read the document that contains it. Over MCP, an ask lists the figure in output.images, and read_document opens one with figure.

edisyl figures get <figure-ref> [-o <file|dir|->]

edisyl figures get <kb-id>/<record-id>/<sha256>                 # figure-<digest>.<ext> in the current directory
edisyl figures get <kb-id>/<record-id>/<sha256> -o hinge.png
edisyl figures get <kb-id>/<record-id>/<sha256> -o - > hinge.png

Flag	Behavior
-o, --out <path>	A file to write, a directory to write into under the default name, or - for stdout (refused when stdout is a terminal).