---
mode: subagent
---

<!-- SPDX-License-Identifier: MIT -->
<!-- SPDX-FileCopyrightText: 2025-2026 Marcus Quinn -->
# t1338.5: Usage logging and disk management

## Origin

- **Created:** 2026-02-26
- **Session:** claude-code:interactive
- **Created by:** ai-interactive
- **Parent task:** t1338 (Local AI model inference via llama.cpp)
- **Conversation context:** Part of the p032 plan to add local model inference. This task adds the data layer for tracking model usage and managing disk space.

## What

SQLite-backed usage logging and disk management for local AI models:
1. `model_usage` table — per-request logging with session ID tracking
2. `model_inventory` table — downloaded model registry with size, source, quantization
3. Session-start nudge when stale models exceed 5 GB
4. Migration from legacy DB path/schema

## Why

Models are 2-50+ GB each. Without usage tracking and cleanup recommendations, disk usage grows unbounded. Per-session logging enables cost comparison between local and cloud tiers. The nudge prevents users from accumulating unused models without realizing it.

## How (Approach)

- Extend `local-model-helper.sh` with new DB path (`~/.aidevops/.agent-workspace/memory/local-models.db`)
- Rename tables: `usage` -> `model_usage`, `model_access` -> `model_inventory`
- Add `session_id` column to `model_usage` (auto-detected from `CLAUDE_SESSION_ID` / `OPENCODE_SESSION_ID`)
- Add `model_inventory` with `file_path`, `repo_source`, `size_bytes`, `quantization` columns
- New `nudge` command for session-start stale model check
- New `inventory` command for DB-backed model listing
- Migration logic for existing legacy DBs
- Update `local-models.md` documentation

## Acceptance Criteria

- [ ] `model_usage` table exists with session_id column

<!-- verify:bash sqlite3 ~/.aidevops/.agent-workspace/memory/local-models.db '.schema model_usage' 2>/dev/null | grep -q session_id || echo 'SKIP: DB not initialized yet' -->

- [ ] `model_inventory` table exists with size_bytes, repo_source columns

<!-- verify:bash sqlite3 ~/.aidevops/.agent-workspace/memory/local-models.db '.schema model_inventory' 2>/dev/null | grep -q size_bytes || echo 'SKIP: DB not initialized yet' -->

- [ ] `nudge` command outputs nothing when no stale models

<!-- verify:codebase pattern="cmd_nudge" path=".agents/scripts/local-model-helper.sh" -->

- [ ] `inventory` command shows model inventory from DB

<!-- verify:codebase pattern="cmd_inventory" path=".agents/scripts/local-model-helper.sh" -->

- [ ] Legacy DB migration preserves existing data

<!-- verify:codebase pattern="_migrate_legacy_db" path=".agents/scripts/local-model-helper.sh" -->

- [ ] ShellCheck clean

<!-- verify:bash shellcheck .agents/scripts/local-model-helper.sh -->

- [ ] Documentation updated with new schema and commands

<!-- verify:codebase pattern="model_usage.*model_inventory" path=".agents/tools/local-models/local-models.md" -->

## Context & Decisions

- DB moved from `~/.aidevops/local-models/usage.db` to `~/.aidevops/.agent-workspace/memory/local-models.db` to be consistent with other framework SQLite DBs
- Tables renamed from `usage`/`model_access` to `model_usage`/`model_inventory` per issue spec
- 5 GB nudge threshold chosen because a single model is typically 2-8 GB, so this triggers when 1-2+ models are stale
- Session ID auto-detected from environment variables set by Claude Code and OpenCode
- Migration is non-destructive — legacy DB is preserved after migration

## Relevant Files

- `.agents/scripts/local-model-helper.sh` — main implementation
- `.agents/tools/local-models/local-models.md` — documentation
- `.agents/scripts/shared-constants.sh` — shared utilities (backup_sqlite_db used for migration)

## Dependencies

- **Blocked by:** t1338.4 (llama.cpp binary management)
- **Blocks:** t1338.6+ (model routing integration)
- **External:** sqlite3 (standard on macOS/Linux)

## Estimate Breakdown

| Phase | Time | Notes |
|-------|------|-------|
| Research/read | 15m | Understand existing schema and issue requirements |
| Implementation | 1h | Schema, migration, nudge, inventory commands |
| Testing | 15m | ShellCheck, functional verification |
| **Total** | **~1.5h** | |
