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)
|
||||
[](LICENSE)
|
||||
|
||||
Every past session, subagent, and workflow -- queryable by your agent.
|
||||
|
||||
**Humans should not browse session history. Agents should query it.**
|
||||
Every past session, subagent, and workflow -- queryable by your agent, browsable by you.
|
||||
|
||||
</div>
|
||||
|
||||
<br />
|
||||
|
||||
<div align="center">
|
||||
<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>
|
||||
## Two sides of the same index
|
||||
|
||||
## 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,
|
||||
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.
|
||||
**App side** — an Electron desktop app for humans to browse sessions, manage memories, view usage stats, and see weekly recap cards.
|
||||
|
||||
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
|
||||
|
||||
| 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
|
||||
## Skill: agent-first retrieval
|
||||
|
||||
```
|
||||
/obelisk 上次 auth bug 最后到底改了哪些文件，为什么这么改
|
||||
/obelisk 这个文件最近在哪些 sessions 里被反复修改
|
||||
/obelisk 找出最近失败的 tool calls，它们分别发生在哪些任务里
|
||||
/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
|
||||
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:
|
||||
|
||||
```
|
||||
/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
|
||||
### How it works
|
||||
|
||||
```
|
||||
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>
|
||||
↓
|
||||
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
|
||||
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()`.
|
||||
Core API: `search()`, `context()`, `sql()`, plus structured helpers (`sessions`, `memories`, `summaries`, `workflows`, `failures`, `fileHistory`, etc).
|
||||
|
||||
Memory is a synthesis cache, not a replacement for raw sessions. The agent can
|
||||
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.
|
||||
### Memory layer
|
||||
|
||||
**The core idea: don't make humans browse, tag, or organize sessions.**
|
||||
Don't invent a rigid query DSL either.
|
||||
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.
|
||||
|
||||
Agents can write code. So Obelisk gives them a small local query runtime over
|
||||
your past work.
|
||||
## App: A surface for human
|
||||
|
||||
The agent starts from a small core API, then uses structured shortcuts and
|
||||
references only when the question needs them:
|
||||
A companion desktop app for browsing what the skill indexes.
|
||||
|
||||
**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`
|
||||
- `context(uuid)` — full story around a message (parent chain, subagent/workflow metadata)
|
||||
- `sql(query, ...params)` — read-only SQL for structured queries
|
||||
- **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
|
||||
|
||||
**Structured shortcuts** — overview, session, memory, summary, subagent,
|
||||
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.
|
||||
macOS only. Download from [Releases](https://github.com/tommy0103/obelisk/releases).
|
||||
|
||||
## 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 |
|
||||
| **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 |
|
||||
| **Workflows** | `workflows/wf_<runId>.json` | Script, structured result, agent count |
|
||||
| **Workflow agents** | `subagents/workflows/wf_<runId>/` | Per-agent transcripts linked to workflow |
|
||||
| **Memories** | markdown files registered by the agent after user approval | Prior conclusions linked to source sessions/messages and optional anchors |
|
||||
| **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 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
|
||||
|
||||
```
|
||||
.claude/skills/obelisk/
|
||||
├── SKILL.md # Skill definition + simple API + examples
|
||||
├── scripts/
|
||||
│ ├── schema.sql # Executable SQLite schema
|
||||
│ └── runtime.mjs # Indexer + query runtime (zero deps)
|
||||
└── references/
|
||||
├── schema.md # Full table schema + advanced API reference
|
||||
├── query-patterns.md # Copyable retrieval recipes
|
||||
├── retrieval-semantics.md # Query design frame for retrieval semantics
|
||||
├── recap-patterns.md # Compatibility pointer to references/recap/overview.md
|
||||
├── recap-writing.md # Compatibility pointer to per-card recap writing docs
|
||||
├── recap/
|
||||
│ ├── overview.md
|
||||
│ ├── pattern1-cover.md
|
||||
│ ├── writing1-cover.md
|
||||
│ ├── pattern2-thinking.md
|
||||
│ ├── 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
|
||||
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
|
||||
|
||||
The index rebuilds incrementally — only new or modified JSONL files are re-parsed.
|
||||
When the optional app is running, it is the active indexer: it watches Claude
|
||||
project files, builds in a worker thread, writes `__app_heartbeat__` plus
|
||||
`__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.
|
||||
- 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)
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user