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

# Search & Filters

> Semantic search, metadata filters, graph traversal depth, and unified search across all memory types.

## Basic search

```python theme={null}
results = m.search("deployment stack")
# Returns top 5 entities by relevance
```

## Parameters

| Parameter     | Type | Default   | Description                                      |
| ------------- | ---- | --------- | ------------------------------------------------ |
| `query`       | str  | required  | Natural language search query                    |
| `limit`       | int  | 5         | Maximum results to return                        |
| `graph_depth` | int  | 2         | How many hops to traverse in the knowledge graph |
| `user_id`     | str  | "default" | User whose memories to search                    |
| `filters`     | dict | None      | Metadata key-value filters                       |

## Metadata filters

Filter search results by metadata stored on entities. Uses PostgreSQL JSONB containment (`@>`) for fast filtering with GIN indexes.

```python theme={null}
# Filter by agent
results = m.search("config", filters={"agent_id": "support-bot"})

# Filter by app
results = m.search("preferences", filters={"app_id": "prod"})

# Multiple filters (AND logic)
results = m.search("issues", filters={
    "agent_id": "support-bot",
    "app_id": "production",
})

# Also works with shorthand parameters
results = m.search("config", agent_id="support-bot", app_id="prod")

# Filter by provenance source
results = m.search("meeting notes", filters={"source": "slack"})

# Filter by custom metadata
results = m.search("bugs", filters={"source": "discord", "channel": "#engineering"})
```

## Graph RAG (graph depth)

Mengram uses Graph RAG — retrieval-augmented generation over a knowledge graph. Instead of flat vector search, it traverses entity relationships to find connected context.

```
Query: "database issues"
  → Direct: PostgreSQL (technology)
    → 1 hop: Railway (platform) — "deployed_on"
      → 2 hop: OOM Bug (event) — "occurred_on" → Railway
```

Searching for "database issues" also surfaces that OOM bug on Railway — connected through the knowledge graph, not through keyword or embedding similarity.

Control traversal depth with `graph_depth`:

```python theme={null}
# Shallow — just direct matches, fastest
results = m.search("Python", graph_depth=0)

# Default — 2 hops (entity → related → related)
results = m.search("Python", graph_depth=2)

# Deep — traverse far connections, slower but more context
results = m.search("Python", graph_depth=4)
```

## Unified search

Search all 3 memory types in a single call:

```python theme={null}
results = m.search_all("deployment problems")

# Semantic — knowledge graph entities with facts
for entity in results["semantic"]:
    print(entity["entity"], entity["facts"])

# Episodic — events and experiences
for event in results["episodic"]:
    print(event["summary"], event["outcome"])

# Procedural — workflows and processes
for proc in results["procedural"]:
    print(proc["name"], proc["steps"])
```

## Timeline search

Search facts by time range:

```python theme={null}
facts = m.timeline(after="2026-01-01", before="2026-02-01")
for f in facts:
    print(f["created_at"], f["entity"], f["fact"])
```