---
title: "Documents and PDFs"
description: "How Basic Memory turns PDFs, Word, PowerPoint, and CSV files into searchable Markdown notes that stay linked to the original file."
canonical_url: "https://docs.basicmemory.com/concepts/documents-and-pdfs"
---
# Documents and PDFs

> How Basic Memory turns PDFs, Word, PowerPoint, and CSV files into searchable Markdown notes that stay linked to the original file.

Knowledge doesn't only live in notes. Reports, slide decks, papers, and spreadsheets sit in the same folders, and until now your AI could see them only as opaque files. As of [v0.24](https://docs.basicmemory.com/whats-new/v0-24), Basic Memory can extract a document's text into a Markdown note that sits next to the original file, so search finds what's inside the document and your AI can read it like any other note.

---

## How it works

Put the file in a project, then import it:

```bash
bm import document reports/q3-review.pdf
```

Basic Memory indexes the project, extracts the file, and writes two notes:

<table>
<thead>
  <tr>
    <th>
      Note
    </th>
    
    <th>
      Path
    </th>
    
    <th>
      Purpose
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        Extracted text
      </strong>
    </td>
    
    <td>
      <code>
        reports/q3-review.pdf.md
      </code>
    </td>
    
    <td>
      The document's text as Markdown, next to the source file
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Ingestion run
      </strong>
    </td>
    
    <td>
      <code>
        document-ingestion-runs/<run-id>.md
      </code>
    </td>
    
    <td>
      Provenance: which extractor ran, with what settings, against which bytes
    </td>
  </tr>
</tbody>
</table>

The original file is never modified. The extracted-text note is an ordinary Markdown file: full-text and semantic search index it, `bm_read` reads it, and you can open it in any editor.

```text
reports/
├── q3-review.pdf        # the original, unchanged
└── q3-review.pdf.md     # extracted text, searchable
document-ingestion-runs/
└── 748d4356-....md      # what produced it
```

Re-running the import is a no-op while the source file is unchanged. Basic Memory won't overwrite a note you wrote or edited by hand at the sidecar path.

<note>

The path is resolved against the **project root**, not your current directory, and the file must already be inside the project. To import something from `~/Downloads`, copy it into the project folder first. Use `--project` to pick a project other than the default. Full options are in the [CLI Reference](https://docs.basicmemory.com/reference/cli-reference).

</note>

### In Basic Memory Cloud

In the web app, upload a PDF, Word, PowerPoint, or CSV file, or drag it into a folder. Basic Memory extracts it the same way, into a searchable note next to the original. Open the file to switch between the **Original** and the **Extracted text**.

<theme-image alt="An uploaded PDF shown as its extracted text, with the Original and Extracted text toggle" dark="/screenshots/cloud-app/pdf-import-extracted-dark.png" light="/screenshots/cloud-app/pdf-import-extracted-light.png">



</theme-image>

---

## Supported formats

<table>
<thead>
  <tr>
    <th>
      Format
    </th>
    
    <th>
      Extension
    </th>
    
    <th>
      Install
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      PDF
    </td>
    
    <td>
      <code>
        .pdf
      </code>
    </td>
    
    <td>
      <code>
        basic-memory[pdf]
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Word
    </td>
    
    <td>
      <code>
        .docx
      </code>
    </td>
    
    <td>
      <code>
        basic-memory[documents]
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      PowerPoint
    </td>
    
    <td>
      <code>
        .pptx
      </code>
    </td>
    
    <td>
      <code>
        basic-memory[documents]
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      CSV
    </td>
    
    <td>
      <code>
        .csv
      </code>
    </td>
    
    <td>
      Included — no extra needed
    </td>
  </tr>
</tbody>
</table>

Document extraction is optional so the default install stays small. Add the extras you need:

<code-group>

```bash [uv]
uv tool install 'basic-memory[pdf,documents]'
```

```bash [pip]
pip install 'basic-memory[pdf,documents]'
```

</code-group>

PDFs are extracted with pdf-inspector; Word and PowerPoint files with Microsoft's markitdown converters. Both run in a separate worker process with time and size limits, so a malformed or huge file can't hang Basic Memory. A CSV becomes a bounded preview — the header and the first 200 rows as a Markdown table — rather than a full dump, and must be valid UTF-8.

---

## What the extracted note looks like

The note's frontmatter records where the text came from:

```yaml
---
title: q3-review.pdf
type: extracted_text
schema: schema/document-extraction
tags: [document, pdf, generated]
source:
  media_type: application/pdf
  file_path: reports/q3-review.pdf
  checksum: sha256:...
extraction:
  engine: firecrawl/pdf-inspector
  status: complete
  page_count: 12
  pages_needing_ocr: []
ingestion:
  stage: raw
  run_id: 748d4356-...
bm_parse_semantics: false
---

<!-- Page 1 -->

Q3 Business Review
...
```

- **type: extracted_text** marks it as derived text. Sidecars written by earlier versions use `type: document`; both are valid and Basic Memory never rewrites one into the other.
- **source** identifies the exact file and the checksum of the bytes that were extracted.
- **extraction** summarizes the result — status, page counts, and any scanned pages that need OCR. The full per-page map lives on the ingestion-run note, which keeps long PDFs' sidecar frontmatter small.
- **Page markers** (`<!-- Page N -->`) keep PDF page boundaries visible in the text.

### Extracted text stays graph-quiet

Raw extracted text is searchable, but it doesn't add observations or relations to your knowledge graph — `bm_parse_semantics: false`. A PDF that happens to contain `- [note] ...` or `[[Something]]` won't flood your graph with accidental facts and links.

The one connection every extracted-text note does get is a **derived_from** relation to its source file. Basic Memory adds it from the note's `source` frontmatter at index time, so `bm_context` can walk from the text to the original PDF and back. Don't write this relation into the body yourself.

---

## Page citations

<note>

Basic Memory defines the citation format below, but v0.24 doesn't yet ship a command or tool that enriches an extracted document. Today `bm import document` produces the raw extracted text only.

</note>

When an extracted document is enriched — its raw text turned into structured observations — each observation can cite the PDF page it came from. The citation is written as a Markdown footnote plus a matching `sources` entry in frontmatter, following the [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) provenance convention:

```markdown
## Observations

- [fact] Revenue increased 14% quarter over quarter. [^document-page-2]

[^document-page-2]: [PDF page 2](/reports/q3-review.pdf#page=2)
```

```yaml
sources:
  - id: document-page-2
    resource: /reports/q3-review.pdf#page=2
    title: q3-review.pdf, p. iv
    locator:
      page: 2
      page_label: iv
```

`page` is the physical page in the PDF (the one a viewer jumps to with `#page=2`); `page_label` is the optional printed page number. Page numbers are checked against the extraction's page count, and the link is built from the source file's path rather than supplied by an AI, so a citation always points at the real file. Enriched documents turn semantic parsing back on, so their observations join the graph like any other note's.

---

## Other files in your project

Files you don't extract are still part of the project. Images, PDFs, and other non-Markdown files are indexed as file entries you can list, read with `bm_read`, link to, and move. As of v0.24 each one also records its content type and format. Moving one preserves its bytes exactly, and deleting one through Basic Memory removes it from storage.

Metadata filters in `bm_search` apply to Markdown notes only.

---

## Next steps

<card-group>
<card icon="i-lucide-file-text" title="Knowledge Format" to="https://docs.basicmemory.com/concepts/knowledge-format">

The structure of a Markdown note.

</card>

<card icon="i-lucide-terminal" title="CLI Reference" to="https://docs.basicmemory.com/reference/cli-reference">

`bm import document` and the other import commands.

</card>

<card icon="i-lucide-search" title="Semantic Search" to="https://docs.basicmemory.com/concepts/semantic-search">

How extracted text is indexed and found.

</card>

<card icon="i-lucide-sparkles" title="What's New in v0.24" to="https://docs.basicmemory.com/whats-new/v0-24">

Everything in this release.

</card>
</card-group>


## Sitemap

See the full [sitemap](https://docs.basicmemory.com/sitemap.md) for all pages.
