Brain tools

The Brain is your workspace's long-term memory — documents you ingest get chunked, embedded with pgvector, and become queryable by any agent that has access. Five tools cover ingestion, retrieval, and management.

All endpoints follow POST https://mcp.vlozi.app/tools/brain.<name> with Authorization: Bearer ls_xxx.

`brain.query`

Semantic search across your workspace memory. Pass a natural-language question; get the most relevant chunks back.

Scope: brain:copilot.use

Input: { query: string, limit?: number } (limit default 5, max 20)

Response:

{
  "data": {
    "results": [
      { "content": "...", "similarity": 0.91, "docId": "doc_xxx" },
      { "content": "...", "similarity": 0.84, "docId": "doc_yyy" }
    ]
  }
}

similarity is cosine similarity (1.0 = identical embedding, 0.0 = orthogonal). Most useful results sit above ~0.75.

curl -X POST https://mcp.vlozi.app/tools/brain.query \
  -H "Authorization: Bearer $VLOZI_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query": "what is our refund policy?", "limit": 3}'

`brain.ingest`

Add a document to workspace memory. The content is chunked, embedded, and indexed for future retrieval.

Scope: brain:copilot.use

Input:

Field	Type	Notes
`filename`	`string` (required)	Display name
`content`	`string` (required)	Plain text, 10 chars min, 500KB max
`fileType`	`"txt" \| "md" \| "csv" \| "manual" \| "url"`	Default `"txt"`

Response: { id: string, filename: string, status: "ready" \| "failed", chunksCreated: number } plus error if status is failed.

curl -X POST https://mcp.vlozi.app/tools/brain.ingest \
  -H "Authorization: Bearer $VLOZI_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "filename": "refund-policy.md",
    "content": "# Refund Policy\n\nCustomers may request a refund within 30 days...",
    "fileType": "md"
  }'

TIP

Ingestion is synchronous in Phase 1 — the response only comes back once embedding is complete. Large documents (50KB+) can take several seconds. Use fileType: "url" to label web-scraped content; the type is metadata only, not parsed differently.

`brain.list_memories`

List ingested documents with their processing status.

Scope: brain:copilot.use

Input: { status?: "processing" | "ready" | "failed" | "all", limit?: number }

Response: { memories: { id, filename, fileType, fileSize, status, chunkCount, errorMessage, createdAt }[] }

# Show only failed ingests
curl -X POST https://mcp.vlozi.app/tools/brain.list_memories \
  -H "Authorization: Bearer $VLOZI_API_KEY" \
  -H "content-type: application/json" \
  -d '{"status": "failed"}'

`brain.delete_memory`

Delete a document and all its chunks. Cascade-cleans the embeddings.

Scope: brain:memory.delete (separate from brain:copilot.use — destructive)

Input: { id: string }

Response: { id, deleted: true }

curl -X POST https://mcp.vlozi.app/tools/brain.delete_memory \
  -H "Authorization: Bearer $VLOZI_API_KEY" \
  -d '{"id": "doc_xxx"}'

CAUTION

Deleted memories cannot be recovered. Future queries will no longer see this content even though older RAG responses may have cited it.

`brain.get_context`

Like query, but joins the top results into a single string suitable for an agent's prompt context.

Scope: brain:copilot.use

Input: { topic: string, maxChunks?: number } (default 5, max 10)

Response:

{
  "data": {
    "context": "[chunk 1, similarity 0.91]\n...\n\n---\n\n[chunk 2, similarity 0.84]\n...",
    "chunkCount": 2,
    "sources": [
      { "docId": "doc_xxx", "similarity": 0.91 },
      { "docId": "doc_yyy", "similarity": 0.84 }
    ]
  }
}

The pre-formatted context string is ready to drop into a system prompt. The sources array lets you cite where the content came from.

curl -X POST https://mcp.vlozi.app/tools/brain.get_context \
  -H "Authorization: Bearer $VLOZI_API_KEY" \
  -H "content-type: application/json" \
  -d '{"topic": "company values and culture", "maxChunks": 4}'

For a complete RAG bot built on these tools, see the knowledge-base Q&A recipe.