docs: rewrite README to cover both skill and app sides
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.
This commit is contained in:
tommy0103
Binary file not shown.
|
After Width: | Height: | Size: 1.7 MiB |
@@ -9,75 +9,41 @@
|
|||||||
[](https://github.com/tommy0103/obelisk/releases)
|
[](https://github.com/tommy0103/obelisk/releases)
|
||||||
[](LICENSE)
|
[](LICENSE)
|
||||||
|
|
||||||
Every past session, subagent, and workflow -- queryable by your agent.
|
Every past session, subagent, and workflow -- queryable by your agent, browsable by you.
|
||||||
|
|
||||||
**Humans should not browse session history. Agents should query it.**
|
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
<br />
|
<br />
|
||||||
|
|
||||||
<div align="center">
|
## Two sides of the same index
|
||||||
<img src=".github/assets/demo.png" alt="Obelisk in action" width="540">
|
|
||||||
<br />
|
|
||||||
<p>Ask in plain language. The agent writes the query, runs it, answers.</p>
|
|
||||||
</div>
|
|
||||||
|
|
||||||
## Not a session browser
|
Obelisk has two sides that share one SQLite index:
|
||||||
|
|
||||||
Most history tools help humans find old chats.
|
**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.
|
||||||
|
|
||||||
Obelisk is built for agents. It exposes past work as structured data: sessions,
|
**App side** — an Electron desktop app for humans to browse sessions, manage memories, view usage stats, and see weekly recap cards.
|
||||||
messages, tool calls, subagents, workflows, file history, failures, parent
|
|
||||||
chains, and human-approved markdown memories. The agent writes the query, runs
|
|
||||||
it locally, and answers in plain language.
|
|
||||||
|
|
||||||
You don't manage history. You ask questions about past work.
|
Both read from the same `~/.claude/obelisk.sqlite` database. The skill indexes; the app watches and renders.
|
||||||
|
|
||||||
## Why Obelisk
|
## Skill: agent-first retrieval
|
||||||
|
|
||||||
| Session library | Obelisk |
|
|
||||||
|---|---|
|
|
||||||
| Find an old chat | Answer a question about past work |
|
|
||||||
| Human browses snippets | Agent writes and runs a query |
|
|
||||||
| Search result list | Structured context and reasoning |
|
|
||||||
| Sessions as documents | Sessions as queryable memory |
|
|
||||||
| Good for recall | Good for investigation |
|
|
||||||
|
|
||||||
## What you can ask
|
|
||||||
|
|
||||||
```
|
```
|
||||||
/obelisk 上次 auth bug 最后到底改了哪些文件，为什么这么改
|
/obelisk 上次 auth bug 最后到底改了哪些文件，为什么这么改
|
||||||
/obelisk 这个文件最近在哪些 sessions 里被反复修改
|
/obelisk 这个文件最近在哪些 sessions 里被反复修改
|
||||||
/obelisk 找出最近失败的 tool calls，它们分别发生在哪些任务里
|
/obelisk 找出最近失败的 tool calls，它们分别发生在哪些任务里
|
||||||
/obelisk 那个 review workflow 的 subagents 各自结论是什么
|
/obelisk 那个 review workflow 的 subagents 各自结论是什么
|
||||||
/obelisk 我之前有没有试过这个方案，结果为什么放弃了
|
/obelisk recap this week
|
||||||
```
|
```
|
||||||
|
|
||||||
Anything Claude Code has done before -- sessions, tool calls, subagents, workflows -- becomes structured, queryable memory. Ask in your own words.
|
### Install
|
||||||
|
|
||||||
## Install
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npx skills add tommy0103/obelisk
|
npx skills add tommy0103/obelisk
|
||||||
```
|
```
|
||||||
|
|
||||||
Or manually: copy `obelisk/` into your project's `.claude/skills/`.
|
Or manually: copy the skill into `.claude/skills/obelisk/`.
|
||||||
|
|
||||||
Then in any Claude Code session:
|
### How it works
|
||||||
|
|
||||||
```
|
|
||||||
/obelisk <your question>
|
|
||||||
```
|
|
||||||
|
|
||||||
First run builds the index (~5 seconds for 100 sessions). After that it rebuilds incrementally.
|
|
||||||
|
|
||||||
### Requires
|
|
||||||
|
|
||||||
- Node.js 22+ (uses built-in node:sqlite with FTS5)
|
|
||||||
- Claude Code with skills support.
|
|
||||||
|
|
||||||
## How it works
|
|
||||||
|
|
||||||
```
|
```
|
||||||
You ask a question
|
You ask a question
|
||||||
@@ -86,63 +52,30 @@ Agent writes a JS query against the SQLite index
|
|||||||
↓
|
↓
|
||||||
Runs it via node runtime.mjs --query <script>
|
Runs it via node runtime.mjs --query <script>
|
||||||
↓
|
↓
|
||||||
Reads the JSON result, answers you in natural language
|
Reads the JSON result, answers in natural language
|
||||||
```
|
```
|
||||||
|
|
||||||
When a retrieval produces a memory worth keeping, the agent proposes a markdown
|
Core API: `search()`, `context()`, `sql()`, plus structured helpers (`sessions`, `memories`, `summaries`, `workflows`, `failures`, `fileHistory`, etc).
|
||||||
memory file. After user approval, it registers that file with the narrow
|
|
||||||
`runtime.mjs --attune <script>` runtime, which exposes only memory mutation
|
|
||||||
helpers such as `remember()` and `forget()`.
|
|
||||||
|
|
||||||
Memory is a synthesis cache, not a replacement for raw sessions. The agent can
|
### Memory layer
|
||||||
decide whether to use, ignore, or verify a memory during an answer. Persistent
|
|
||||||
changes still require human approval, but explicit corrections count: if you say
|
|
||||||
a memory is wrong, outdated, or should be replaced, the agent can archive or
|
|
||||||
update the exact matching record without a second confirmation.
|
|
||||||
|
|
||||||
**The core idea: don't make humans browse, tag, or organize sessions.**
|
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.
|
||||||
Don't invent a rigid query DSL either.
|
|
||||||
|
|
||||||
Agents can write code. So Obelisk gives them a small local query runtime over
|
## App: A surface for human
|
||||||
your past work.
|
|
||||||
|
|
||||||
The agent starts from a small core API, then uses structured shortcuts and
|
A companion desktop app for browsing what the skill indexes.
|
||||||
references only when the question needs them:
|
|
||||||
|
|
||||||
**Core primitives** — the main CodeAct surface:
|
<div align="center">
|
||||||
|
<img src=".github/assets/app-screenshot.png" alt="Obelisk App" width="720">
|
||||||
|
</div>
|
||||||
|
|
||||||
- `search(text)` — FTS5 full-text search, returns matches with surrounding context plus message `content_type` and `is_meta`
|
- **Sessions** — browse all sessions with search, project filtering, readable tool calls (diffs, terminal output, file viewers)
|
||||||
- `context(uuid)` — full story around a message (parent chain, subagent/workflow metadata)
|
- **Memory** — list and detail views for registered memory files
|
||||||
- `sql(query, ...params)` — read-only SQL for structured queries
|
- **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
|
||||||
|
|
||||||
**Structured shortcuts** — overview, session, memory, summary, subagent,
|
macOS only. Download from [Releases](https://github.com/tommy0103/obelisk/releases).
|
||||||
workflow, file-history, failure, raw-window, and parent-chain helpers over the
|
|
||||||
same SQLite data.
|
|
||||||
|
|
||||||
**References** — agent reads on demand when the task needs deeper structure:
|
|
||||||
|
|
||||||
- `references/schema.md` — full SQLite schema and API reference
|
|
||||||
- `references/query-patterns.md` — copyable CodeAct recipes for common retrieval tasks
|
|
||||||
- `references/retrieval-semantics.md` — query design frame for scoped and synthesis retrieval
|
|
||||||
- `references/recap/overview.md` — optional `/obelisk recap` card-by-card entrypoint
|
|
||||||
- `references/recap/pattern1-cover.md` and `references/recap/writing1-cover.md`
|
|
||||||
- `references/recap/pattern2-thinking.md` and `references/recap/writing2-thinking.md`
|
|
||||||
- `references/recap/pattern3-vibe.md` and `references/recap/writing3-vibe.md`
|
|
||||||
- `references/recap/pattern4-workflow.md` and `references/recap/writing4-workflow.md`
|
|
||||||
- `references/recap/pattern5-closing.md` and `references/recap/writing5-closing.md`
|
|
||||||
- `references/pitfalls.md` — scope, FTS, ordering, compact/raw, and field-name traps
|
|
||||||
|
|
||||||
The executable SQLite schema lives in `scripts/schema.sql`; `references/schema.md`
|
|
||||||
is the human/agent explanation of that contract.
|
|
||||||
|
|
||||||
The design is progressive disclosure with guardrails: the main skill keeps the
|
|
||||||
core contract and high-risk pitfalls visible, while longer recipes and the full
|
|
||||||
schema stay out of the first prompt until the agent needs them.
|
|
||||||
The optional recap references are only for the explicit `/obelisk recap` intent;
|
|
||||||
they are not part of the ordinary retrieval path. `references/recap/overview.md`
|
|
||||||
drives a card-by-card loop: read one card's retrieval pattern, gather that
|
|
||||||
card's evidence, read its writing reference, update the JSON, then continue.
|
|
||||||
This keeps schema, taste, and query planning from competing in one large prompt.
|
|
||||||
|
|
||||||
## What gets indexed
|
## What gets indexed
|
||||||
|
|
||||||
@@ -150,54 +83,40 @@ This keeps schema, taste, and query planning from competing in one large prompt.
|
|||||||
|-------|--------|----------------|
|
|-------|--------|----------------|
|
||||||
| **Sessions** | `<project>/<sessionId>.jsonl` | Title, project, timestamps, git branch |
|
| **Sessions** | `<project>/<sessionId>.jsonl` | Title, project, timestamps, git branch |
|
||||||
| **Messages** | user + assistant turns | Full text, model, token usage, parent chain |
|
| **Messages** | user + assistant turns | Full text, model, token usage, parent chain |
|
||||||
| **Tool calls** | every tool invocation | Tool name, input, file paths touched |
|
| **Tool calls** | every tool invocation | Tool name, input, file paths |
|
||||||
| **Subagents** | `subagents/agent-<id>.jsonl` | Agent type, description, full conversation |
|
| **Subagents** | `subagents/agent-<id>.jsonl` | Agent type, description, full conversation |
|
||||||
| **Workflows** | `workflows/wf_<runId>.json` | Script, structured result, agent count |
|
| **Workflows** | `workflows/wf_<runId>.json` | Script, result, agent count |
|
||||||
| **Workflow agents** | `subagents/workflows/wf_<runId>/` | Per-agent transcripts linked to workflow |
|
| **Workflow agents** | `subagents/workflows/wf_<runId>/` | Per-agent transcripts |
|
||||||
| **Memories** | markdown files registered by the agent after user approval | Prior conclusions linked to source sessions/messages and optional anchors |
|
| **Memories** | registered markdown files | Conclusions linked to source sessions |
|
||||||
|
|
||||||
Full-text search via FTS5 covers message text across every session layer and ranked memory recall over registered memory summaries, while the SQLite tables preserve the structure agents need for investigation.
|
Full-text search via FTS5 covers all layers.
|
||||||
|
|
||||||
## Structure
|
## Structure
|
||||||
|
|
||||||
```
|
```
|
||||||
.claude/skills/obelisk/
|
scripts/ # Skill runtime (zero npm deps, Node 22 built-in sqlite)
|
||||||
├── SKILL.md # Skill definition + simple API + examples
|
├── schema.sql # Executable SQLite schema
|
||||||
├── scripts/
|
├── runtime.mjs # Indexer + query runtime
|
||||||
│ ├── schema.sql # Executable SQLite schema
|
├── db.mjs # Schema init, migrations
|
||||||
│ └── runtime.mjs # Indexer + query runtime (zero deps)
|
├── indexer.mjs # JSONL discovery + incremental indexing
|
||||||
└── references/
|
└── query.mjs # Query API (search, sessions, memories, etc)
|
||||||
├── schema.md # Full table schema + advanced API reference
|
|
||||||
├── query-patterns.md # Copyable retrieval recipes
|
references/ # Agent-readable docs (progressive disclosure)
|
||||||
├── retrieval-semantics.md # Query design frame for retrieval semantics
|
├── schema.md
|
||||||
├── recap-patterns.md # Compatibility pointer to references/recap/overview.md
|
├── query-patterns.md
|
||||||
├── recap-writing.md # Compatibility pointer to per-card recap writing docs
|
├── retrieval-semantics.md
|
||||||
├── recap/
|
├── recap-patterns.md
|
||||||
│ ├── overview.md
|
├── recap/ # Per-card pattern + writing references
|
||||||
│ ├── pattern1-cover.md
|
└── pitfalls.md
|
||||||
│ ├── writing1-cover.md
|
|
||||||
│ ├── pattern2-thinking.md
|
SKILL.md # Skill definition + API + retrieval strategy
|
||||||
│ ├── writing2-thinking.md
|
|
||||||
│ ├── pattern3-vibe.md
|
|
||||||
│ ├── writing3-vibe.md
|
|
||||||
│ ├── pattern4-workflow.md
|
|
||||||
│ ├── writing4-workflow.md
|
|
||||||
│ ├── pattern5-closing.md
|
|
||||||
│ └── writing5-closing.md
|
|
||||||
└── pitfalls.md # Scope, FTS, ordering, and compactness traps
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Implementation Notes
|
## Implementation Notes
|
||||||
|
|
||||||
The index rebuilds incrementally — only new or modified JSONL files are re-parsed.
|
- Index rebuilds incrementally — only new/modified JSONL files are re-parsed
|
||||||
When the optional app is running, it is the active indexer: it watches Claude
|
- Skill side uses Node 22 built-in `node:sqlite`; zero npm dependencies
|
||||||
project files, builds in a worker thread, writes `__app_heartbeat__` plus
|
- `~/.obelisk/recap/` watched for new recap JSON files (agent writes, app renders)
|
||||||
`__app_last_successful_build__` into `index_state`, and the skill-side lazy
|
|
||||||
build skips work only while both markers are fresh.
|
|
||||||
|
|
||||||
Zero npm dependencies. Uses Node 22's built-in node:sqlite with FTS5. The entire runtime is ~400 lines.
|
|
||||||
|
|
||||||
20K lines of scattered JSONL → something the agent can search() and sql() against in milliseconds.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user