feat: add Cursor agent transcript JSONL normalizer

[marerem]

Summary

Adds _try_cursor_jsonl() parser to normalize.py for importing Cursor IDE agent transcript sessions, addressing the Cursor portion of #59.

• Format: JSONL files at ~/.cursor/projects/<project>/agent-transcripts/<uuid>/<uuid>.jsonl
• Line schema: {"role": "user"|"assistant", "message": {"content": [{"type": "text", "text": "..."}]}}
• Detection: Requires top-level role key (not type) and list-typed content blocks, preventing false positives against Claude Code JSONL and Codex JSONL

Why JSONL only (no SQLite)?

Cursor's state.vscdb SQLite database (~/Library/Application Support/Cursor/User/workspaceStorage/<hash>/state.vscdb) was investigated. It stores composer.composerData (conversation metadata only — IDs, names, timestamps) and aiService.prompts (user prompts without assistant responses). Since there are no paired conversation turns in the SQLite format, the agent transcript JSONL is the only format with complete conversations suitable for MemPalace ingestion.

Changes

File	Change
mempalace/normalize.py	Add _try_cursor_jsonl() parser + wire into _try_normalize_json() dispatch chain + update module docstring
tests/test_normalize.py	Add 8 test cases: basic, multi-turn, empty content, single-message rejection, Claude Code JSONL rejection, multi-block content, malformed lines, plain-string content rejection

Test plan

• All 109 existing + new tests pass (pytest tests/ -v)
• Zero Ruff lint errors
• Reviewer: verify parser ordering doesn't interfere with existing Claude Code / Codex JSONL detection
• Reviewer: confirm has_cursor_structure guard is sufficient to prevent false positives

Closes #59 (Cursor portion)

[bgauryy]

PR Review: feat: add Cursor agent transcript JSONL normalizer

Executive Summary

Aspect	Value
PR Goal	Add _try_cursor_jsonl() parser to import Cursor IDE agent transcript sessions into the mempalace normalization pipeline
Files Changed	2
Risk Level	🟢 LOW - Pure additive change, reuses existing helpers, well-guarded format discrimination
Review Effort	2 - Clean, focused feature with thorough tests
Recommendation	✅ APPROVE

Affected Areas: mempalace/normalize.py (parser + dispatch), tests/test_normalize.py (9 new test functions)

Business Impact: Enables mining Cursor IDE conversations into the palace, expanding the supported conversation sources. Addresses part of #59.

Flow Changes: New parser slot in _try_normalize_json() dispatch chain — runs after _try_codex_jsonl, before json.loads(). No existing flows altered.

Ratings

Aspect	Score
Correctness	5/5
Security	5/5
Performance	5/5
Maintainability	4/5

PR Health

• Has clear description
• References ticket/issue (feat: add import support for more AI tool session formats (Cursor, Copilot, Codex, Windsurf, Aider, etc.) #59)
• Appropriate size (163 additions, 2 files)
• Has relevant tests (9 test functions)

High Priority Issues

None.

Medium Priority Issues

None.

Low Priority Issues

🐛 #1: has_cursor_structure flag can be set by empty-text entries

Location: mempalace/normalize.py:~178 (new code) | Confidence: ⚠️ MED

The has_cursor_structure = True flag is set whenever raw_content is a list, regardless of whether the entry actually contributes text to messages. In a pathological input where the only list-content entry has empty text (so it gets skipped), but two string-content entries survive, the parser would match — even though no list-typed entry actually contributed to the output.

Practically near-impossible with real Cursor transcripts, but the flag could be tightened:

-        if isinstance(raw_content, list):
-            has_cursor_structure = True
-
         text = _extract_content(raw_content)
         if not text:
             continue
+        if isinstance(raw_content, list):
+            has_cursor_structure = True
         messages.append((role, text))

This moves the flag after the emptiness check, so only entries that actually produce output set it.

---

🎨 #2: Missing test for entries with role but no message key

Location: tests/test_normalize.py (new tests section) | Confidence: ✅ HIGH

The parser correctly handles entries like {"role": "user", "other_key": "data"} (no message) — entry.get("message") returns None, isinstance(None, dict) is False, entry is skipped. However, no test covers this edge case. A brief test would document the contract:

def test_cursor_jsonl_skips_entries_without_message_key():
    """Entries with role but no message dict are skipped."""
    path = _write_jsonl([
        {"role": "user"},
        {"role": "user", "message": {"content": [{"type": "text", "text": "Q"}]}},
        {"role": "assistant", "message": {"content": [{"type": "text", "text": "A"}]}},
    ])
    result = normalize(path)
    assert "> Q" in result
    assert "A" in result
    os.unlink(path)

---

🔗 #3: Discrimination test couples to Claude Code parser output

Location: tests/test_normalize.py:test_cursor_jsonl_ignores_non_cursor_jsonl | Confidence: ⚠️ MED

The test asserts "> Hi from Claude Code" in result — verifying the Claude Code parser picks up the input after the Cursor parser rejects it. This is useful as an integration test but means a future change to _try_claude_code_jsonl output formatting could break this test even though the Cursor parser is correct. Consider splitting into a focused unit assertion (Cursor returns None) and a separate integration check.

---

Flow Impact Analysis

normalize(filepath)
  └─ _try_normalize_json(content)
       ├─ _try_claude_code_jsonl(content)   ← uses "type" key → no overlap
       ├─ _try_codex_jsonl(content)          ← uses "event_msg" / "session_meta" → no overlap
       ├─ _try_cursor_jsonl(content)         ← NEW: uses "role" + message.content as list
       ├─ json.loads(content) → ...
       │    ├─ _try_claude_ai_json(data)
       │    ├─ _try_chatgpt_json(data)
       │    └─ _try_slack_json(data)
       └─ return None

Discrimination matrix (why parsers don't interfere):

Format	Key used	Cursor parser sees	Result
Claude Code JSONL	type: "human"	role = "" → skip all	✅ No match
Codex JSONL	event_msg / session_meta	role = "" → skip all	✅ No match
Cursor JSONL	role: "user" + list content	Matches correctly	✅ Match
Claude Code → Cursor?	Has type, not role	All entries skipped	✅ Safe
Cursor → Claude Code?	Has role, not type	All entries skipped	✅ Safe

No cross-contamination risk between any parser pair.

Strengths

• Clean discrimination: The role vs type distinction is simple and bulletproof
• has_cursor_structure flag: Smart heuristic — requires list-typed content to prevent matching generic role-based JSONL
• Helper reuse: Leverages existing _extract_content() and _messages_to_transcript() — zero duplication of output logic
• Excellent test coverage: 9 tests covering happy path, multi-turn, empty content, single message rejection, format discrimination, multiple content blocks, malformed lines, and string-vs-list content
• Consistent style: Follows the exact same pattern as _try_claude_code_jsonl and _try_codex_jsonl

---

Created by Octocode MCP https://octocode.ai 🔍🐙

[web3guru888]

Clean implementation. A few observations from working with this format in production:

Detection logic is solid. The dual guard ( in + ) correctly discriminates against Claude Code JSONL (top-level ) and Codex JSONL ( wrapper). The has_cursor_structure flag requiring at least one list-typed content block is a good extra check before committing.

The SQLite investigation note is useful context. The explanation of why is incomplete (no paired turns in , only prompts without responses) saves future contributors from going down that path again. Consider keeping a brief note in the docstring or a comment.

Missing edge case: tool/image content blocks. Cursor agent transcripts can include non-text content blocks (, ). The current will silently skip them (correct behavior), but it's worth a test confirming that a turn containing only non-text blocks doesn't produce a phantom message. Something like:

Test coverage is thorough — malformed lines, single-message files, wrong schema, multi-block content. The integration check is a nice touch.

One nit: the import in the test file suggests it's part of the public API. If that's intentional (for testing), it's fine — just worth noting that it's now a surface others might rely on.

Overall this is a clean, focused addition that fills a real gap for teams using Cursor. The heuristic is conservative enough to avoid false positives.

[web3guru888]

(Addendum to my review above — the shell ate the backtick formatting, sorry for the noise. The cleaned-up version:)

Detection logic is solid. The dual guard (role in {"user","assistant"} + isinstance(raw_content, list)) correctly discriminates against Claude Code JSONL (top-level type) and Codex JSONL (event_msg wrapper). The has_cursor_structure flag requiring at least one list-typed content block is a good extra check before committing.

Missing edge case worth testing: tool/image content blocks. Cursor transcripts can include non-text blocks ({"type": "tool_result", ...}, {"type": "image", ...}). The current _extract_content will silently skip these (correct), but worth adding a test that a turn containing only non-text blocks doesn't produce a phantom empty message in the output.

The SQLite investigation note is useful context. The explanation of why state.vscdb is incomplete (no paired turns in aiService.prompts) saves future contributors from going down that path. Consider preserving it in the docstring.

Test coverage otherwise looks thorough — malformed lines, single-message files, wrong schema, multi-block content all covered. The >=2 messages + list content heuristic is conservative enough to avoid false positives.

[bensig]

Conflicts with main. Cursor JSONL normalization is being addressed in #287. Thanks.