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

# Stats & diagnostics

> Get health metrics and memory usage statistics for Memory Crystal.

Retrieve aggregate statistics about your Memory Crystal memory store including counts, strength distribution, capture rate, and strongest memories.

## What this means in practice

Use `crystal_stats` to:

* Monitor total memory count and archive status
* Understand memory distribution across stores (sensory, episodic, semantic, procedural, prospective)
* Check recent capture activity (captures in the last 24 hours)
* Identify the strongest memories by strength score
* Assess overall health and usage patterns

## Parameters

| Parameter | Type   | Required | Description                                                                 |
| --------- | ------ | -------- | --------------------------------------------------------------------------- |
| `channel` | string | No       | Optional channel identifier. If provided, stats are scoped to that channel. |

## Returns

```json theme={"system"}
{
  "totalMemories": 342,
  "archivedCount": 28,
  "avgStrength": 0.756,
  "recentCaptures": 12,
  "byStore": {
    "sensory": 89,
    "episodic": 156,
    "semantic": 54,
    "procedural": 32,
    "prospective": 11
  },
  "strongest": [
    {
      "title": "Chose Convex over Supabase for backend",
      "store": "semantic",
      "strength": 0.95,
      "category": "decision",
      "id": "mem_xyz123"
    },
    {
      "title": "Deploy via Railway + git push",
      "store": "procedural",
      "strength": 0.91,
      "category": "workflow",
      "id": "mem_abc456"
    }
  ]
}
```

The response also includes a formatted markdown summary:

```
## Memory Crystal Stats
- Total memories: 342
- Archived memories: 28
- Average strength: 0.756
- Captures last 24h: 12

## Store counts
- sensory: 89
- episodic: 156
- semantic: 54
- procedural: 32
- prospective: 11

## Strongest
1. Chose Convex over Supabase for backend (semantic) — 0.95
2. Deploy via Railway + git push (procedural) — 0.91
```

## Examples

**Get global stats:**

```json theme={"system"}
{}
```

**Get stats for a specific channel:**

```json theme={"system"}
{
  "channel": "dev-team"
}
```

## Interpreting the results

* **`totalMemories`** — cumulative memories ever created (including archived)
* **`archivedCount`** — memories marked as archived; not recalled by default
* **`avgStrength`** — mean strength across all active memories; indicates overall salience
* **`recentCaptures`** — automatic captures in the last 24 hours from `crystal_capture` hook
* **`byStore`** — distribution across the five memory types
* **`strongest`** — top-N memories by strength; useful for identifying what the system prioritizes

## When to use vs alternatives

| Use case                          | Tool                                      |
| --------------------------------- | ----------------------------------------- |
| Overall health & usage snapshot   | **`crystal_stats`**                       |
| Recall a specific memory by query | `crystal_recall`                          |
| List all memories (not summary)   | Use dashboard or `crystal_what_do_i_know` |
| Check recent messages             | `crystal_recent`                          |

## Error handling

| Error                         | Cause                                              | Resolution                                                                |
| ----------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------- |
| Embedding service unavailable | The API cannot reach the embedding backend.        | Retry; check service health.                                              |
| Memory Crystal not configured | Environment variables not set.                     | Ensure `MEMORY_CRYSTAL_API_URL` and `MEMORY_CRYSTAL_API_KEY` are defined. |
| Invalid channel               | Channel identifier is malformed or does not exist. | Verify the channel name.                                                  |

## Source of truth

* `mcp-server/src/tools/stats.ts` — tool definition
* `convex/crystal/stats.ts` — backend calculation logic
* `apps/web/app/(dashboard)/` — stats visualization in the dashboard