Skip to content

feat: add read-only JSON memory CLI for SSH/cron automation#124

Merged
eriksjaastad merged 2 commits into
mainfrom
feat/pt-memory-readonly-automation
May 5, 2026
Merged

feat: add read-only JSON memory CLI for SSH/cron automation#124
eriksjaastad merged 2 commits into
mainfrom
feat/pt-memory-readonly-automation

Conversation

@manager-identity
Copy link
Copy Markdown
Contributor

Summary

  • Adds a sandbox-friendly read-only memory surface for LoopLens/Hermes (SSH + cron) that opens ai-memory/brain.db directly in SQLite read-only mode (PRAGMA query_only = ON) without shelling through Doppler.
  • New commands: pt memory search --query ... --json, pt memory recent --json, pt memory stats --json, pt memory export --format ndjson, pt config show --effective --json, pt doctor --json, pt --version.
  • Existing human pt memory search "query" behavior is preserved; JSON/filter mode uses the new direct read-only path.

Design notes

  • Stable schema: every JSON response carries a schema_version string (pt.memory.v1, pt.config.v1, pt.doctor.v1).
  • Distinct exit codes for automation: 2 validation, 3 backend unavailable, 4 query failure, 5 auth.
  • Asymmetric error routing: single-object commands (search/recent/stats) emit error JSON to stdout (consumer branches on ok); memory export emits errors to stderr so its NDJSON stdout stream stays exclusively a data channel. _emit_json_error is annotated NoReturn to make the control flow legible to type checkers.
  • Migration warning gating is unchanged from main: _warn_unapplied_migrations writes to stderr only, banner is TTY-gated, and PT_SUPPRESS_MIGRATION_WARNING=1 is the documented opt-out for cron/SSH.

Test plan

  • PT_SKIP_DOPPLER=1 ./pt doctor --json returns a valid pt.doctor.v1 payload with all checks ok on a healthy box.
  • ./pt memory recent --since 7d --limit 5 --json returns a pt.memory.v1 envelope with stable pagination fields.
  • ./pt memory export --project project-tracker --format ndjson prints one JSON object per line on stdout, nothing on stderr; exit code 0.
  • PT_MEMORY_DB_PATH=/tmp/missing.db ./pt memory export prints nothing on stdout, a structured backend_unavailable JSON object on stderr, exit code 3.
  • ./pt memory search "MCP" --top 3 (no --json, no filters) still hits the existing brain.py path and behaves identically to main.
  • ./pt info list --json (existing command) still emits the same output as main — confirms the migration-warning gate change did not regress unrelated --json consumers.
  • pytest tests/test_memory_cli.py — 8/8 green.

Related

  • Closes #6059

manager-identity Bot added 2 commits May 5, 2026 16:58
Adds sandbox-friendly read-only commands that open ai-memory/brain.db
in SQLite read-only mode (PRAGMA query_only=ON) without shelling out
through Doppler:

  pt memory search --query ... --json
  pt memory recent --json
  pt memory stats --json
  pt memory export --format ndjson
  pt config show --effective --json
  pt doctor --json
  pt --version

Existing human `pt memory search "query"` behavior is preserved;
JSON/filter mode uses the direct read-only query path.
- Drop the `--json in sys.argv` short-circuit in cli(): it was too broad
  (silently suppressed migration warnings for every existing --json
  consumer like `pt info list --json`). The migration warning already
  goes to stderr, the banner is already TTY-gated, and
  PT_SUPPRESS_MIGRATION_WARNING is the documented opt-out for cron/SSH.
- Annotate _emit_json_error as NoReturn so type checkers know variables
  in the surrounding scope are unreachable on the error path. No
  runtime change — SystemExit propagation was already correct.
- Route memory_export errors to stderr via a new err= kwarg on
  _emit_json_error. NDJSON streams must keep stdout exclusively for
  data lines; an error JSON object mid-stream would corrupt downstream
  parsers. Other JSON commands keep stdout-on-error since they emit a
  single object the consumer can branch on.
- Add three memory_export tests: ndjson shape, --project filter,
  error-routing-to-stderr.
@manager-identity manager-identity Bot added the feature New feature label May 5, 2026
@eriksjaastad eriksjaastad merged commit 36362b4 into main May 5, 2026
2 checks passed
@eriksjaastad eriksjaastad deleted the feat/pt-memory-readonly-automation branch May 5, 2026 21:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

feature New feature

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant