> For the complete documentation index, see [llms.txt](https://docs.origintrail.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.origintrail.io/build-with-dkg/import-documents.md).

# Import Documents

Turn a project note into knowledge your agent can connect to other records. Import the document, inspect its extracted relationships, and have the agent answer with a source. When the contribution is ready, you can share it so other participants can use the same evidence.

Start with a healthy node and the exact Context Graph ID from the [quickstart](https://docs.origintrail.io/start-here/quickstart.md). Use documents you intend this node and its configured extraction providers to process.

## Supply a small document

Save this as `atlas-note.md`:

```markdown
# Atlas architecture note

Atlas uses Oxigraph to store its RDF graph. This is fictional tutorial data.
The project owner is the Atlas team.
```

```bash
dkg ka import-file atlas-note -c "$CG" --input-file ./atlas-note.md
dkg ka extraction-status atlas-note -c "$CG"
```

Import and semantic extraction are different stages. Inspect the node-served skill's available extraction pipelines and the returned status:

| Status        | Meaning and next action                                                                               |
| ------------- | ----------------------------------------------------------------------------------------------------- |
| `in_progress` | Poll extraction status with a bounded wait                                                            |
| `completed`   | Inspect the written triples and source artifact                                                       |
| `skipped`     | The artifact was stored but extraction did not write triples; check converters/pipeline configuration |
| `failed`      | Read the error and correct the cause; a reported count is not proof of a partial successful write     |

A status lookup can return `404` if no import record exists or the tracker expired. Inspect the KA and import artifact before deciding to import again.

## Inspect and improve the knowledge

```bash
dkg ka query atlas-note -c "$CG"
```

Confirm what the pipeline actually extracted. Structural Markdown extraction may preserve document structure without creating the `usesDatabase` relationship. Semantic extraction can require a configured model and incur provider costs; its output needs review. Do not promise the same facts from every pipeline.

Ask the agent to read the completed import artifact through its discovered artifact-reading tool, inspect the KA, and propose missing relationships with source provenance. Review the proposed facts before it writes them. To learn a deterministic graph representation first, use the [five-triple fixture](https://docs.origintrail.io/start-here/quickstart.md#3-write-a-small-inspectable-fact).

Use stable IRIs for entities, predicates with documented meanings, and source identifiers for assertions. These let a later query connect the imported knowledge to other contributions. Two similar labels are not proof that two entities are identical. Keep source statements separate from model-inferred relationships, so a reader can tell which evidence supports each claim.

## Retrieve, update, and share

In a fresh conversation under the same authorized identity, ask the agent to read `atlas-note` from `$CG`, answer only from the retrieved evidence, and identify the source and WM layer. If the relevant relationship is absent, the right result is a missing-evidence report.

WM writes are additive. For an existing shared/published KA, use the [pull-from/edit lifecycle](https://docs.origintrail.io/operate/knowledge-asset-lifecycle.md#editing-a-published-knowledge-asset); appending a contradictory fact does not replace an earlier value. Discard/recreate a draft only when that replacement is intended.

Seal and share only after reviewing the extracted content and destination policy:

```bash
dkg ka finalize atlas-note -c "$CG"
dkg ka share atlas-note -c "$CG"
```

Publication is a separate, funded decision. File deletion, removal from WM, removal from peers, and changing an on-chain commitment are different operations; do not promise global erasure from deleting a local file.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.origintrail.io/build-with-dkg/import-documents.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
