cam/USAGE.md

CAM Usage Workflow

Step-by-step order for moving Cursor agent context between workstations.

Repository: https://git.p7net.ru/tools/cam.git
Version: 0.0.1 (in development)

---

One-time setup (each workstation)

1. Clone CAM into the project

From the consumer project root (e.g. crm3-migration):

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

2. Create a local workstation config

cp config/workstations/macos.example.yml config/workstations/local.yml
# Windows: cp config/workstations/windows.example.yml config/workstations/local.yml

Edit config/workstations/local.yml:

Key	Set to
workstation.id	Short ID for this PC (e.g. nt-041, office-pc)
project.root	Absolute path to the project opened in Cursor
export.output_dir	Usually docs/cursor_agents
export.index_language	en or ru

local.yml is gitignored — never commit real paths to the public CAM repo.

3. Verify paths

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

Check transcripts_dir points to your Cursor agent-transcripts folder.

---

Before leaving a workstation (save context)

Run from the project root:

source .venv-nt-041/bin/activate   # or your project venv
python tools/cam/cam.py -c tools/cam/config/workstations/local.yml export

This updates in the project:

• docs/cursor_agents/raw/ — JSONL transcripts
• docs/cursor_agents/markdown/ — readable exports
• docs/cursor_agents/manifest.json, INDEX.md

Commit and push the consumer project repository:

git add docs/cursor_agents/
git commit -m "Export Cursor agent history from <workstation-id>"
git push

---

On a new workstation (restore context)

1. Clone the consumer project

git clone https://git.p7net.ru/rhana/crm3-migration.git crm3-26
cd crm3-26

See the project’s docs/meta/REPOSITORIES.md for other required clones (configs, tools/run_bsl, etc.).

2. Set up CAM (one-time on this PC)

git clone https://git.p7net.ru/tools/cam.git tools/cam
cp tools/cam/config/workstations/macos.example.yml tools/cam/config/workstations/local.yml
# edit project.root to this machine’s absolute path
python tools/cam/cam.py -c tools/cam/config/workstations/local.yml paths

3. Import into Cursor (optional — chat sidebar)

Close Cursor completely, then:

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

Re-open Cursor. Existing local files are not overwritten unless import.overwrite_existing: true in config.

4. Continue work with the agent (recommended)

In a new Cursor Agent chat:

@docs/cursor_agents/INDEX.md
Continue work on <topic>. Context was exported from workstation <id>.

This works reliably across machines; UI import is best-effort.

---

Daily cycle (two-way sync)

Workstation A                          Workstation B
─────────────                          ─────────────
  export                                 git pull
  git commit + push          ──────►    import (optional)
                                         work…
  git pull                   ◄──────    export
  import (optional)                    git commit + push
  work…
  export …

Step	Command	Direction
export	python tools/cam/cam.py -c …/local.yml export	Cursor local → project archive
import	python tools/cam/cam.py -c …/local.yml import	project archive → Cursor local

---

Command reference

All commands use -c before the subcommand:

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

---

CRM3-26 / crm3-migration example

# nt-041 (macOS) — template
cp tools/cam/config/workstations/nt-041.example.yml tools/cam/config/workstations/local.yml
# set project.root: /Users/you/projects/crm3-26

python tools/cam/cam.py -c tools/cam/config/workstations/local.yml export
git add docs/cursor_agents/ && git commit -m "Export Cursor agent history" && git push

---

Troubleshooting

Problem	Check
Transcripts folder not found	Open project in Cursor once; run paths; fix project.root
Wrong slug / empty transcripts	project.root must match the path Cursor uses exactly
Import skips files	Set import.overwrite_existing: true or delete old local transcripts
Chats not in sidebar after import	Use @docs/cursor_agents/INDEX.md — UI restore is not guaranteed

---

Security

• Do not commit workstation configs with secrets to cam.git.
• Agent transcripts may contain business data — treat docs/cursor_agents/ like project documentation in your private migration repo.