> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memorylake.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Memory Pipeline
> How MemoryLake processes conversations and documents into searchable, structured memories
## The Core Flow
MemoryLake has two input channels -- documents and conversations -- that feed into a unified search index. Here is how data flows through the system:
```
Input Channels Processing Output
-------------- ---------- ------
Documents -----> Indexing ------+
(files from |
the Library) +----> Unified Search Index
|
Conversations -> Fact --------+
(messages) Extraction
|
+-> Project Facts
+-> Actor Facts
```
Both channels contribute to the same search results. When you query a workspace, MemoryLake searches across document content and extracted facts together, returning the most relevant results regardless of source.
## Document Memory
Document memory comes from files you import into a project from the Library. MemoryLake indexes the content for semantic search, so you can find relevant passages using natural language queries.
### How it works
Upload files to the MemoryLake Library using the [Library API](/features/memorylake/api-reference/library/overview). The Library is your central file store -- it holds the original files independent of any project.
Import documents from the Library into a project using the [Import Documents API](/features/memorylake/api-reference/v3-documents/import-documents). This tells MemoryLake to index the file's content for that project.
MemoryLake processes the document asynchronously -- parsing the content, chunking it, and building a semantic index. Once complete, the document's content is searchable.
### Supported formats
MemoryLake supports common document formats including PDF, Word (`.docx`), Excel (`.xlsx`), PowerPoint (`.pptx`), plain text, Markdown, and images.
For best results, use well-structured documents with clear headings and sections. MemoryLake uses the document structure to produce better search results.
## Conversation Memory
Conversation memory comes from user-assistant exchanges that you submit to a project. This is where MemoryLake's automatic fact extraction happens.
### How it works
Create a conversation in a project to group related messages together.
```bash theme={null}
curl -X POST https://app.memorylake.ai/openapi/memorylake/api/v3/workspaces/{workspace_id}/memories/conversations \
-H "Authorization: Bearer $MEMORYLAKE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"custom_id": "planning-001",
"kind": "DIRECT",
"rw_project_ids": ["{project_id}"],
"name": "Planning session"
}'
```
Submit messages to the conversation one at a time. Include the `actor_id` so MemoryLake can associate facts with the right participant.
```bash theme={null}
curl -X POST https://app.memorylake.ai/openapi/memorylake/api/v3/conversations/{conversation_id}/messages \
-H "Authorization: Bearer $MEMORYLAKE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"custom_id": "msg-001",
"actor_id": "act_jane456",
"content": [{"block_type": "TEXT", "text": "We decided to use React for the frontend. Launch target is March."}]
}'
curl -X POST https://app.memorylake.ai/openapi/memorylake/api/v3/conversations/{conversation_id}/messages \
-H "Authorization: Bearer $MEMORYLAKE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"custom_id": "msg-002",
"actor_id": "act_assistant",
"content": [{"block_type": "TEXT", "text": "Got it. I will note that the frontend uses React with a March launch target."}]
}
]
}'
```
MemoryLake analyzes the messages and extracts structured facts:
* **Project Fact:** "The frontend uses React"
* **Project Fact:** "Launch target is March"
* **Actor Fact (Jane):** context about Jane's involvement in the decision
Facts are extracted asynchronously, typically within a few seconds of submitting messages.
### What gets extracted
MemoryLake identifies and extracts several types of knowledge from conversations:
| Category | Examples |
| -------------------- | --------------------------------------------------------------------- |
| **Preferences** | "I prefer dark mode," "Send me weekly summaries" |
| **Decisions** | "We chose PostgreSQL," "The deadline is Q3" |
| **Personal context** | "I manage the billing team," "I work at Acme Corp" |
| **Goals and plans** | "We are targeting 10K users by launch," "Next sprint focuses on auth" |
| **Relationships** | "Sarah is the engineering lead," "The billing team reports to me" |
## How Search Unifies Both Channels
When you search a workspace, MemoryLake queries across both document content and extracted facts in a single request:
```bash theme={null}
curl -X POST https://app.memorylake.ai/openapi/memorylake/api/v3/workspaces/{workspace_id}/memories/search \
-H "Authorization: Bearer $MEMORYLAKE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "What technology stack are we using?"}'
```
The response includes results from both channels:
```json theme={null}
{
"success": true,
"data": {
"documents": [
{
"document_id": "doc_xyz",
"document_name": "Tech Stack Overview",
"items": [
{"text": "...our backend runs on Node.js with PostgreSQL..."}
]
}
],
"facts": [
{
"id": "fact_001",
"fact": "The frontend uses React",
"score": 0.95
},
{
"id": "fact_002",
"fact": "The team chose PostgreSQL for the database",
"score": 0.88
}
]
}
}
```
The result merges facts extracted from conversations with passages found in documents. From the caller's perspective, it is one query, one result set.
See the [Search API reference](/features/memorylake/api-reference/search/search-memories) for the full set of search parameters and options.
## Documents vs. Conversations: When to Use Each
Both channels feed the same search index, but they serve different purposes:
| Use documents when... | Use conversations when... |
| --------------------------------------------------------- | ------------------------------------------ |
| You have existing files (PDFs, docs, wikis) | You are capturing real-time interactions |
| The information is static or changes infrequently | The information evolves through dialogue |
| You want full-text search over long-form content | You want automatic fact extraction |
| You are building a knowledge base from existing materials | You are building per-user memory over time |
Most applications use both channels. Import your existing documentation as documents, and submit ongoing user interactions as conversations. MemoryLake searches across both seamlessly.
## Structuring Messages for Better Extraction
The quality of extracted facts depends on how messages are written. Here are some best practices:
**Be explicit.** "I prefer email notifications" extracts better than "yeah email is fine I guess."
**State facts directly.** "Our deadline is March 15" produces a clear, useful fact. Vague statements like "we should probably aim for mid-March" produce less precise extractions.
**Include context.** "We chose React for the frontend because of team expertise" gives MemoryLake more to work with than just "React."
**Use the `actor_id` field.** Always include the actor ID on user messages. Without it, MemoryLake cannot associate personal facts with the right actor.
**Send complete exchanges.** Include both user and assistant messages. The full context of the conversation helps MemoryLake extract more accurate and relevant facts.
Do not include sensitive information (passwords, API keys, secrets) in conversation messages. Facts are extracted and stored persistently. Treat conversation content the same way you would treat data written to a database.
## Next Steps
See the full end-to-end flow in action
Deep dive into per-user memory with actors
API reference for creating conversations and messages
API reference for searching across documents and facts