superdense

Files (10)

• QUERY_REFERENCE.md
• SKILL.md
• openai.yaml · agents/
• README.md · reward/
• collect.md · reward/
• compare.md · reward/
• curate.md · reward/
• finalize.md · reward/
• profile.md · reward/
• reconcile.md · reward/

SKILL.md (first lines)

# Superdense Stored Sessions

## Concepts

- **Session** — one stored agent run, identified by `<adapter>:<sessionId>` (e.g. `codex:abc-123`).
- **Project key** — normalized project identity used to group related workspaces. For Conductor paths, `/Users/x/conductor/workspaces/superdense/casablanca/packages/core` has project key `/Users/x/conductor/workspaces/superdense`; outside Conductor, project key equals `pwd`.
- **Session filter** — query filter named `session`; use it for agent, project, `pwd`, time, errors, tools, commands, event count, plan-mode fields, and sub-agent relationships.
- **Compactor** — on-demand view that re-reads the session log and prints to stdout. Only `salience` (gist) and `trace` (timeline).

## Sub-Agent Sessions

Modern coding agents (Claude Code, Codex, OpenCode) spawn sub-agent sessions to delegate work. Superdense indexes these as first-class sessions linked to their parent.

**Default behavior**: `session list`, `--q`, saved queries, and ad-hoc queries return **root sessions only**. Sub-agents are hidden by default.

**How to discover children of a session:**

```bash
# session show returns direct-child sub-agent metadata
superdense session show <session-id>

# list direct children (id + relation by default; --full for metadata)
superdense session children <session-id>
superdense session children <session-id> --full

# recursive tree (default depth=1; use --depth N for deeper)
superdense session tree <session-id>
superdense session tree <session-id> --depth 3
```

**How to include sub-agents in search:**

```bash
# session list with --include-subagents
superdense session list --include-subagents

# query DSL: isSubagent param (default false = root-only)
superdense query --query '{"filters":{"filter":{"name":"session","params":{"isSubagent":true}}}}'

# find children of a specific parent via parent: param
superdense query --query '{"filters":{"filter":{"name":"session","params":{"isSubagent":true,"parent":"claude-code:<parent-id>"}}}}'

# find level-1 sub-agents that spawned their own sub-agents
superdense query --query '{"filters":{"filter":{"name":"session","params":{"isSubagent":true,"hasSubagents":true,"subagentDepth":{"op":"=","value":1}}}}}'

# find every indexed session in one root/sub-agent tree
superdense query --query '{"filters":{"filter":{"name":"session","params":{"rootSession":"codex:<root-id>"}}}}'
```

**Direct access works unchanged** — `session show <child-id>`, `session path <child-id>`, and `compactor run <name> <child-id>` all work on sub-agent sessions directly.

**System enrichment:** every indexed session, including sub-agent sessions, gets an always-on `subagent_summary` enrichment. It contains direct-child fields (`hasSubagents`, `subagentCount`, `subagentIds`) plus recursive/tree fields (`descendantSubagentCount`, `subagentDepth`, `rootSessionId`, `ancestorSessionIds`). Inspect it with:

```bash
superdense session enrichments <session-id> --name subagent_summary
```

## Workflow

Use the CLI as a staged inspection pipeline: candidate discovery → metadata triage → compact only what's relevant.

**Reward layer.** To see the reward-layer punch list and next stage, start with:

```bash
superdense reward status
```

Use `superdense reward status --project <id>` to focus the project-sensitive stages. The pipeline is `profile -> curate -> finalize -> reconcile -> collect -> compare`. Run status first, then read only the reference file for the stage it selects:

| Stage       | Reference             |
| ----------- | --------------------- |
| `profile`   | `reward/profile.md`   |
| `curate`    | `reward/curate.md`    |
| `finalize`  | `reward/finalize.md`  |
| `reconcile` | `reward/reconcile.md` |
| `collect`   | `reward/collect.md`   |
| `compare`   | `reward/compare.md`   |

Shared reward-layer rules and helper references for artifact types and connector names live in `reward/README.md`.

**Precondition.** Refresh the index only when the user asks about recent/latest work, new sessions may have appeared, or results look stale:

```bash
superdense index
```

1. Find candidate sessions. Root sessions are searched by default; use `session children`/`session tree` or `isSubagent: true` to follow up on delegated work after picking a root candidate. Pick the discovery path that matches the search:
   - `superdense session list --q "text"` — substring search across **first prompt, summary, and working directory** only (case-insensitive `LIKE`). Use for quick keyword/topic/pwd hits.

     ```bash
     superdense session list --q "search text" --limit 20
     ```

   - `superdense query` — use whenever the search needs a field `--q` doesn't cover: agent, project, time bounds, `hasErrors`, `toolUsed`, `cliUsed`, `eventCount`, plan-mode filters, transcript filters, or any `and`/`or`/`not` combinator. Ad hoc, not saved. Inspect the live schema first for plan-mode or project-scoped searches:

     ```bash
     superdense filter show session
     superdense query --query '<query-json>' --limit 20
     superdense query --query @query.json --limit 20
     ```

   - `superdense saved-query` — use only when the user names an existing reusable cohort or asks to persist one:

     ```bash
     superdense saved-query list
     superdense saved-query run <query-id> --limit 20
     superdense saved-query save --name "name" --query '<query-json>'
     superdense saved-query save --name "name" --query @query.json
     ```

2. Triage candidates before compacting. Prefer session metadata to raw logs; inspect session details only when metadata is not enough:

   ```bash
   superdense session show <session-id>
   superdense session enrichments <session-id>
   ```

3. Compact only the sessions that look relevant:

From Nimrobo/superdense, Apache-2.0.

More from Nimrobo/superdense