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

# Memory

# Memory & RAG Tools

The 60db MCP Server exposes the full Memory/RAG layer to MCP clients like Claude Desktop. These tools let an AI assistant persist user memories, ingest knowledge base documents (91+ formats with built-in OCR), run hybrid semantic recall, and assemble LLM-ready context for retrieval-augmented generation.

<Info>
  All memory tools are **pay-as-you-go** from the workspace wallet. Every billable response surfaces the new balance, the charge amount, and the transaction ID in the formatted output so the agent can reason about cost. See the [pricing reference](/api-reference/memory/pricing) for rates and refund policy.
</Info>

## Tool summary

| Tool                               | Billed | Purpose                                                     |
| ---------------------------------- | ------ | ----------------------------------------------------------- |
| `sixtydb_memory_ingest`            | ✓      | Store a single memory                                       |
| `sixtydb_memory_ingest_batch`      | ✓      | Batch-store up to 100 memories                              |
| `sixtydb_memory_upload_document`   | ✓✓     | Extract + ingest a document (PDF, DOCX, XLSX, images, etc.) |
| `sixtydb_memory_search`            | ✓      | Hybrid semantic + keyword recall                            |
| `sixtydb_memory_context`           | ✓      | Assemble LLM-ready context for RAG                          |
| `sixtydb_memory_list_collections`  | —      | List collections in the workspace                           |
| `sixtydb_memory_create_collection` | —      | Create a team/knowledge/hive collection                     |
| `sixtydb_memory_get_usage`         | —      | Monthly spend breakdown + wallet balance                    |
| `sixtydb_memory_get_status`        | —      | Poll a memory's ingestion state                             |
| `sixtydb_memory_delete`            | —      | Soft-delete a memory (24h undo)                             |

## Ingest a memory

Store a single fact, preference, or conversation snippet:

```json theme={null}
{
  "tool": "sixtydb_memory_ingest",
  "arguments": {
    "text": "User prefers vegetarian food and is lactose intolerant.",
    "title": "Dietary preferences",
    "type": "user",
    "infer": true
  }
}
```

**Parameters:**

* `text` (required) — content to store, max 100,000 characters
* `title` (optional) — display title
* `collection` (optional) — target collection ID (defaults to personal)
* `type` — `user`, `knowledge`, or `hive` (default: `user`)
* `infer` — if true, the memory service extracts structured facts via LLM

**Cost:** \$0.0001 per 1,000 characters.

## Upload a document

The most powerful memory tool — give the agent a file path and 60db handles format detection, OCR, chunking, and ingestion:

```json theme={null}
{
  "tool": "sixtydb_memory_upload_document",
  "arguments": {
    "file_path": "/Users/me/Documents/quarterly-report.pdf",
    "collection": "company_reports",
    "type": "knowledge",
    "title": "Q4 2026 Quarterly Report"
  }
}
```

**Parameters:**

* `file_path` (required) — absolute path on the agent's local filesystem
* `collection` (optional) — target collection
* `type` — `user` | `knowledge` | `hive` (default: `knowledge` — right choice for docs)
* `title` (optional) — display title, defaults to filename
* `chunk_size` (optional) — characters per chunk (200–8000, default 1500)
* `chunk_overlap` (optional) — character overlap between chunks (default 200)

**Supported formats:** PDF, DOCX, DOC, ODT, RTF, TXT, MD, HTML, EPUB, XLSX, XLS, CSV, ODS, PPTX, PPT, ODP, EML, MSG, PNG, JPG, TIFF, BMP, and 70+ more. OCR is applied automatically to scanned PDFs and images.

**Max file size:** 200 MB. **Max chunks per document:** 100.

**Cost (two-stage):**

* Extract fee: \$0.003 per MB (pre-charged)
* Ingest fee: \$0.0001 per 1,000 extracted characters (post-charged)

Both fees are automatically refunded on any failure.

## Search memories

Hybrid semantic + keyword recall with optional cross-encoder reranking, across user memories AND knowledge documents in one call:

```json theme={null}
{
  "tool": "sixtydb_memory_search",
  "arguments": {
    "query": "What are my dietary preferences?",
    "mode": "thinking",
    "max_results": 10,
    "alpha": 0.8
  }
}
```

