---
slug: searching
title: "Searching"
description: "It finds by meaning and connection, not keyword matching. `@` attribution, causal and time questions, and how to read a result."
lang: en
---


# Searching

AiAkiv's search is **meaning plus connection**, not keyword matching. Used well,
it answers questions keywords can't.

## The basic move: just ask in plain language

```
ak how did the combat system design change?
```

Search defaults to **hybrid** (events + entities, meaning-based), so it finds
things even when no word overlaps. Each result carries:

- **reason**: why this matched (similar embedding / shared entity / sequential
  link, and so on)
- **the link map (hint)**: which threads, entities, and topics tie the results
  together

**Don't read the results flat: read the reason and the link map with them.**
When you ask for "latest" or "related", a similar-embedding marker often points
at a synonym whose name changed; follow it and more turns up.

## When the summary isn't enough, pull the original

Search gives you the event **summary**. A summary is LLM-generated, so it can
occasionally be inaccurate. When you need the exact content, use **fetch full
text** to pull the event's original.

## Narrow by author or team with `@`

Who wrote a memory is stamped by the server at save time (it can't be forged). An
`@handle` at the **very start** of the query is the attribution filter.

- `@alice@example.com`: browse that person's events, newest first
- `@alice@example.com save bug`: search **within** that person's scope
- `@teamname ...` Filter to content attributed to that team

An ordinary tag can't start with `@`, which is why "who wrote this" can't be
forged by a client or an AI.

## The questions keywords can't do: where AiAkiv earns its place

These are where AiAkiv shines, because keywords fail **structurally**.

- **Causal and temporal jumps:** "which **past decision** caused this bug?" From
  the bug event, back along the causal link and the timeline to the earlier
  decision. (Tying the cause in at save time is what pays off here →
  [Saving](saving).)
- **Shared-entity connections:** "**why did** inventory and save-files change
  **together**?" Through the entity the two events share.
- **Change history:** "show me the **history** of balance tuning". Events on the
  same topic laid along a timeline.

Open-ended questions about the most recent thing work well too: **"what's the
latest bug and what caused it?"**: you don't have to name a specific bug; the
graph brings back the recent event and its causes.

## The server decides the search scope

The search scope (domains, tags) is **decided by the server from its access
policy**: a client cannot widen or narrow it through the query. The response's
`searched_scope` tells you the scope actually applied. "What I can read within my
team" is the ceiling. If you want only one domain, **filter the results**; don't
put a domain filter in the query (that can silently drop data).

## Next

- Saving well → [Saving](saving)
- When results aren't what you expected → [Common problems](faq)