> Markdown export: /developers/first-memory-walkthrough.md
> HTML: /developers/first-memory-walkthrough
---
description: End-to-end tutorial — capture a thought, search memories, and get a grounded answer via MCP.
audience: integrator
---

# First memory walkthrough

> **In plain terms:** A hands-on tutorial — capture a thought, search your memories, and get a grounded answer through your connected AI assistant.

This walkthrough assumes you completed [Connect Cursor or Claude](/developers/cursor-and-claude) and have a working MCP connection.

## Who this is for

- **Integrators** validating an MCP connection with hands-on tool calls
- **Self-hosted users** who finished Cursor or Claude setup

## Step 1 — Capture a thought

Ask your assistant to store a memory, or invoke the tool directly if your client exposes raw MCP calls:

**Tool:** `capture_thought`

```json
{
  "raw": "I'm building a side project using SvelteKit and PostgreSQL. Deadline is end of Q3."
}
```

**Expected result:** A success response with a thought `id` and a natural-language summary of what was stored. Behind the scenes, Eigen Mesh normalizes the text, classifies it, computes an embedding, updates the lexical index, and syncs graph nodes in Apache AGE.

## Step 2 — Browse recent thoughts

**Tool:** `retrieve_thoughts`

```json
{
  "order": "created_at",
  "top_k": 10
}
```

**Expected result:** Your most recent open thoughts, newest first. Results are scoped to your user only (text fields — no embedding vectors).

You should see the thought from Step 1 in the list.

## Step 3 — Search memories

**Tool:** `retrieve_thoughts`

```json
{
  "query": "What tech stack am I using for my side project?",
  "top_k": 5
}
```

**Expected result:** Ranked matches with `normalizedText`, `category`, and fused `score`. Hybrid retrieval combines pgvector similarity, PostgreSQL full-text search, and precomputed graph neighbors — then an LLM listwise reranker refines the top results.

Optional: `"threshold": 0.3` filters results below a normalized score in `[0, 1]`.

## Step 4 — Ask a grounded question

HTTP MCP has no `answer_question` tool. Ask your assistant to answer from retrieved context, or call `retrieve_thoughts` first:

**Tool:** `retrieve_thoughts`

```json
{
  "query": "When is my side project deadline?",
  "top_k": 5
}
```

**Expected result:** Ranked thought matches. Your assistant (or you) composes a natural-language answer citing the returned thought ids — reducing hallucination by grounding in retrieved text only.

> **Tip:** The in-app **Chat** UI (`/chat`) does retrieve-then-compose automatically.

## Step 5 — Edit a memory

**Tool:** `edit_thought`

```json
{
  "thought_id": "<id-from-step-1>",
  "edit_request": "Change the deadline to end of Q4 instead of Q3."
}
```

**Expected result:** Updated thought summary. The system re-embeds and refreshes graph links.

## What you learned

| Step | Tool | Operation |
|------|------|-----------|
| 1 | `capture_thought` | Write |
| 2 | `retrieve_thoughts` (`order=created_at`) | Browse recent |
| 3 | `retrieve_thoughts` (`query`) | Hybrid search |
| 4 | `retrieve_thoughts` + client compose | Retrieve + answer |
| 5 | `edit_thought` | Update |

## Troubleshooting

See [Troubleshooting](/developers/troubleshooting) if tool calls fail or return empty results.

## Next steps

- [How memory works](/developers/how-memory-works) — pipeline behind these tools
- [MCP tools reference](/developers/mcp-tools) — full contracts
- [HTTP API overview](/developers/http-api) — REST endpoints for custom apps