ha-data-stores

Hope Agent Data Stores

Use this skill when you need to locate or inspect Hope Agent's persisted local data. Prefer product tools first; use direct SQLite only for diagnostics or ad-hoc analysis that existing tools do not cover.

Priority order

1. Use dedicated model tools when they answer the question:
   • sessions_search for finding exact details in current or historical chat messages.
   • sessions_history for paginated transcript reading once a session is known.
   • recall_memory / memory_get for user/project/agent memory.
   • note_* / knowledge_recall for attached knowledge spaces.
   • get_settings for AppConfig settings.
   • job_status for background job state visible to the current session.
2. Use read-only SQLite queries only when a dedicated tool is missing, too coarse, or the task is diagnostic/audit work.
3. Never mutate app databases directly. Do not run UPDATE, DELETE, INSERT, DROP, CREATE, ALTER, VACUUM, REINDEX, or ATTACH.

Data root

All app-managed data lives under the Hope Agent data root:

• If HA_DATA_DIR is set: use it exactly.
• Otherwise: ~/.hope-agent.

Shell helper:

ROOT="${HA_DATA_DIR:-$HOME/.hope-agent}"

Use this helper instead of hard-coding ~/.hope-agent when running queries.

SQLite read-only patterns

Use the sqlite CLI with -readonly:

ROOT="${HA_DATA_DIR:-$HOME/.hope-agent}"
sqlite3 -readonly -cmd ".headers on" -cmd ".mode column" "$ROOT/sessions.db" \
  "SELECT id, title, agent_id, updated_at FROM sessions ORDER BY updated_at DESC LIMIT 10;"

Python fallback:

python3 - <<'PY'
import os, sqlite3
root = os.environ.get("HA_DATA_DIR") or os.path.expanduser("~/.hope-agent")
path = os.path.join(root, "sessions.db")
con = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
for row in con.execute("SELECT id, title, updated_at FROM sessions ORDER BY updated_at DESC LIMIT 10"):
    print(row)
PY

Main stores

Store	Path	Purpose
Sessions	$ROOT/sessions.db	Sessions, messages, chat context snapshots, projects, knowledge registry/bindings, channel mappings, subagent runs, tasks, learning events
Memory	$ROOT/memory.db	Long-term memories, memory FTS/vector data, Dreaming claims/evidence/profile data
Logs	$ROOT/logs.db	Structured app logs emitted by app_info! / app_warn! / app_error! / app_debug!
Background jobs	$ROOT/background_jobs.db	Unified background job cache for async tools and subagent/group projections
Cron	$ROOT/cron.db	Scheduled tasks managed by manage_cron
Wakeups	$ROOT/wakeups.db	Agent self-scheduled wakeups from schedule_wakeup
Recap	$ROOT/recap/recap.db	Cached recap/report facets and summaries
Knowledge index	$ROOT/knowledge/index.db	Rebuildable note/chunk/link/tag search cache; real notes are Markdown files
Canvas	$ROOT/canvas/canvas.db	Canvas projects and versions
Local model jobs	$ROOT/local_model_jobs.db	Ollama/local-model install, pull, preload jobs
Local LLM cache	$ROOT/local_llm_library_cache.db	Cached Ollama Library search/tag metadata