# API Cost Tracking
This MCP memory server now includes comprehensive API cost tracking for OpenAI and OpenRouter usage.
## Features
- **Real-time cost tracking** for all embedding generation operations
- **Token estimation** before API calls using tiktoken
- **Daily/monthly usage reports** via MCP tool
- **Per-user cost attribution** for multi-tenant environments
- **Automatic recording** of all API usage with metadata
## Database Schema
A new table `api_usage_tracking` stores all API usage data:
```sql
CREATE TABLE IF NOT EXISTS api_usage_tracking (
id TEXT PRIMARY KEY,
user_id TEXT NOT NULL,
api_provider TEXT NOT NULL CHECK(api_provider IN ('openai', 'openrouter')),
model TEXT NOT NULL,
tokens_used INTEGER NOT NULL DEFAULT 0,
cost_usd REAL NOT NULL,
operation_type TEXT NOT NULL,
timestamp INTEGER NOT NULL,
date TEXT NOT NULL,
metadata TEXT,
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);
```
Indexes are automatically created for:
- `(user_id, date)` - Fast per-user daily lookups
- `(api_provider, date)` - Provider-specific aggregations
- `(date)` - Global daily statistics
## Using the MCP Tool
### Get Daily Costs
Use the `get_daily_costs` tool to retrieve usage and cost information:
```json
{
"name": "get_daily_costs",
"arguments": {
"date": "2025-10-01"
}
}
```
If `date` is not provided, it defaults to today.
### Example Response
```
š Daily API Cost Report - 2025-10-01
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
OpenAI (Embeddings):
ā¢ Requests: 15
ā¢ Tokens: 4,532
ā¢ Cost: $0.0001
OpenRouter:
ā¢ Requests: 0
ā¢ Tokens: 0
ā¢ Cost: $0.0000
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
Total Daily Cost: $0.0001
Total Requests: 15
Total Tokens: 4,532
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
```
## Cost Information in Logs
All embedding operations now include cost information in stderr logs:
```
[EmbeddingService] ā
Successfully generated embedding: 1536 dimensions, 42 tokens, $0.000001, 234ms
```
## Pricing
Current pricing (as of implementation):
- **OpenAI text-embedding-3-small**: $0.02 per 1M tokens
- **OpenRouter**: Varies by model (tracked automatically when implemented)
## Token Estimation
Before making API calls, you can estimate costs:
```typescript
import { EmbeddingService } from './utils/embeddings.js';
const service = new EmbeddingService(apiKey);
const text = "Your content here...";
// Estimate tokens
const estimatedTokens = service.estimateTokens(text);
console.log(`Estimated tokens: ${estimatedTokens}`);
// Estimate cost
const estimatedCost = service.estimateCost(text);
console.log(`Estimated cost: $${estimatedCost.toFixed(6)}`);
```
## Programmatic Access
### UsageTrackingDB API
```typescript
import { UsageTrackingDB } from './database/usage-tracking.js';
const tracker = new UsageTrackingDB(db);
// Get daily usage
const today = '2025-10-01';
const dailyUsage = await tracker.getDailyUsage(userId, today);
// Get monthly usage
const monthlyUsage = await tracker.getMonthlyUsage(userId, '2025-10');
// Get all-time usage
const allTimeUsage = await tracker.getAllTimeUsage(userId);
// Get date range usage
const rangeUsage = await tracker.getUserUsageByDateRange(
userId,
'2025-10-01',
'2025-10-31'
);
```
### DailyUsageSummary Structure
```typescript
interface DailyUsageSummary {
openai: {
tokens: number;
cost: number;
requests: number;
};
openrouter: {
tokens: number;
cost: number;
requests: number;
};
total: {
tokens: number;
cost: number;
requests: number;
};
}
```
## Implementation Details
### Automatic Tracking
Cost tracking is automatically enabled when:
1. A database connection is provided to `EmbeddingService`
2. The `OPENAI_API_KEY` environment variable is set
### What Gets Tracked
For each embedding generation:
- **User ID**: For multi-tenant attribution
- **API Provider**: `openai` or `openrouter`
- **Model**: e.g., `text-embedding-3-small`
- **Tokens Used**: Actual count from API response
- **Cost USD**: Calculated based on provider pricing
- **Operation Type**: e.g., `embedding`
- **Timestamp**: Unix timestamp in milliseconds
- **Date**: ISO date string (YYYY-MM-DD)
- **Metadata**: Duration, batch size, etc.
### Performance Impact
- Minimal overhead: ~1-2ms per operation
- Non-blocking: Usage recording failures don't affect embedding generation
- Indexed queries: Fast aggregation even with large datasets
## Migration from Existing Installation
If you have an existing installation:
1. The `api_usage_tracking` table will be created automatically on next startup
2. Existing memories will not have cost tracking (only new operations)
3. No data migration required
## Privacy Considerations
- Only metadata is stored (no actual content)
- User IDs are hashed (if using API key authentication)
- Can be disabled by not providing database connection to EmbeddingService
## Troubleshooting
### Cost tracking not working?
1. Verify database connection is passed to EmbeddingService:
```typescript
new EmbeddingService(apiKey, model, db)
```
2. Check that table was created:
```sql
SELECT name FROM sqlite_master WHERE type='table' AND name='api_usage_tracking';
```
3. Verify user ID is available:
```typescript
console.error('User ID:', userId);
```
### No data showing in reports?
1. Ensure embeddings have been generated since installation
2. Check correct date format: `YYYY-MM-DD`
3. Verify user ID matches
## Future Enhancements
Potential additions:
- Cost budget alerts and limits
- Weekly/monthly cost reports via email
- Cost breakdown by memory type or entity
- Export cost data to CSV/JSON
- Integration with billing systems
- OpenRouter cost tracking (when implemented)
## Testing
Run cost tracking tests:
```bash
npm test -- tests/unit/cost-tracking.test.ts
```
## Files Modified/Added
**New Files:**
- `src/database/usage-tracking.ts` - Usage tracking database operations
- `tests/unit/cost-tracking.test.ts` - Unit tests
- `docs/COST_TRACKING.md` - This documentation
**Modified Files:**
- `src/database/schema.ts` - Added `api_usage_tracking` table
- `src/utils/embeddings.ts` - Enhanced with cost tracking
- `src/core/memory-core.ts` - Pass userId to embeddings
- `src/desktop-mcp-server.ts` - Added `get_daily_costs` tool
- `package.json` - Added `tiktoken` dependency
## Support
For issues or questions about cost tracking:
1. Check this documentation
2. Review implementation in `src/database/usage-tracking.ts`
3. Examine test cases in `tests/unit/cost-tracking.test.ts`
