skills.rest
shiwenwen
shiwenwenCOMMUNITY
Explore all skills by this author →
GitHub

ha-data-stores

Inspect Hope Agent's local SQLite data stores with read-only diagnostic queries.

1.6k|149|Updated Mar 13, 2026
Search Tags:#sqlite#Debugging#Diagnostics#data stores#database inspection#read-only queries#hope agent
One-click install
npx skills add https://github.com/shiwenwen/hope-agent --skill ha-data-stores
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: ha-data-stores
Source: https://github.com/shiwenwen/hope-agent/tree/main/skills/ha-data-stores
Command: npx skills add https://github.com/shiwenwen/hope-agent --skill ha-data-stores

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

When debugging or auditing Hope Agent, you often need to know where sessions, memories, logs, background jobs, and knowledge indexes are persisted and how to inspect them safely without corrupting app state.

Core Features & Use Cases

  • Data Store Map: Documents every database (sessions.db, memory.db, logs.db, background_jobs.db, cron.db, knowledge index) and important non-DB paths under the Hope Agent data root.
  • Safe Read-Only Query Patterns: Provides sqlite3 -readonly and Python read-only URI patterns, plus ready-made SQL for sessions, messages FTS, logs, background jobs, and memories.
  • Tool-First Priority Workflow: Directs you to dedicated model tools (sessions_search, recall_memory, get_settings, job_status) before falling back to raw SQL.
  • Use Case: A user asks "where are my chat sessions stored and why did a background job fail?" Use this Skill to locate sessions.db and background_jobs.db, then run bounded read-only queries to diagnose the issue.

Quick Start

Ask the agent to show the 10 most recently updated sessions from the Hope Agent local database using a read-only SQLite query.

Frequently Asked Questions about ha-data-stores

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Where does Hope Agent store its local data?▼

Hope Agent stores all app-managed data under the data root: the HA_DATA_DIR environment variable if set, otherwise ~/.hope-agent. This directory contains sessions.db, memory.db, logs.db, background_jobs.db, config.json, and other stores.

How do I query Hope Agent's SQLite databases safely?▼

Use the sqlite3 CLI with the -readonly flag, or Python's sqlite3 with a file: URI using mode=ro. Never run UPDATE, DELETE, INSERT, DROP, CREATE, ALTER, VACUUM, REINDEX, or ATTACH against app databases.

Should I use SQL or the built-in tools to search chat messages?▼

Prefer the dedicated sessions_search and sessions_history tools first. Use raw SQL against sessions.db and the messages_fts full-text index only when the tools are too coarse or the task is diagnostic or audit work.

Can I edit the knowledge index database directly?▼

No. The knowledge/index.db file is a rebuildable search cache, while the actual notes are Markdown files that serve as the source of truth. Rebuild the index through product flows instead of editing it.

Why does my query return different results than the product tools?▼

When direct SQL contradicts a product tool result, trust the product tool for user-facing behavior. Use SQL only to explain the discrepancy, since tools may apply additional filtering or business logic.

Related Skills

Explore More Software Engineering Skills→
mainion-aimainion-ai
12

mk-memory-setup

Configure host-based memory-kernel environment for NanoClaw agent persistence.

Community
Advanced
patternincpatterninc
57

autonomy--sre-agent

Diagnose production issues by querying logs, metrics, and traces from CLIs.

Official
Advanced
jagreehaljagreehal
3

observability

Wrap business logic with trace() and structured logs using OpenTelemetry conventions.

Community
Intermediate
huangzthuangzt
17

sqlite-tools

Execute SQL queries and inspect schemas in SQLite database files.

Community
Intermediate