Meridian AI - Context Infrastructure for AI Agents

Introduction

Welcome to Meridian, the Agentic Context Layer

We empower search in two main ways - semantic search and knowledge graphs. Like typical systems, documents are semantically broken into chunks of information. A document, usually, will be broken into multiple chunks.

On top of this, we perform entity and relationship extraction on all documents you upload - linear issues, github PRs, google documents, emails, etc. People, projects, topics, customer accounts, etc. are identified across documents, extracted, registered as idempotent entities, and put into relationships with other entities. For example, if myself and my cofounder communicate about a project a lot, the following would be stored in our index:

Entities

Chris Farrington

Kashyap Nathan

Relationships

Chris Farrington works on Meridian: knowledge graph feature

Kashyap Nathan works on Meridian: vector embeddings and indexing.

Kashyap Nathan works with Chris Farrington <occurrences: 20>

These entities and relationships are tied to the documents used to extract them. Thus, when entering a query "What are Kashyap and Chris working on" to, say, our smart search endpoint, we recognize those entities behind the scenes, recognize the inherent relationships, filter our document search, and then (optionally) perform a semantic search among those filtered documents.

Something important to note is that knowledge graphs are built at the tenant / org level. Different peoples documents and actions are seen holistically, giving Meridian a pulse on an organization, while still implementing strict role based access to queries for individual end users.

In terms of setup - a user is simply required to oauth into a source connector and select the files, repos, teams, channels, etc. they want synced. After that, we handle incremental syncing, ingestion, extraction, etc. As documents are edited, messages are sent, and PRs are merged, we also take note of that activity. Questions like "who made changes to document x today" are queryable.

Tools

Meridian provides a suite of tools for querying your knowledge base.

1. Agent Query (Internal Search Agent)

The internal agent is the highest-level abstraction. It uses an agent to intelligently search and synthesize information across your knowledge base.

Endpoint

POST /v1/agent/query

Input Structure

questionstring (required)

A natural language query

session_idstring (optional)

A run_id for multi-turn conversations

max_iterationsinteger (optional, default: 5)

Max number of agent "turns" that can be taken

Output Structure

Response Fields:

answer (string): Full LLM-generated answer synthesizing information from sources
run_id (string): Session/run ID for continuing multi-turn conversations
sources (array): List of source documents used in the answer
title (string): Title of the source document
url (string): URL to the source document (may be "#" if not available)
source_type (string): Data source type (e.g., "microsoft-teams", "slack", "github")
created_at (ISO 8601 datetime): When the source document was created
created_at (ISO 8601 datetime): Timestamp of the response

{
  "answer": "Based on the search results, Nike mentioned several concerns about our API rate limiting during the Q4 sync meeting on October 15th...",
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "sources": [
    {
      "title": "Nike Q4 Sync - Oct 15.json",
      "url": "https://dashboard.trymeridian.dev/files/...",
      "source_type": "microsoft-teams",
      "created_at": "2024-10-15T14:30:00Z"
    },
    {
      "title": "API Discussion - Slack Channel",
      "url": "#",
      "source_type": "slack",
      "created_at": "2024-10-14T09:15:00Z"
    }
  ],
  "created_at": "2024-11-20T10:30:45.123456Z"
}

Example cURL Request

curl -X POST "https://webhooks.trymeridian.dev/v1/agent/query" \
  -H "Authorization: Bearer kt_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What did Nike say about our API?",
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "max_iterations": 5
  }'

2. RAG Search

Pure semantic search without knowledge graph filtering. Faster and suitable for broad technical searches.

Endpoint

POST /api/v1/search/rag

Input Structure

querystring (required, 1-1000 chars)

Search query

sourcesarray (optional)

Filter by data source types (OR logic). Valid values: "google-mail", "outlook", "slack", "google-drive", "sharepoint", "box", "github", "microsoft-teams", "linear", "notion", "dropbox", "confluence", etc.

limitinteger (optional, default: 10, range: 1-100)

Maximum number of results

offsetinteger (optional, default: 0, min: 0)

Pagination offset (not currently implemented)

afterISO 8601 datetime (optional)

Only return documents after this timestamp

beforeISO 8601 datetime (optional)

Only return documents before this timestamp

context_windowobject (optional)

Retrieve surrounding chunks

- before (integer, 0-10): Number of chunks before the matched chunk

- after (integer, 0-10): Number of chunks after the matched chunk

enable_rerankboolean (optional, default: true)

Enable Cohere reranking

Output Structure

Same structure as Smart Search output (see below)

Example cURL Request

