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

# Querying memories

> Search, ask, and timeline from Python

<Info>
  **Query Methods** - Use `find()` for keyword/semantic search, `ask()` for RAG-powered Q\&A with context synthesis, and `timeline()` for chronological retrieval. All methods return structured dicts matching CLI JSON output format.
</Info>

```python theme={null}
from memvid_sdk import use

mv = use("basic", "notes.mv2")
hits = mv.find("deterministic", k=5, mode="lex")
answer = mv.ask("Why is the WAL embedded?", mode="auto", context_only=True)
timeline = mv.timeline(since=1730000000, until=1730003600, limit=10)
```

* `find` returns a list of dicts containing `frame_id`, `score`, `preview`, and metadata identical to CLI JSON output
* `ask` returns a dict with `answer`, `context`, and ranked hits (semantic/hybrid require `enable_vec=True`)
* `timeline` yields chronological entries by scanning the Time Index Track; falls back gracefully when absent

### Permission-Aware Retrieval (ACL)

`find()` and `ask()` support permission-aware retrieval via `acl_context` + `acl_enforcement_mode`.

See [Permission-Aware Retrieval (ACL)](/concepts/permission-aware-retrieval).

```python theme={null}
hits = mv.find(
    "budget",
    mode="lex",
    k=5,
    acl_context={"tenant_id": "tenant-123", "roles": ["finance"]},
    acl_enforcement_mode="enforce",
)["hits"]
```

### Reading frame payloads

Use the hit URI to fetch metadata (`frame`) or bytes (`blob`):

```python theme={null}
hit = hits["hits"][0]
uri = hit["uri"]
meta = mv.frame(uri)
payload_bytes = mv.blob(uri)
```

### Error handling

All methods raise the same typed exceptions as the CLI. Catch `LockedError`, `CapacityExceededError`, etc., to mirror CLI messaging and make it easier to follow the troubleshooting guidance in the Golden Test Pack.

> **Testing** - Reuse the Golden Corpus to validate search + timeline outputs in Python integration tests to keep parity with CLI regressions.