cam/README.md

CAM — Cursor Agents Manager

Version: 0.0.1
Status: in development
License: MIT

CAM exports and imports Cursor agent conversation transcripts so you can version them in a project repository and move context between workstations.

Repository: https://git.p7net.ru/tools/cam.git

Why

Cursor stores agent history locally under ~/.cursor/projects/<workspace-slug>/agent-transcripts/. That data does not travel with your git project. CAM:

1. Export — copy transcripts into docs/cursor_agents/ (or another folder) as JSONL + Markdown + index
2. Commit — push the archive with your project
3. Import (optional) — restore .jsonl files into Cursor on another machine
4. Continue — open @docs/cursor_agents/INDEX.md in a new Cursor chat for agent context

Requirements

• Python 3.10+
• PyYAML

pip install -r requirements.txt

Quick start

1. Clone CAM into your project

git clone https://git.p7net.ru/tools/cam.git tools/cam
cd tools/cam
pip install -r requirements.txt

2. Create a workstation config

Each machine needs its own YAML file (not committed to the public CAM repo):

cp config/workstations/macos.example.yml config/workstations/local.yml
# edit project.root and other paths

Or copy a project-specific example if your project provides one (e.g. nt-041.example.yml).

Config search order (first existing file wins):

1. --config argument
2. $CAM_CONFIG environment variable
3. config/workstations/<hostname>.yml
4. config/workstations/local.yml
5. config/config.yml

3. Export

python cam.py -c config/workstations/local.yml export

4. Commit archive (in your project repo)

git add docs/cursor_agents/
git commit -m "Export Cursor agent history"

5. Import on another workstation (optional)

Close Cursor first, then:

python cam.py -c config/workstations/local.yml import --dry-run   # preview
python cam.py -c config/workstations/local.yml import

Re-open Cursor. Chat history may appear in the sidebar depending on Cursor version (undocumented behaviour).

Recommended: use the Markdown archive and @docs/cursor_agents/INDEX.md in a new agent chat instead of relying on UI restore.

Commands

Command	Description
paths	Show resolved paths (project, transcripts, export dir)
export	Export Cursor transcripts to project archive
import	Copy archive raw/ back to Cursor transcripts folder
list	List sessions in the export archive

python cam.py --version
python cam.py -c config/workstations/local.yml paths
python cam.py -c config/workstations/local.yml export
python cam.py -c config/workstations/local.yml import --dry-run
python cam.py -c config/workstations/local.yml list

Configuration

See config/config.example.yml.

Key	Description
workstation.id	Short ID stored in manifest.json (no secrets)
workstation.label	Human-readable workstation name
project.root	Absolute path to project root opened in Cursor
project.name	Display name
cursor.transcripts_dir	Override transcripts path (optional)
cursor.home	Override ~/.cursor (optional)
export.output_dir	Archive directory relative to project.root
export.index_language	en or ru for generated Markdown
import.overwrite_existing	Replace existing Cursor transcript files

Security: do not put passwords, tokens, or private hostnames into configs committed to the open CAM repository. Keep real workstation configs local (*.yml is gitignored; only *.example.yml templates are tracked).

Archive layout

docs/cursor_agents/
├── INDEX.md
├── manifest.json
├── raw/
│   ├── <session-id>.jsonl
│   └── <parent-id>/subagents/<subagent-id>.jsonl
└── markdown/
    ├── <session-id>.md
    └── subagents/<subagent-id>.md

Cursor project slug

If cursor.transcripts_dir is omitted, CAM derives:

~/.cursor/projects/<slug>/agent-transcripts/

where <slug> is built from the absolute project.root path (slashes → dashes, drive letter lowercased on Windows). Example:

Project root	Cursor slug
/Users/you/projects/my-app	Users-you-projects-my-app
D:/work/my-app	d-work-my-app

Use python cam.py paths to verify the resolved path on your machine.

Integration with consumer projects

Consumer projects (e.g. crm3-migration) typically:

1. Clone CAM into tools/cam/ (separate git repo)
2. Keep a project-specific config/workstations/<host>.example.yml template in the consumer repo or local docs
3. Store exports in docs/cursor_agents/

Development

python cam.py paths -c config/config.example.yml   # fails until project.root exists

Changelog

See CHANGELOG.md.