curl -X POST "https://webhooks.trymeridian.dev/api/v1/search/rag" \
  -H "Authorization: Bearer kt_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "JWT authentication implementation",
    "sources": ["github"],
    "limit": 15
  }'

3. Filtered RAG Search

Pure RAG search with manually specified filters. Maximum control and fastest performance. No KG extraction. Uses manual filters only.

Endpoint

POST /api/v1/search/rag/filtered

Input Structure

querystring (required, 1-1000 chars)

Search query

filtersobject (required)

Manual filters to apply

entity_idsarray (optional)

Entity IDs to filter by (OR logic). Supports wildcards (e.g., "EMPLOYEE::*")

relationshipsarray (optional)

Relationship patterns (OR logic)

- source (string): Source entity ID (supports wildcards)

- relation (string): Relationship type

- target (string): Target entity ID (supports wildcards)

sourcesarray (optional)

Data source types (OR logic). Valid values: "google-mail", "outlook", "slack", "google-drive", "sharepoint", "box", "github", "microsoft-teams", "linear", "notion", "dropbox", "confluence", etc.

limitinteger (optional, default: 10, range: 1-100)

Maximum number of results

offsetinteger (optional, default: 0, min: 0)

Pagination offset (not currently implemented)

afterISO 8601 datetime (optional)

Only return documents after this timestamp

beforeISO 8601 datetime (optional)

Only return documents before this timestamp

context_windowobject (optional)

Retrieve surrounding chunks

- before (integer, 0-10): Number of chunks before the matched chunk

- after (integer, 0-10): Number of chunks after the matched chunk

enable_rerankboolean (optional, default: true)

Enable Cohere reranking

Output Structure

Same structure as Smart Search output (see below)

Example cURL Request

curl -X POST "https://webhooks.trymeridian.dev/api/v1/search/rag/filtered" \
  -H "Authorization: Bearer kt_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "api implementation",
    "filters": {
      "entity_ids": ["EMPLOYEE::john-uuid"],
      "sources": ["github"]
    },
    "limit": 20
  }'

4. Smart Search

Smart Search performs automatic entity extraction, automatic relationship extraction, knowledge-graph-driven filtering, and semantic search over relevant documents.

Endpoint

POST /api/v1/search/smart

Input Structure

querystring (required)

A natural language query

sourcesarray (optional)

A source filter list

entity_idsarray (optional)

Entity IDs to bias the KG extraction (add your own entity ids to heavily guide the LLM entity and relationship recognition)

afterISO 8601 datetime (optional)

Only return documents after this timestamp

beforeISO 8601 datetime (optional)

Only return documents before this timestamp

context_windowobject (optional)

What surrounding chunks to retrieve

- before (integer, 0-10): Number of chunks before the matched chunk

- after (integer, 0-10): Number of chunks after the matched chunk

enable_rerankboolean (optional, default: true)

LLM based reranking

deterministicboolean (optional, default: false)

If true, return all results related to the kg extraction filters, otherwise, return the results of a kg extraction + filter + semantic search

limitinteger (optional, default: 10, range: 1-100)

Maximum number of results

offsetinteger (optional, default: 0, min: 0)

Pagination offset

Output Structure

Response Fields:

results (array): List of search result chunks
content (string): Chunk text content
document_id (string): Canonical file/document ID
chunk_index (integer): Index of chunk within document
score (float): Relevance score (0-1)
metadata (object): Chunk metadata
file_name (string): Name of the source file
source_type (string): Data source type (e.g., "microsoft-teams", "github", "slack")
created_at (ISO 8601 datetime, optional): When document was created
entities (array): Entities found in this chunk
id (string): Entity ID (e.g., "ACCOUNT::nike-uuid")
name (string): Entity name (e.g., "Nike")
type (string): Entity type (e.g., "ACCOUNT")
relationships (array of strings): Relationship IDs in format "SOURCE_ENTITY__RELATIONSHIP_TYPE__TARGET_ENTITY"
provider_metadata (object, optional): Additional provider-specific metadata
context (object, optional): Surrounding chunks (if context_window was requested)
before (array): Chunks before this one
after (array): Chunks after this one
query_analysis (object): Analysis of query processing
original_query (string): The original query
extracted_entities (array of strings, optional): Entity IDs extracted from query
matched_entities (array of objects, optional): Fuzzy-matched entities
extracted (string): Entity ID extracted from query
matched (string): Matched entity ID from knowledge graph
confidence (float): Match confidence (0-1)
applied_filters (object): Filters that were applied
execution_time_ms (integer): Query execution time in milliseconds

