# Self Awareness

Claude Science's own session database schema and SDK surface for introspection via...

- Repository: https://github.com/HughYau/AcademicForge (2620 stars)
- Category: Data and ML
- License: Apache-2.0
- Last updated: 2026-08-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add HughYau/AcademicForge --skill self-awareness -g -a claude-code -y`
Codex: `npx skills add HughYau/AcademicForge --skill self-awareness -g -a codex -y`
Cursor: `npx skills add HughYau/AcademicForge --skill self-awareness -g -a cursor -y`
Gemini CLI: `npx skills add HughYau/AcademicForge --skill self-awareness -g -a gemini-cli -y`

## Description

Claude Science's own session database schema and SDK surface for introspection via host.query(). Load this when you need to query your own conversation history, token usage, cost accounting, execution log, or artifact metadata beyond what host.frames()/host.artifacts() provide, e.g. "how many tokens has this session used", "what was my last tool call", "list every file I've written", "where are messages stored", "what tables can I query", "inspect frames.context_data", or any time you're about to PRAGMA-probe the Claude Science metadata DB to discover its schema.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Self-awareness, Claude Science's own database and SDK

`host.query(sql, params=[], limit=None, df=False)` runs read-only SQLite
against Claude Science's own metadata DB. It is only available via the **`repl`
tool** (not `python`/`r`). Results are automatically scoped to the current
project, so `SELECT * FROM frames` returns only frames in this project. The
`repl` tool is stdlib-only, `df=True` returns the raw dict there (use
`json.dump(..., open("handoff/q.json","w"))` and load in a `python` cell if
you want pandas).

## Dialect and limits

- **SQLite.** Epoch-milliseconds for all timestamps
  (`created_at > strftime('%s','now','-1 day')*1000`). Booleans are `0`/`1`.
  JSON columns are TEXT, use `json_extract(col, '$.key')`. Recursive CTEs OK.
- `SELECT` / `WITH` / `PRAGMA` / `EXPLAIN` only; one statement per call;
  `?` placeholders with `params=[...]`.
- **Scoping.** Most tables are transparently filtered to the current
  project (and `memories` to the current user) via CTEs that shadow the
  real tables, `session_claims`, `verification_checks`, and `poller_lease`
  are unscoped. You therefore **cannot** use `main.table` / `temp.table`, schema-qualified names are rejected.
- **Caps.** Default 200 rows (max `limit=1000`); cells >2000 chars are
  clipped in place with a `…[+N chars]` marker; total serialized output
  capped at ~100k chars (`truncated=True`, `truncation_reason="total_size_cap"`, narrow your columns). 5-second timeout.
- Schema introspection: `host.query("PRAGMA table_info(frames)")` or
  `host.query("SELECT name, sql FROM sqlite_master WHERE type='table'")`.

## Queryable tables

### Session / conversation

The rest: https://github.com/HughYau/AcademicForge/blob/HEAD/skills/claude-science/self-awareness/SKILL.md