get_stats

Get statistics about the knowledge base, memory graph, conversations, and insights. Use scope to select which stats to return.

Parameters

Parameter	Type	Required	Default	Description
`scope`	enum	No	`all`	Which stats to return: `all`, `knowledge`, `memory`, `conversations`, `insights`

Example Requests

All Stats

{}

Returns stats for all enabled features. Disabled features are silently skipped.

Specific Scope

{ "scope": "memory" }

Returns only memory stats. Returns an error if the feature is disabled.

Response

Scope: all

{
  "knowledge": {
    "total": 150,
    "bySourceType": { "note": 80, "file": 65, "url": 5 },
    "byContentType": { "email": 30, "document": 120 },
    "topTags": [{ "tag": "work", "count": 45 }, { "tag": "planning", "count": 20 }],
    "dateRange": { "oldest": "2024-01-15T10:00:00Z", "newest": "2026-01-05T14:30:00Z" }
  },
  "memory": {
    "totalEntities": 25,
    "totalObservations": 150,
    "totalRelations": 30,
    "entityTypeCounts": { "person": 10, "project": 8, "concept": 5, "organization": 2 }
  },
  "conversations": {
    "totalSessions": 15,
    "sessionsWithSummary": 12,
    "totalTurns": 340,
    "turnsWithEmbedding": 280
  },
  "insights": {
    "total": 8,
    "new": 3,
    "seen": 4,
    "dismissed": 1,
    "byType": { "cross_reference": 5, "entity_bridge": 2, "theme": 1 },
    "queueState": { "chunks_pending": 0, "is_processing": false, "last_scan_at": "2026-01-05T10:00:00Z" }
  }
}

Compact Mode

When COMPACT_RESPONSES=true, stats use abbreviated keys. Knowledge stats pass through unchanged; memory, conversations, and insights use compact keys:

{
  "knowledge": { "total": 150, "bySourceType": { "note": 80 }, "byContentType": { "email": 30 }, "topTags": [{ "tag": "work", "count": 45 }], "dateRange": { "oldest": "...", "newest": "..." } },
  "memory": { "ent": 25, "obs": 150, "rel": 30, "byType": { "person": 10 } },
  "conversations": { "sess": 15, "indexed": 12, "turns": 340, "turnIdx": 280 },
  "insights": { "n": 8, "new": 3, "seen": 4, "dis": 1, "types": {}, "q": { "p": 0, "proc": false, "last": "..." } }
}

Output Schema

This tool MUST return structuredContent alongside the text response. The structuredContent object MUST use canonical verbose keys regardless of the COMPACT_RESPONSES setting.

Field	Type	Description
`knowledge`	object	Knowledge base stats (when scope includes knowledge)
`knowledge.total`	integer	Total documents
`knowledge.bySourceType`	object	Count by source type
`knowledge.byContentType`	object	Count by content type
`knowledge.topTags`	array	Top tags with counts
`knowledge.topTags[].tag`	string	Tag name
`knowledge.topTags[].count`	integer	Number of documents with this tag
`knowledge.dateRange`	object	Oldest/newest document dates
`knowledge.dateRange.oldest`	string?	ISO timestamp of oldest document
`knowledge.dateRange.newest`	string?	ISO timestamp of newest document
`memory`	object	Memory stats (when scope includes memory)
`memory.totalEntities`	integer	Total entities
`memory.totalObservations`	integer	Total observations
`memory.totalRelations`	integer	Total relations
`memory.entityTypeCounts`	object	Count by entity type
`conversations`	object	Conversation stats (when scope includes conversations)
`conversations.totalSessions`	integer	Total sessions
`conversations.sessionsWithSummary`	integer	Sessions with summaries
`conversations.totalTurns`	integer	Total turns
`conversations.turnsWithEmbedding`	integer	Turns with embeddings
`insights`	object	Insight stats (when scope includes insights)
`insights.total`	integer	Total insights
`insights.new`	integer	New insights
`insights.seen`	integer	Seen insights
`insights.dismissed`	integer	Dismissed insights
`insights.byType`	object	Count by insight type
`insights.queueState`	object?	Processing queue state (null if unavailable)
`insights.queueState.chunks_pending`	integer	Chunks awaiting processing
`insights.queueState.is_processing`	boolean	Whether a scan is in progress
`insights.queueState.last_scan_at`	string?	ISO timestamp of last scan

Scope Behavior

Scope	Feature Flag	Behavior
`all`	-	Returns all enabled features, silently skips disabled ones
`knowledge`	always available	Returns knowledge base stats
`memory`	`ENABLE_MEMORY`	Returns memory stats, error if disabled
`conversations`	`ENABLE_CONVERSATIONS`	Returns conversation stats, error if disabled
`insights`	`ENABLE_INSIGHTS`	Returns insight stats, error if disabled or schema not initialized

Use Cases

Health Check

Verify all systems are working:

{ "scope": "all" }

Capacity Planning

Monitor specific subsystem growth:

{ "scope": "knowledge" }

Debugging

Check if memories are being created as expected:

{ "scope": "memory" }

Errors

Error	Cause	Fix
Database not configured	Missing Supabase credentials	Set `SUPABASE_URL` and `SUPABASE_SERVICE_KEY`
Memory feature disabled	`ENABLE_MEMORY=false` and scope=memory	Set `ENABLE_MEMORY=true`
Conversations feature disabled	`ENABLE_CONVERSATIONS=false` and scope=conversations	Set `ENABLE_CONVERSATIONS=true`
Insights feature disabled	`ENABLE_INSIGHTS=false` and scope=insights	Set `ENABLE_INSIGHTS=true`
Insight schema not initialized	Missing insight tables	Run the insight schema SQL

search - Search across the knowledge base
query_memory - Query memory graph
query_conversations - Query past conversations
get_insights - View discovered insights

On this page