tommy0103
c50706daef
Restructure the README around the dual nature of Obelisk: agent-first skill for querying session history, plus Electron desktop app for browsing sessions, memories, activity, and recap cards. Trim verbose implementation details and add app screenshot.
4.7 KiB
Every past session, subagent, and workflow -- queryable by your agent, browsable by you.
Two sides of the same index
Obelisk has two sides that share one SQLite index:
Skill side — a Claude Code skill that lets the agent search and query its own session history. The agent writes JS queries, runs them locally, answers in plain language.
App side — an Electron desktop app for humans to browse sessions, manage memories, view usage stats, and see weekly recap cards.
Both read from the same ~/.claude/obelisk.sqlite database. The skill indexes; the app watches and renders.
Skill: agent-first retrieval
/obelisk 上次 auth bug 最后到底改了哪些文件，为什么这么改
/obelisk 这个文件最近在哪些 sessions 里被反复修改
/obelisk 找出最近失败的 tool calls，它们分别发生在哪些任务里
/obelisk 那个 review workflow 的 subagents 各自结论是什么
/obelisk recap this week
Install
npx skills add tommy0103/obelisk
Or manually: copy the skill into .claude/skills/obelisk/.
How it works
You ask a question
↓
Agent writes a JS query against the SQLite index
↓
Runs it via node runtime.mjs --query <script>
↓
Reads the JSON result, answers in natural language
Core API: search(), context(), sql(), plus structured helpers (sessions, memories, summaries, workflows, failures, fileHistory, etc).
Memory layer
When a retrieval produces a conclusion worth keeping, the agent proposes a markdown memory file. After user approval, it registers the file with runtime.mjs --remember. Memories are recalled via memories() in future sessions — a synthesis cache, not a replacement for raw evidence.
App: A surface for human
A companion desktop app for browsing what the skill indexes.
- Sessions — browse all sessions with search, project filtering, readable tool calls (diffs, terminal output, file viewers)
- Memory — list and detail views for registered memory files
- Activity — GitHub-style heatmap, weekly/cumulative token charts
- Recap — shareable weekly/monthly recap cards with archetype theming
- Settings — data source configuration, auto-refresh, rebuild index
macOS only. Download from Releases.
What gets indexed
| Layer | Source | What's captured |
|---|---|---|
| Sessions | <project>/<sessionId>.jsonl |
Title, project, timestamps, git branch |
| Messages | user + assistant turns | Full text, model, token usage, parent chain |
| Tool calls | every tool invocation | Tool name, input, file paths |
| Subagents | subagents/agent-<id>.jsonl |
Agent type, description, full conversation |
| Workflows | workflows/wf_<runId>.json |
Script, result, agent count |
| Workflow agents | subagents/workflows/wf_<runId>/ |
Per-agent transcripts |
| Memories | registered markdown files | Conclusions linked to source sessions |
Full-text search via FTS5 covers all layers.
Structure
scripts/ # Skill runtime (zero npm deps, Node 22 built-in sqlite)
├── schema.sql # Executable SQLite schema
├── runtime.mjs # Indexer + query runtime
├── db.mjs # Schema init, migrations
├── indexer.mjs # JSONL discovery + incremental indexing
└── query.mjs # Query API (search, sessions, memories, etc)
references/ # Agent-readable docs (progressive disclosure)
├── schema.md
├── query-patterns.md
├── retrieval-semantics.md
├── recap-patterns.md
├── recap/ # Per-card pattern + writing references
└── pitfalls.md
SKILL.md # Skill definition + API + retrieval strategy
Implementation Notes
- Index rebuilds incrementally — only new/modified JSONL files are re-parsed
- Skill side uses Node 22 built-in
node:sqlite; zero npm dependencies ~/.obelisk/recap/watched for new recap JSON files (agent writes, app renders)
License
MIT @tommy0103