Local-first search and analysis for AI coding-agent session history.
Sessions will normalize Cursor, Codex, and future agent histories into one faithful local index. Humans and agents can then recover context, inspect decisions, audit drift and verification, and discover recurring work without uploading transcripts.
Status: pre-alpha. The repository foundation, canonical contracts, read-only state inspection, and protected SQLite lifecycle are implemented. Indexing, search, provider adapters, and the packaged Agent Skill are planned and not yet available. The npm package has not been released.
- One provider-neutral query model instead of provider-specific workflows.
- Explicit, read-only indexing with no telemetry or cloud dependency.
- Provenance that distinguishes human, injected, delegated, copied, model, tool, and system content.
- Deduplicated evidence counts that do not mistake forks or copied prompts for independent recurrence.
- Human output for exploration and versioned JSON/JSONL for scripts and agents.
Prerequisites: Node.js 24.15 or newer and pnpm 11.10 through Corepack.
git clone https://github.com/ferueda/sessions.git
cd sessions
corepack enable
pnpm install --frozen-lockfile
pnpm build
node dist/bin/sessions.js doctorCurrent commands:
node dist/bin/sessions.js --help
node dist/bin/sessions.js --version
node dist/bin/sessions.js doctor
node dist/bin/sessions.js doctor --format json
node dist/bin/sessions.js paths
node dist/bin/sessions.js paths --format jsondoctor checks the Node runtime, in-memory SQLite FTS5 capabilities, and the existing Sessions index state. paths reports the Sessions-owned index directory, database, and SQLite sidecar paths. Neither command creates or migrates state, inspects providers, or accesses the network. An uninitialized index is a healthy fresh-install state.
The internal writer lifecycle already provides protected SQLite initialization and migrations, but no public command opens it yet. The current database migration contains metadata only—there are no canonical session tables or provider adapters.
sessions index [--source cursor|codex]
sessions list [filters]
sessions search <text> [filters]
sessions show <source-instance:id> [--entry N --context N]
sessions export <source-instance:id> --format md|json|jsonl
sessions index clear
The public delivery target is npm install --global @ferueda/sessions or npx @ferueda/sessions, after package ownership, cross-platform parity, and trusted publishing are configured.
Provider histories are inputs, never mutation targets. Indexing will be explicit, local, and network-free. The planned canonical index is rebuildable derived data with user-controlled clearing and restrictive local permissions. See the privacy contract for promises and limitations.
- Project intent
- Accepted architecture memo
- V1 implementation roadmap
- CLI contract
- Architecture decisions
- Active implementation plans
Start with CONTRIBUTING.md and the contributor index. pnpm check is the repository definition of done.
MIT