Release v0.1.0: context codes and readable archive file names.
- registry.yaml maps codes (w1-1, w1.git.001) to sessions and stable paths
- Markdown files named {code}--{slug}.md for Cursor @ picker
- Selective export/import via --context and --mask
- cam code list|set|show for manual code assignment
- Re-export updates same file per context code
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -3,179 +3,179 @@
|
||||
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)
|
||||
**Version:** 0.1.0 (in development)
|
||||
|
||||
---
|
||||
|
||||
## Context codes (readable names)
|
||||
|
||||
Each agent session gets a **context code** stored in `registry.yaml`:
|
||||
|
||||
| Code type | Example | Meaning |
|
||||
|-----------|---------|---------|
|
||||
| Auto main | `w1-1`, `w2-110` | `{workstation.index}-{seq}` |
|
||||
| Auto subagent | `w1-11.1` | `{parent}.{seq}` |
|
||||
| Manual | `w1.git.001`, `sync-crm3` | Assigned by operator |
|
||||
|
||||
Markdown files use readable names for Cursor `@`:
|
||||
|
||||
```
|
||||
docs/cursor_agents/markdown/w1-11--Из-исходной-базы-в-целевую.md
|
||||
docs/cursor_agents/markdown/w1.git.001--sync-analysis.md
|
||||
```
|
||||
|
||||
**Re-export updates the same file** for a given code (consolidated/enriched context overwrites in place).
|
||||
|
||||
In a new Cursor chat:
|
||||
|
||||
```
|
||||
@docs/cursor_agents/markdown/w1-11--Из-исходной-базы-в-целевую.md
|
||||
```
|
||||
|
||||
or reference by code:
|
||||
|
||||
```
|
||||
Context w1-11 — continue transfer of customer orders.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## One-time setup (each workstation)
|
||||
|
||||
### 1. Clone CAM into the project
|
||||
|
||||
From the **consumer project root** (e.g. `crm3-migration`):
|
||||
### 1. Clone CAM
|
||||
|
||||
```bash
|
||||
git clone https://git.p7net.ru/tools/cam.git tools/cam
|
||||
cd tools/cam
|
||||
pip install -r requirements.txt
|
||||
pip install -r tools/cam/requirements.txt
|
||||
```
|
||||
|
||||
### 2. Create a local workstation config
|
||||
### 2. Workstation config
|
||||
|
||||
```bash
|
||||
cp config/workstations/macos.example.yml config/workstations/local.yml
|
||||
# Windows: cp config/workstations/windows.example.yml config/workstations/local.yml
|
||||
cp tools/cam/config/workstations/macos.example.yml tools/cam/config/workstations/local.yml
|
||||
```
|
||||
|
||||
Edit `config/workstations/local.yml`:
|
||||
Required fields:
|
||||
|
||||
| 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` |
|
||||
```yaml
|
||||
workstation:
|
||||
id: "nt-041"
|
||||
index: "w1" # w1, w2, … — prefix for auto codes
|
||||
|
||||
`local.yml` is **gitignored** — never commit real paths to the public CAM repo.
|
||||
context:
|
||||
prefix_workstation: true # w1-1 (true) or 1 (false)
|
||||
auto_format: "{ws}-{seq}"
|
||||
subagent_format: "{parent}.{seq}"
|
||||
|
||||
### 3. Verify paths
|
||||
registry:
|
||||
file: "registry.yaml"
|
||||
```
|
||||
|
||||
### 3. Verify
|
||||
|
||||
```bash
|
||||
python cam.py -c config/workstations/local.yml paths
|
||||
python tools/cam/cam.py -c tools/cam/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**:
|
||||
## Before leaving a workstation
|
||||
|
||||
```bash
|
||||
source .venv-nt-041/bin/activate # or your project venv
|
||||
# all contexts
|
||||
python tools/cam/cam.py -c tools/cam/config/workstations/local.yml export
|
||||
|
||||
# one context
|
||||
python tools/cam/cam.py -c tools/cam/config/workstations/local.yml export --context w1-11
|
||||
|
||||
# by mask
|
||||
python tools/cam/cam.py -c tools/cam/config/workstations/local.yml export --mask 'w1-*'
|
||||
```
|
||||
|
||||
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:
|
||||
Commit project archive:
|
||||
|
||||
```bash
|
||||
git add docs/cursor_agents/
|
||||
git commit -m "Export Cursor agent history from <workstation-id>"
|
||||
git commit -m "Export Cursor agent contexts (w1)"
|
||||
git push
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## On a new workstation (restore context)
|
||||
|
||||
### 1. Clone the consumer project
|
||||
|
||||
```bash
|
||||
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)
|
||||
|
||||
```bash
|
||||
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:
|
||||
## On a new workstation
|
||||
|
||||
```bash
|
||||
git pull
|
||||
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
|
||||
# or selective:
|
||||
python tools/cam/cam.py -c tools/cam/config/workstations/local.yml import --mask 'w1-*'
|
||||
```
|
||||
|
||||
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.
|
||||
Close Cursor before import. For new agent work, prefer `@markdown/w1-11--….md`.
|
||||
|
||||
---
|
||||
|
||||
## Daily cycle (two-way sync)
|
||||
## Manual context codes
|
||||
|
||||
```
|
||||
Workstation A Workstation B
|
||||
───────────── ─────────────
|
||||
export git pull
|
||||
git commit + push ──────► import (optional)
|
||||
work…
|
||||
git pull ◄────── export
|
||||
import (optional) git commit + push
|
||||
work…
|
||||
export …
|
||||
```bash
|
||||
# list all codes
|
||||
python tools/cam/cam.py -c tools/cam/config/workstations/local.yml code list
|
||||
|
||||
# rename w1-11 → thematic code
|
||||
python tools/cam/cam.py -c tools/cam/config/workstations/local.yml code set w1-11 w1.git.zakaz
|
||||
|
||||
# show details
|
||||
python tools/cam/cam.py -c tools/cam/config/workstations/local.yml code show w1.git.zakaz
|
||||
```
|
||||
|
||||
| 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 |
|
||||
Rules for manual codes: letters, digits, `.`, `-`, `_` (e.g. `w1.git.001`, `sync-crm3`).
|
||||
|
||||
To drop workstation prefix in **new** auto codes only:
|
||||
|
||||
```yaml
|
||||
context:
|
||||
prefix_workstation: false
|
||||
auto_format: "{seq}"
|
||||
```
|
||||
|
||||
Existing codes in `registry.yaml` are not renamed automatically.
|
||||
|
||||
---
|
||||
|
||||
## Command reference
|
||||
|
||||
All commands use `-c` **before** the subcommand:
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `export` | Cursor → project archive |
|
||||
| `import` | project archive → Cursor |
|
||||
| `list` | List contexts in archive |
|
||||
| `code list` | List codes from registry |
|
||||
| `code set TARGET NEW` | Assign/rename code |
|
||||
| `code show CODE` | Show context record |
|
||||
| `paths` | Resolved paths |
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
Flags: `--context CODE`, `--mask PATTERN` (glob: `w1-*`, `*.git.*`).
|
||||
|
||||
---
|
||||
|
||||
## CRM3-26 / crm3-migration example
|
||||
## Archive layout (0.1.0)
|
||||
|
||||
```bash
|
||||
# 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 |
|
||||
docs/cursor_agents/
|
||||
├── registry.yaml # codes ↔ session UUID ↔ file paths
|
||||
├── INDEX.md
|
||||
├── manifest.json
|
||||
├── raw/ # JSONL by session UUID (for Cursor import)
|
||||
└── markdown/
|
||||
├── w1-1--topic.md # @-friendly names
|
||||
└── subagents/
|
||||
└── w1-1.1--topic.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
Do not commit workstation `local.yml` with secrets to public repos.
|
||||
Agent transcripts may contain business data — keep `docs/cursor_agents/` in your private project repo.
|
||||
|
||||
Reference in New Issue
Block a user