> Markdown export: /developers/how-memory-works.md
> HTML: /developers/how-memory-works
---
description: User-facing overview of the Eigen Mesh memory pipeline — capture, enrichment, retrieval, and consolidation.
audience: end-user
---

# How memory works

> **In plain terms:** You drop in thoughts as they come. Eigen Mesh organizes them in the background and makes them searchable later — in the browser or through connected AI tools — without you filing, tagging, or repeating context every session.

## Who this is for

- **End users** capturing and searching memories in the browser or via connected AI tools
- **Integrators** who want to understand what happens after `capture_thought` and `retrieve_thoughts`

## The pipeline in everyday terms

1. **Capture** — Type or dictate a thought. No structure required upfront.
2. **Organize** — Eigen Mesh classifies, links, and indexes what you saved automatically.
3. **Retrieve** — Search or ask a question; relevant memories surface with citations.
4. **Consolidate** — Overnight, less important memories fade while connections strengthen.

You own your data in all deployment modes. Self-hosted operators control infrastructure; managed users retain export/delete guarantees. See [Deployment model](/developers/deployment-model).

---

## Technical details

### Pipeline overview

```mermaid
flowchart LR
  Capture[Capture raw thought]
  Enrich[Enrich classify embed]
  Store[(Postgres pgvector)]
  Graph[(Apache AGE graph)]
  Materialize[Materialize neighbors bundles]
  Retrieve[Hybrid retrieval rerank]
  Compose[Grounded answer]
  Sleep[Nightly consolidation]

  Capture --> Enrich
  Enrich --> Store
  Enrich --> Graph
  Graph --> Materialize
  Materialize --> Retrieve
  Store --> Retrieve
  Retrieve --> Compose
  Store --> Sleep
  Graph --> Sleep
```

### 1. Capture

You submit unstructured text (type or dictate in the browser). Dictation uses server-side speech-to-text (billed like other LLM calls on platform credits). No filing, tagging, or structure required upfront.

- **Browser UI:** `/capture` with optional offline queue (IndexedDB + Background Sync)
- **MCP:** `capture_thought`
- **REST:** `POST /api/capture/submit`

### 2. Enrichment (ingestion)

On persist, the server:

1. Normalizes and classifies the text (ontology categories: thought, task, idea, reference, date, person)
2. Computes an embedding and stores it in **pgvector** (never returned to tools or LLM prompts)
3. Builds lexical search tokens (`tsvector` / FTS) and `lexical_text` for keyword recall
4. Syncs nodes and edges in **Apache AGE** (OpenCypher graph in the same Postgres instance)
5. Materializes `thought_neighbor`, `thought_entity`, and community bundles for fast retrieval
6. Extracts entities and relations; logs activity with transparent per-call cost

Ontology profile refreshes every 10th captured thought.

### 3. Retrieval

When you search or ask a question:

1. **Vector channel** — pgvector approximate nearest neighbor on query embedding
2. **Lexical channel** — PostgreSQL full-text search over `lexical_text` and cues
3. **Graph channel** — precomputed neighbors, entity-anchored paths, and community bundles (no live AGE traversal at query time)
4. **Fusion** — weighted merge of channels, then **LLM listwise rerank** over the top candidate pool

Surfaces: MCP `retrieve_thoughts`, REST `/api/retrieval/search`, in-app **Chat** UI.

Browse recent thoughts via MCP `retrieve_thoughts` with `order=created_at` (no query).

### 4. Grounded answers

The in-app **Chat** agent calls `retrieve_thoughts`, then composes a natural-language answer with citations in the agent loop. HTTP MCP clients do the same two-step pattern in their own client — there is no `answer_question` MCP tool.

The LLM sees **text and scores only** — not embedding vectors ([Embeddings boundary](/developers/embeddings-boundary)).

### 5. Consolidation (sleep)

Nightly pg_cron triggers consolidation:

| Phase | What happens |
|-------|----------------|
| **Deep sleep** | Salience decay, ontology prune, entity dedup |
| **REM** | Community detection, community summaries and bundles for retrieval |

Salience also bumps when you access memories during the day (reconsolidation).

## Troubleshooting

See [Troubleshooting](/developers/troubleshooting) for retrieval and capture issues.

## Next steps

- [Architecture overview](/developers/architecture) — system domains
- [MCP overview](/developers/mcp-overview) — connect your assistant
- [Embeddings boundary](/developers/embeddings-boundary) — security policy