feat: add opt-in import of pre-install user prompts from one agent host

[knqiufan]

Feature description

PowerContext only captures user prompts after its plugin is installed. Older prompts from Codex, Claude Code, or DeepSeek Harness stay in that host's local session files. A project that already has months of history has to start from zero.

Add an explicit, default-off CLI that copies only user prompts from one host into the existing Source pipeline:

powercontext import-sessions --host codex
powercontext import-sessions --host claude-code
powercontext import-sessions --host dsh

--host is required. This does not change Memory contracts, does not read full transcripts in v1, and does not run from a prompt hook.

This is not "inject history into the agent". It is a one-time or incremental backfill into PowerContext, so later prepare can use knowledge the user already wrote.

Problem and proposed solution

Why this issue exists

The official loop is:

user prompt → Source → optional extract → Memory → later prepare

That loop starts only after setup and a running Server. Live hooks capture the current user prompt as POST /v1/sources/content. They never read host session files created before install. Scheduled extract cannot invent Sources that were never captured.

So the first day of PowerContext looks empty even when the user has already told Codex or DSH the project's decisions, constraints, and facts.

Gap

Today	Missing
Hook captures the current user prompt	No reader for host session files created before install
POST /v1/sources/content and flush already exist	No official command that feeds old prompts into those APIs
Scope is per project and shared across hosts	Old prompts are stranded in host-specific files

Value

• Users can reuse decisions, constraints, and facts already stated to an agent, instead of re-teaching PowerContext from the install day.
• Later recall still uses the current prepare path and the same project scope.
• Backfill stays explicit and host-scoped, so a Codex-only user does not have DSH or Claude files scanned by default.

Proposed user contract

Keep server run and live hooks unchanged. Add a client-side importer.

--host should stay required:

• Session paths and formats differ by host.
• Live capture already uses host-specific source_id and origin (codex-user-prompt:, claude-code-user-prompt:, dsh-user-prompt:).
• Users often want only one host. Scanning every host by default would be surprising.

Suggested flow:

import-sessions --host <codex|claude-code|dsh>
  → host adapter reads local user prompts
  → derive the same scope as the plugin (cwd / git remote / override)
  → POST /v1/sources/content
  → optional flush

Rules:

• Default: user prompts only. Do not import assistant replies or full transcripts in v1.
• Reuse existing HTTP APIs. Do not add a second Memory write path.
• Use a stable backfill source_id, for example codex-history:<file>:<index>, with metadata.origin matching the host. Do not guess live hook hashes.
• Skip sessions with no workspace. Do not dump every chat into one global scope.
• Filter secrets. Skip or fail visibly if the host format cannot be parsed.
• Server must already be running. This command does not start it.
• Optional --flush, --dry-run, and --scope-id. Flush still needs a generation model; importing Sources alone does not create Memory.

Implementation belongs in CLI / host adapters, not in src/powercontext/builtin. Host file formats are not a Core contract.

Acceptance criteria

• A clean install does not import history. setup does not run this command.
• --host is required. codex reads only Codex files; dsh reads only DSH files; claude-code reads only Claude Code files.
• Imported items are ordinary Content Sources on the same scope the plugin would use for that workspace.
• Rerunning the command does not create duplicate Sources for the same host prompt.
• Sessions without a workspace are skipped, not assigned a guessed global scope.
• v1 does not persist assistant replies or full transcripts.
• Live hooks, prepare, and fail-open behavior stay unchanged.
• Without a generation model or --flush, the command may create Sources only and must not claim they are already Memory.

Out of scope

• Changing prepare to search raw Source
• Watching ~/.codex or other host files on every prompt
• Enabling import during setup
• Promising that every old prompt becomes a recallable Memory card. The default coding extractor drops transcripts.

If maintainers consider this a new official integration boundary, I can follow with a docs-only RFC before implementation.

Alternatives considered

1. One command that imports every host. Reject as the default. Formats, privacy, and scope differ. --host should stay explicit. A later --host all can wait until single-host adapters exist.
2. Ask users to paste old chats into /v1/sources/content. Works for a few prompts, not for months of history.
3. Read host files from the live hook. Reject. Hooks are fail-open and time-budgeted. Backfill is batch work.
4. Import assistant replies or full transcripts. Conflicts with the v1 "user prompt only" contract and with extractors that drop transcripts. Leave it out of v1.

Additional context

Live capture already writes host-specific Sources:

• Codex: codex-user-prompt:<sha256>, origin=codex
• Claude Code: claude-code-user-prompt:<sha256>, origin=claude-code
• DSH: dsh-user-prompt:<sha256>, origin=dsh

RFC 0014 does not host sessions or watch files; those belong to Source integration. This issue proposes that opt-in adapter, not a Core protocol change.

Related but not the same:

• research: define the Source integration shape #1240 tracks the broader Source integration shape
• Tracking Issue: Agent Integrations for PowerContext #1213 tracks Agent integrations, not pre-install backfill
• RFC 0014 non-goals: do not host sessions or full transcripts

Searched open and closed issues for import-sessions, transcript, history import, and pre-install prompt backfill. No existing tracker found as of 2026-08-21.

Are you willing to contribute to this feature?

• Yes, I am willing to contribute code, docs, or design feedback.