> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memcontext.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Context Vault

> Turn workspace documents, files, and URLs into searchable AI context.

Context Vault lets your app add company or project knowledge once, then retrieve
the right source passages and extracted facts whenever your AI system needs
context.

Use it for support bots, internal copilots, onboarding agents, sales assistants,
or any workflow where an AI system needs to answer from trusted workspace
documents.

## Why Context Vault Exists

Normal memory is best for short, durable facts like preferences, decisions, and
project context. Company knowledge is different. It usually lives in PDFs,
Markdown files, help centers, contracts, onboarding docs, tickets, and long
internal notes.

Context Vault is the AI context pipeline for that kind of knowledge. It lets you
add long-form content, turn it into searchable context, and retrieve the right
pieces when your AI application needs to answer.

Use Context Vault when you want to:

* Let a support bot answer from product documentation
* Let an internal copilot search handbooks, policies, and SOPs
* Let a legal or finance assistant retrieve exact clauses from PDFs
* Let an AI workflow combine source passages with extracted facts

Do not use Context Vault for:

* Small user preferences that should be saved as personal memories
* Temporary chat messages that do not need to be remembered
* Private tenant data unless you put each tenant in its own workspace or scope

## What You Can Add

Context Vault accepts:

* PDFs
* Markdown and text files
* DOCX files
* CSV files
* Images and scanned documents
* Public file URLs
* Documentation or website URLs
* Already extracted text or Markdown

For files that need OCR, MemContext extracts readable text automatically. For
documentation URLs, MemContext fetches clean page content that is easier to
search than raw HTML.

## How The AI Context Pipeline Works

When you add a document, MemContext prepares it for retrieval in three layers:

1. **Source document**: the original file, URL, or text stays connected to the
   workspace document.
2. **Document chunks**: the content is split into meaningful sections so your AI
   can receive the exact source passage it needs.
3. **Extracted memories**: important facts are saved separately as atomic
   memories and linked back to the chunks they came from.

This is why Context Vault can return both the original source context and the
clean extracted knowledge. Your app can pass both to an LLM, show citations, or
let users inspect the original document.

## Add A Document With The SDK

```typescript theme={null}
import { MemContextClient } from "memcontext-sdk";

const client = new MemContextClient({
  apiKey: process.env.MEMCONTEXT_API_KEY!,
});

await client.ingestContextVaultDocument({
  workspaceId: "8b3b8f4c-...",
  title: "Product docs",
  uri: "https://docs.example.com",
  sourceType: "url",
  crawlSubpages: true,
});
```

Upload a local file:

```typescript theme={null}
await client.uploadContextVaultDocument({
  workspaceId: "8b3b8f4c-...",
  title: "Employee handbook",
  file,
  filename: "handbook.pdf",
  sourceType: "pdf",
});
```

## Add A Document With The API

### Upload A File

Use this when your client has the file bytes.

```bash theme={null}
curl -X POST https://api.memcontext.in/api/context-vault/documents/upload \
  -H "X-API-Key: mc_your_key" \
  -F "workspaceId=8b3b8f4c-..." \
  -F "title=Employee Handbook" \
  -F "sourceType=pdf" \
  -F "file=@handbook.pdf"
```

### Add A Public File URL

Use this when the file is already available at a public URL.

```bash theme={null}
curl -X POST https://api.memcontext.in/api/context-vault/documents \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mc_your_key" \
  -d '{
    "workspaceId": "8b3b8f4c-...",
    "title": "Security Whitepaper",
    "sourceType": "pdf",
    "uri": "https://example.com/security-whitepaper.pdf",
    "scope": "security"
  }'
```

### Add A Documentation URL

Use this for documentation sites, help centers, or public web pages.

```bash theme={null}
curl -X POST https://api.memcontext.in/api/context-vault/documents \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mc_your_key" \
  -d '{
    "workspaceId": "8b3b8f4c-...",
    "title": "Product Docs",
    "uri": "https://docs.example.com",
    "sourceType": "url",
    "crawlSubpages": true,
    "priorityPageLimit": 15,
    "subpageTarget": ["api", "guides"]
  }'
```

For docs sites that expose `llms.txt`, MemContext uses the page map to discover
and rank useful pages, then ingests only the selected priority pages.
`priorityPageLimit` defaults to `15` and is capped at `25`.

### Add Text Or Markdown Directly

Use this when your app already has clean text.

```bash theme={null}
curl -X POST https://api.memcontext.in/api/context-vault/documents \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mc_your_key" \
  -d '{
    "workspaceId": "8b3b8f4c-...",
    "title": "Leave Policy",
    "sourceType": "markdown",
    "content": "# Leave Policy\nEmployees get 18 paid leave days..."
  }'
```