{
  "results": [
    {
      "content": "Nike requested API improvements during the Q4 planning call...",
      "document_id": "550e8400-e29b-41d4-a716-446655440000",
      "chunk_index": 5,
      "score": 0.95,
      "metadata": {
        "file_name": "Q4 Planning Meeting Transcript",
        "source_type": "microsoft-teams",
        "created_at": "2024-01-10T14:30:00Z",
        "entities": [
          {
            "id": "ACCOUNT::nike-uuid",
            "name": "Nike",
            "type": "ACCOUNT"
          }
        ],
        "relationships": [
          "ACCOUNT::nike-uuid__participates_in__TEAMS_MEETING::meeting-123-uuid"
        ],
        "provider_metadata": {}
      },
      "context": {
        "before": [...],
        "after": [...]
      }
    }
  ],
  "query_analysis": {
    "original_query": "What did Nike say about our API in recent calls?",
    "extracted_entities": ["ACCOUNT::nike-uuid"],
    "matched_entities": [
      {
        "extracted": "Nike",
        "matched": "ACCOUNT::nike-uuid",
        "confidence": 0.98
      }
    ],
    "applied_filters": {}
  },
  "execution_time_ms": 245
}

Example cURL Request

curl -X POST "https://webhooks.trymeridian.dev/api/v1/search/smart" \
  -H "Authorization: Bearer kt_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What did Nike say about our API in recent calls?",
    "limit": 10,
    "offset": 0,
    "after": "2024-10-01T00:00:00Z",
    "before": "2024-11-20T23:59:59Z",
    "context_window": {
      "before": 2,
      "after": 2
    },
    "enable_rerank": true,
    "deterministic": false
  }'

5. Filtered Smart Search

Manual filters combined with automatic KG extraction. The filtered endpoint combines manual filters with automatic KG extraction. It extracts entities from the query and applies both the manual filters and extracted entities.

Endpoint

POST /api/v1/search/smart/filtered

Input Structure

querystring (required, 1-1000 chars)

Natural language query

filtersobject (required)

Manual filters to apply

entity_idsarray (optional)

Entity IDs to filter by (OR logic). Supports wildcards (e.g., "EMPLOYEE::*")

relationshipsarray (optional)

Relationship patterns (OR logic)

- source (string): Source entity ID (supports wildcards)

- relation (string): Relationship type

- target (string): Target entity ID (supports wildcards)

sourcesarray (optional)

Data source types (OR logic). Valid values: "google-mail", "outlook", "slack", "google-drive", "sharepoint", "box", "github", "microsoft-teams", "linear", "notion", "dropbox", "confluence", etc.

limitinteger (optional, default: 10, range: 1-100)

Maximum number of results

offsetinteger (optional, default: 0, min: 0)

Pagination offset

afterISO 8601 datetime (optional)

Only return documents after this timestamp

beforeISO 8601 datetime (optional)

Only return documents before this timestamp

context_windowobject (optional)

Retrieve surrounding chunks

- before (integer, 0-10): Number of chunks before the matched chunk

- after (integer, 0-10): Number of chunks after the matched chunk

enable_rerankboolean (optional, default: true)

Enable Cohere reranking

Output Structure

Same structure as Smart Search output (see above)

Example cURL Request

curl -X POST "https://webhooks.trymeridian.dev/api/v1/search/smart/filtered" \
  -H "Authorization: Bearer kt_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "what features were discussed?",
    "filters": {
      "entity_ids": ["ACCOUNT::nike-uuid"],
      "sources": ["microsoft-teams"]
    },
    "limit": 10
  }'

6. Knowledge Graph Query

KG queries return entities, relationships, provenance, and query analysis. Discover entities, relationships, and semantic connections.

Endpoint

POST /api/v1/kg/query

Input Structure

querystring (required, 1-1000 chars)

Natural language query about entities and relationships

depthinteger (optional, default: 1, range: 1-3)

Graph traversal depth: 1 = Direct relationships only, 2 = Friends of friends (2 hops), 3 = Extended network (3 hops)

matching_strategystring (optional, default: "cross_type")

Entity matching strategy: "same_type" = Restrictive, only matches LLM-guessed entity type; "cross_type" = Broad, searches all entity types

relationship_typesarray (optional)

Filter by specific relationship types (e.g., ["participates_in", "leads", "works_on"])

limitinteger (optional, default: 50, range: 1-500)

Maximum number of relationships to return

Output Structure

Response Fields:

entities (array): List of entities found
id (string): Entity ID (e.g., "ACCOUNT::nike-uuid")
name (string): Entity display name (e.g., "Nike")
type (string): Entity type (e.g., "ACCOUNT", "EMPLOYEE", "TEAMS_MEETING")
attributes (object, optional): Entity attributes (key-value pairs)
aliases (array of strings): Alternative names for the entity
document_count (integer): Number of documents mentioning this entity (currently always 0 - TODO)
created_at (ISO 8601 datetime): When the entity was created in the KG
relationships (array): List of relationships found
id (string): Relationship ID (format: "SOURCE_ENTITY__RELATION_TYPE__TARGET_ENTITY")
source (object): Source entity reference
id (string): Entity ID
name (string): Entity name
type (string): Entity type
relation (string): Relationship type (e.g., "participates_in", "leads", "works_on")
target (object): Target entity reference
id (string): Entity ID
name (string): Entity name
type (string): Entity type
provenance (object, optional): Provenance information
document_id (string, optional): Document where relationship was found
chunk_index (integer, optional): Chunk index within document
confidence (float): Confidence score (0-1)
created_at (ISO 8601 datetime): When the relationship was created
query_analysis (object): Analysis of query processing
original_query (string): The original query
extracted_patterns (array, optional): Extracted relationship patterns (currently null)
seed_entities (array, optional): Seed entities used for traversal (currently null)
execution_time_ms (integer): Query execution time in milliseconds

{
  "entities": [
    {
      "id": "ACCOUNT::nike-uuid",
      "name": "Nike",
      "type": "ACCOUNT",
      "attributes": {
        "industry": "Retail",
        "deal_stage": "Negotiation"
      },
      "aliases": ["Nike Inc", "NIKE"],
      "document_count": 47,
      "created_at": "2024-09-01T10:00:00Z"
    },
    {
      "id": "EMPLOYEE::john-doe-uuid",
      "name": "John Doe",
      "type": "EMPLOYEE",
      "attributes": {
        "department": "Sales",
        "title": "Account Manager"
      },
      "aliases": ["J. Doe", "John"],
      "document_count": 23,
      "created_at": "2024-08-15T09:00:00Z"
    }
  ],
  "relationships": [
    {
      "id": "ACCOUNT::nike-uuid__participates_in__TEAMS_MEETING::meeting-123-uuid",
      "source": {
        "id": "ACCOUNT::nike-uuid",
        "name": "Nike",
        "type": "ACCOUNT"
      },
      "relation": "participates_in",
      "target": {
        "id": "TEAMS_MEETING::meeting-123-uuid",
        "name": "Nike Q4 Sync",
        "type": "TEAMS_MEETING"
      },
      "provenance": {
        "document_id": "550e8400-e29b-41d4-a716-446655440000",
        "chunk_index": 3,
        "confidence": 1.0
      },
      "created_at": "2024-10-15T14:30:00Z"
    }
  ],
  "query_analysis": {
    "original_query": "Who participates in meetings with Nike?",
    "extracted_patterns": null,
    "seed_entities": null,
    "execution_time_ms": 234
  }
}

Example cURL Request

curl -X POST "https://webhooks.trymeridian.dev/api/v1/kg/query" \
  -H "Authorization: Bearer kt_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Who participates in meetings with Nike?",
    "depth": 1,
    "matching_strategy": "cross_type",
    "relationship_types": ["participates_in", "leads", "is_assignee_of"],
    "limit": 50
  }'

Custom Entity Types & Extraction Prompts

Coming Soon: Custom entity types and extraction prompts will allow you to define your own entity types and customize the extraction process to better match your organization's specific needs. This will enable more precise entity recognition and relationship extraction tailored to your domain.

Granular Knowledge Graph Tools

Coming Soon: More granular tools for the knowledge graph are in development. These will provide lower-level access to the knowledge graph, allowing you to implement your own graph traversal algorithms directly in your applications. This will enable advanced use cases such as custom relationship discovery, complex graph queries, and specialized traversal patterns.

MCP Integration

Meridian exposes all of these exact tools through the Model Context Protocol (MCP) for integration with AI assistants like Claude Desktop, Cursor, and other AI agents.

The MCP server provides access to:

Agent Query (Internal Search Agent)
RAG Search
Filtered RAG Search
Smart Search
Filtered Smart Search
Knowledge Graph Query

All tools are accessible via the MCP protocol with the same input/output structures as documented above. For MCP-specific configuration and setup instructions, see the MCP Integration documentation.

Example MCP Configuration

Add this configuration to your MCP client (e.g., Cursor's .cursor/mcp.json or Claude Desktop's config file):

{
  "mcpServers": {
    "meridian-search": {
      "url": "https://mcp.trymeridian.dev/mcp",
      "transport": "http",
      "headers": {
        "X-API-Key": "kt_your_api_key_here"
      }
    }
  }
}