Skip to main content

​
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.
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.

​
Parameters

This tool takes no parameters.

​
Response

​
result
string
Formatted statistics summary
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

{}
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: 
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

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:
engram mcp --tools=agent,admin

​
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.

​
HTTP API Alternative

You can also retrieve stats via the HTTP API: 
GET http://localhost:8080/api/stats
See API Reference: Stats for details.

Build docs developers (and LLMs) love

Get started for freeTalk to us