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

# Knowledge & Memory

> How agents get persistent context through searchable knowledge and scoped memory.

Agents draw on two kinds of persistent context. **Knowledge** is reference material you ingest and search semantically. **Memory** is information an agent records and recalls across scopes. Both are provided by the Data Platform REST API.

## Knowledge vs Memory

These serve different purposes and have different access patterns:

|                    | Knowledge                                                                                                          | Memory                                                                         |
| ------------------ | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| **Created by**     | You (or a connector sync). Content is ingested, chunked, and embedded before it's searchable.                      | An agent at runtime. Items are written during task execution.                  |
| **Access pattern** | Searched at query time using embedding similarity (not exact match). Returns ranked results by semantic relevance. | Written and read by a specific agent, scoped by runtime context.               |
| **Sharing**        | Shared across agents that have read access to the store. Multiple agents can search the same knowledge base.       | Private to the writing agent's scope (task, session, agent, or workspace).     |
| **Mutability**     | Updated via re-ingestion or connector sync. Individual chunks are not directly editable.                           | Items can be written, read, and overwritten by the owning agent.               |
| **Persistence**    | Permanent until you delete the store or its content.                                                               | Governed by scope TTL (24h for task, 8h for session, 1yr for agent/workspace). |

<Note>
  Knowledge search uses **embedding similarity**, not keyword or exact match. A query for "refund policy" will match content about "return procedures" or "money-back guarantees" if the semantic meaning is close. Tune `score_threshold` to control the relevance cutoff.
</Note>

## Key concepts

| Term                | Meaning                                                                  |
| ------------------- | ------------------------------------------------------------------------ |
| **Knowledge store** | A searchable collection of ingested content (documents, connector data). |
| **Semantic search** | Retrieval by meaning, ranked by vector similarity.                       |
| **Memory store**    | A container where an agent writes and reads items over time.             |
| **Memory scope**    | Controls how long items persist and how broadly they're shared.          |

## Knowledge

Built by ingesting documents or connecting data sources. Content is chunked and embedded, then available for semantic search.

| Configuration          | Range                                     | Default     |
| ---------------------- | ----------------------------------------- | ----------- |
| `chunk_size`           | 100–4000                                  | 800         |
| `chunk_overlap`        | 0–500                                     | 100         |
| `embedding_dimensions` | 128–4096                                  | 1024        |
| `chunking_strategy`    | `recursive` / `markdown` / `conversation` | `recursive` |
| `embedding_provider`   | `openai` / `bedrock` / `custom`           | —           |

Search: `query` (1–10,000 chars), `top_k` (1–100, default 10), optional `score_threshold`.

## Memory scopes and TTL

| Scope       | TTL      | Use for                                    |
| ----------- | -------- | ------------------------------------------ |
| `TASK`      | 24 hours | Working state within a single task.        |
| `SESSION`   | 8 hours  | Context across a multi-turn session.       |
| `AGENT`     | 1 year   | Long-lived knowledge an agent accumulates. |
| `WORKSPACE` | 1 year   | Memory shared across a workspace.          |

## Accessing via REST API

Knowledge and memory are accessed via `curl` against the Data Platform REST API. There is no SDK client for data operations.

```bash theme={"dark"}
# Search a knowledge store
curl -X POST https://api.hexelstudio.com/data/v1/knowledge/YOUR_STORE_ID/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "refund policy", "top_k": 5}'

# Search memory
curl -X POST https://api.hexelstudio.com/data/v1/memory/YOUR_STORE_ID/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "user preferences", "top_k": 3}'
```

## Related pages

<CardGroup cols={2}>
  <Card title="Knowledge Stores" icon="book" href="/docs/data-platform/knowledge-stores">
    Create and search knowledge.
  </Card>

  <Card title="Memory" icon="brain" href="/docs/data-platform/memory">
    Record and recall agent memory.
  </Card>

  <Card title="Connectors" icon="plug" href="/docs/data-platform/connectors">
    Sync external data into knowledge.
  </Card>

  <Card title="Context Bundles" icon="box" href="/docs/data-platform/context-bundles">
    Assemble grounded context for runs.
  </Card>
</CardGroup>

## Next steps

Continue to [Organizations](/docs/concepts/organizations).