## Check Document Status

After a document is accepted, list documents to see its current status and
progress.

```typescript theme={null}
const docs = await client.listContextVaultDocuments("8b3b8f4c-...");
```

```bash theme={null}
curl "https://api.memcontext.in/api/context-vault/documents?workspaceId=8b3b8f4c-..." \
  -H "X-API-Key: mc_your_key"
```

Common statuses are `pending`, `processing`, `retrying`, `completed`, `failed`,
and `cancelled`.

## Search Workspace Knowledge

Context Vault search has three modes:

| Mode        | What it returns                                   |
| ----------- | ------------------------------------------------- |
| `documents` | Source passages from uploaded files and URLs      |
| `memories`  | Extracted atomic facts with evidence              |
| `hybrid`    | Both document passages and extracted memory facts |

Use `documents` when your AI needs exact source text, such as contract clauses,
policy language, or troubleshooting steps.

Use `memories` when your AI needs concise facts, such as "the refund window is
14 days" or "Scope is the tenant isolation key."

Use `hybrid` for most production AI apps. It gives the model both precise source
passages and distilled facts, which usually improves answer quality and makes
citations easier to show.

```typescript theme={null}
const results = await client.searchContextVault({
  workspaceId: "8b3b8f4c-...",
  query: "What is the leave policy?",
  mode: "hybrid",
});
```

```bash theme={null}
curl "https://api.memcontext.in/api/context-vault/search?workspaceId=8b3b8f4c-...&query=leave%20policy&mode=hybrid" \
  -H "X-API-Key: mc_your_key"
```

## Response Shape

Hybrid search returns document chunks and extracted memories separately:

```json theme={null}
{
  "mode": "hybrid",
  "found": 2,
  "chunks": [
    {
      "id": "chunk_...",
      "sourceId": "doc_...",
      "title": "Employee Handbook",
      "sourceType": "pdf",
      "sectionPath": "Leave Policy",
      "chunkIndex": 12,
      "content": "Employees receive 18 paid leave days per year...",
      "relevance": 0.91
    }
  ],
  "memories": [
    {
      "id": "mem_...",
      "content": "Employees receive 18 paid leave days per year.",
      "category": "fact",
      "evidence": [
        {
          "sourceId": "doc_...",
          "chunkId": "chunk_...",
          "title": "Employee Handbook",
          "sectionPath": "Leave Policy",
          "chunkIndex": 12,
          "quote": "Employees receive 18 paid leave days per year..."
        }
      ]
    }
  ]
}
```

For AI answer generation, pass `chunks[]` as source-document context and
`memories[]` as a separate memory-context block. This keeps citations and
high-level facts easy to handle in your own app.

## Why Search Quality Improves

Context Vault does more than match keywords. It first gathers candidate results
from document chunks and extracted memories. For document searches, MemContext
then uses a re-ranking model on the top candidate passages, currently up to 30
candidates, so the most useful source text appears higher.

This helps with questions where the best answer is not an exact keyword match.

| Query                                          | Good result should surface                              |
| ---------------------------------------------- | ------------------------------------------------------- |
| "What obligations continue after termination?" | Termination, return, payment, and confidentiality terms |
| "Is the contractor an employee?"               | Independent contractor and liability sections           |
| "How should I isolate tenants?"                | Scope and workspace isolation guidance                  |

For best results, ask complete questions and include names, section numbers, or
domain terms when they matter.

## Browse Extracted Memories

List all extracted workspace memories:

```typescript theme={null}
const page = await client.listContextVaultMemories({
  workspaceId: "8b3b8f4c-...",
  limit: 20,
});
```

List memories from one document:

```typescript theme={null}
const extracted = await client.listContextVaultDocumentMemories(
  "8b3b8f4c-...",
  "document-id",
);
```

Load citations for one extracted memory:

```typescript theme={null}
const evidence = await client.listContextVaultMemoryEvidence(
  "8b3b8f4c-...",
  "memory-id",
);
```

## Delete Or Cancel

Cancel a document that is still running:

```typescript theme={null}
await client.cancelContextVaultDocument("document-id");
```

Delete a document:

```typescript theme={null}
await client.deleteContextVaultDocument("document-id");
```

When a document is deleted, memories that only came from that document are
removed from future retrieval. Memories supported by other documents remain
available.

## Supported Sources

Start with:

* Markdown
* TXT
* PDF
* DOCX
* CSV
* PNG, JPG/JPEG, WebP, and TIFF
* Public documentation or website URLs

XLSX, PPTX, and external workspace connectors should be added after the core
document workflow is stable.