---
name: hippocampus
description: Use when the user wants to import documents into Thalius Hippocampus, search them, ask questions with page-cited sources, or connect an agent to Hippocampus over MCP. Covers the REST API (core and vault), tokens, and the MCP server.
---

<!-- Beta, 5 Oct 2026: endpoints and fields can still change. -->

# Hippocampus

Hippocampus turns a company's documents into a layered knowledge base. Search finds the passages that answer a question, each with its pages and a link to the original; ask returns a short answer.

## Before you start

- **Access:** API access gives you a user for your script in a Hippocampus tenant. There are no API keys yet.
- **Addresses:** the tenant's addresses are in the Hippocampus app under Manage tenant → API and MCP. Defaults: core `https://hippocampuscore.thalius.ai`, vault `https://hippocampusvault.thalius.ai`, MCP `https://hippocampusmcp.thalius.ai/mcp`.
- **Token:** every REST call sends `Authorization: Bearer $HIPPOCAMPUS_TOKEN`, the ID token of the signed-in script user. It lasts about an hour; on a `401`, sign in again.

## Connect over MCP (preferred for agents)

The MCP server speaks streamable HTTP and signs in with OAuth in the browser: no token to paste.

```bash
claude mcp add --transport http --scope user hippocampus https://hippocampusmcp.thalius.ai/mcp
claude mcp login hippocampus
```

Other clients: https://www.thalius.ai/developers/mcp

Tools: `hippocampus_ask`, `hippocampus_search`, `hippocampus_list_folders`, `hippocampus_list_documents_by_folder`, `hippocampus_list_tags`, `hippocampus_list_documents_by_tag`, `hippocampus_get_document_markdown`, `hippocampus_get_document_metadata`, `hippocampus_ingest`, `hippocampus_job_status`, `hippocampus_health`. Work in this order: list folders or tags → list documents in one → `hippocampus_search` for passages → `hippocampus_ask`, scoped by `folder_name` or `document_id`. MCP import (`hippocampus_ingest`) takes paths on the server's own disk: to upload a local file, use REST `POST /ingest`.

## REST: the four calls

```bash
# 1. Import (stream=true shows progress; without it, poll GET /jobs/{job_id} until done is true)
curl -sS -N -X POST "https://hippocampuscore.thalius.ai/ingest?stream=true" -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN" \
  -F "files=@contract.pdf" -F 'file_metadata=[{"folder_name":"contracts","tags":[]}]'

# 2. Search: passages with pages and a deep link to the original
curl -sS -X POST "https://hippocampuscore.thalius.ai/search" -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN" -H "Content-Type: application/json" \
  -d '{"query":"What is the notice period?","folder_name":"contracts"}'

# 3. Ask: a short answer (no passages; use search for those)
curl -sS -X POST "https://hippocampuscore.thalius.ai/ask" -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN" -H "Content-Type: application/json" \
  -d '{"query":"What is the notice period?","folder_name":"contracts"}'

# 4. Read a document's text (vault)
curl -sS "https://hippocampusvault.thalius.ai/documents/<document-id>" -H "Authorization: Bearer $HIPPOCAMPUS_TOKEN"
```

## Gotchas

- `folder_name` is a folder path such as `contracts/master-agreements`; vault calls take folder and document ids (UUIDs).
- `/ask` returns `answer`, `reasoning` and `confidence` only. Cite from `/search`.
- An ingest job is finished when `status` is `complete` (not `completed`), or simply when `done` is `true`.
- A streamed import may end with `{"event_type":"error","error":"stream_stalled"}`: the import keeps running. Check the job instead of uploading again.
- Results contain only what the signed-in user may read; a `404` from the vault can mean "not readable".
- Errors: the core answers `{"detail": …}`, the vault `{"message": …}` (or `{"error": "unauthenticated"}` on a bad token).
- The API is in beta: fields can still change. Do not invent SDK calls; there are no official SDKs yet.

## Reference

- API reference: https://www.thalius.ai/developers/api (Markdown: https://www.thalius.ai/developers/api.md)
- OpenAPI: https://www.thalius.ai/developers/openapi.json · Postman: https://www.thalius.ai/developers/hippocampus.postman_collection.json
- MCP: https://www.thalius.ai/developers/mcp (Markdown: https://www.thalius.ai/developers/mcp.md)
- Security and data handling: https://www.thalius.ai/security