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

# mem_stats

> Show memory system statistics

## Overview

Retrieve high-level statistics about the memory system — total sessions, observations, prompts, and tracked projects. Useful for understanding the scope of stored memories and validating that data is being captured.

<Note>
  This tool is part of the **admin** profile and uses deferred loading. It's designed for dashboards, TUIs, and manual inspection rather than routine agent operations.
</Note>

## Parameters

This tool takes no parameters.

## Response

<ResponseField name="result" type="string">
  Formatted statistics summary
</ResponseField>

The response includes:

* **Sessions**: Total number of coding sessions tracked
* **Observations**: Total observations (memories) saved
* **Prompts**: Total user prompts recorded
* **Projects**: Comma-separated list of project names

**Example:**

```
Memory System Stats:
- Sessions: 47
- Observations: 312
- Prompts: 89
- Projects: engram, my-api, frontend-app, infrastructure
```

## Usage Example

### Get Current Stats

```json theme={null}
{}
```

**Response:**

```
Memory System Stats:
- Sessions: 47
- Observations: 312
- Prompts: 89
- Projects: engram, my-api, frontend-app, infrastructure
```

### Empty Database

If no data exists yet:

```
Memory System Stats:
- Sessions: 0
- Observations: 0
- Prompts: 0
- Projects: none yet
```

## When to Use

* **System health**: Verify that memories are being captured
* **Dashboard display**: Show metrics in a TUI or web interface
* **Data validation**: Confirm memory system is working after setup
* **Project overview**: See which projects have been tracked

## Stats Structure

The underlying `Stats` type from `internal/store/store.go` contains:

```go theme={null}
type Stats struct {
    TotalSessions     int      `json:"total_sessions"`
    TotalObservations int      `json:"total_observations"`
    TotalPrompts      int      `json:"total_prompts"`
    Projects          []string `json:"projects"`
}
```

## Agent vs Admin Profile

<Info>
  **Why is this in the admin profile?**

  AI agents don't typically need system-wide statistics during coding sessions. This tool is designed for:

  * Human operators using the TUI (`engram tui`)
  * Dashboard applications
  * CLI inspection (`engram stats` if implemented)
  * Manual curation and maintenance

  If you're building an agent that needs stats, you can include it via:

  ```bash theme={null}
  engram mcp --tools=agent,admin
  ```
</Info>

## Performance

This tool counts records across the database, which is fast for SQLite but uses deferred loading to avoid including it in every MCP initialization.

## Related Tools

* [`mem_context`](/mcp/mem-context) - Get recent session context (agent-facing)
* [`mem_timeline`](/mcp/mem-timeline) - View chronological observation context
* [`mem_search`](/mcp/mem-search) - Search observations

## HTTP API Alternative

You can also retrieve stats via the HTTP API:

```bash theme={null}
GET http://localhost:8080/api/stats
```

See [API Reference: Stats](/api/overview#stats-endpoint) for details.