**Parameters:**

* `query` (required) — search text, max 2,000 chars
* `collection` (optional) — collection to search
* `mode` — `fast` (dense retrieval, \~100-200ms) or `thinking` (wider pool + cross-encoder rerank, \~200-400ms)
* `max_results` — 1–50, default 10
* `alpha` — 0 (keyword only) to 1 (semantic only), default 0.8
* `recency_bias` — weight for newer memories (0–1), default 0
* `graph_context` — include knowledge-graph relationships

**Advanced reranker knobs** (optional, override server defaults):

* `rerank_top_k` — max candidates the cross-encoder reranks (1-500)
* `rerank_timeout_ms` — hard timeout for rerank call (50-5000ms)
* `min_rerank_score` — drop results below this score (0-1)
* `fetch_multiplier` — in thinking mode, fetch N x max\_results candidates (1-10)

When the reranker is active, each result includes a `rerank_score` (cross-encoder confidence, 0-1) alongside the regular `score` (dense similarity). The rerank score is the more reliable ranking signal.

**Tuning by query type:**

| Query type            | Recommended                     |
| --------------------- | ------------------------------- |
| Exact phrase match    | `alpha: 0.2, mode: fast`        |
| Conceptual question   | `alpha: 0.9, mode: fast`        |
| Complex multi-faceted | `alpha: 0.7, mode: thinking`    |
| Latest-events focus   | `alpha: 0.6, recency_bias: 0.3` |

**Cost:** flat \$0.0003 per query regardless of parameters.

## Assemble context (RAG)

Purpose-built for retrieval-augmented generation. Returns a `prompt_ready` string you can prepend directly to an LLM system message:

```json theme={null}
{
  "tool": "sixtydb_memory_context",
  "arguments": {
    "query": "What should I tell the customer about their order?",
    "session_id": "chat_abc123",
    "top_k": 8,
    "max_context_length": 2000
  }
}
```

**Graceful degradation** — if the memory layer is unreachable, the tool returns an empty `prompt_ready` string and the charge is automatically refunded so the chat flow keeps working.

**Cost:** flat \$0.0005 per query.

## Collections

List everything the caller can see:

```json theme={null}
{
  "tool": "sixtydb_memory_list_collections",
  "arguments": {}
}
```

Create a team/knowledge/hive collection (admin/owner only):

```json theme={null}
{
  "tool": "sixtydb_memory_create_collection",
  "arguments": {
    "collection_id": "customer_support",
    "label": "Customer Support KB",
    "kind": "knowledge",
    "shared": true
  }
}
```

Personal collections are auto-created per user on first use and cannot be created via this tool.

**Both are unbilled.**

## Monitor spend

Track usage and wallet balance without affecting the wallet:

```json theme={null}
{
  "tool": "sixtydb_memory_get_usage",
  "arguments": {
    "period": "current_month"
  }
}
```

Returns net spend, operation count, refund count, and a per-service-type breakdown, plus the billing owner's current wallet balance. Always free, works even when the wallet is empty.

**Periods:** `current_month` (default), `last_30_days`, `all_time`.

## Handling insufficient credits

When the wallet runs out, billable tools return an error with `INSUFFICIENT_CREDITS` structure. Agents should:

1. Catch the 402 case
2. Call `sixtydb_memory_get_usage` to show the shortfall to the user
3. Prompt the user to top up via the 60db dashboard (link: `/app/billing`)
4. Retry the original operation once the wallet is funded

## Billing transparency in every response

Every billable tool response includes a **Billing** footer in the formatted output:

```
**Memory queued** in collection `user_abc123`
Type: user
Total queued: 1
- `mem_01HV...` — pending: Memory queued for processing

_Billing: charged **$0.000013** · balance **$9.464587** · tx `84ffd09e`_
```

The JSON response format also embeds a `billing: { balance, charged, txId }` object for programmatic consumers.

## Related

* [Memory pricing & billing](/api-reference/memory/pricing)
* [Get memory usage endpoint](/api-reference/memory/usage)
* [Memory feature overview](/features/memory)
* [Authz MCP tools](/mcp-server/authz)