Passive Capture

Rules File Sync

Edit .contxt/rules.md in your IDE and watch it sync to memory automatically.

The Rules File

.contxt/rules.md is a human-readable markdown file that mirrors your memory store. It gives you a plain-text window into everything Contxt knows about your project — your stack, architectural decisions, coding patterns, and active context.

Because it lives in your repository, you can read and edit it directly in your IDE. Contxt watches for changes and syncs them back to the memory store automatically, keeping both representations in lockstep.

File Format

The rules file uses standard markdown headings to separate memory categories. Each heading maps to a specific memory type, and the bullet items beneath become individual memory entries.

# Stack
- Next.js 14, App Router
- Prisma + Postgres
- Stripe Billing

# Decisions
- Use Prisma for ORM (better TS support than Drizzle)
- JWT in httpOnly cookies (stateless, refresh rotation)

# Patterns
- API routes: Zod schema → validate → handler → typed response
- Error handling: centralized with exponential backoff

# Context
Currently building user onboarding flow.
Blocked on Stripe webhook integration.

Section Parsing

Each markdown heading signals a different parsing strategy. Contxt applies the appropriate parser to each section when syncing.

HeadingBehavior
# StackProject stack metadata — stored as stack entries on the project
# DecisionsDecision entries — text in parentheses is extracted as rationale
# PatternsPattern entries — text before the colon becomes the pattern name
# ContextActive context entry — replaces the current context block entirely
Any other headingDocument entry — stored as a document with the heading as the title

CLI Commands

Three commands cover the full sync lifecycle:

$ contxt rules sync       # Parse rules.md → update memory
$ contxt rules generate   # Generate rules.md from memory (first-time bootstrap)
$ contxt rules diff       # Show what's out of sync (no writes)
  • sync

    Reads the current rules.md and upserts changed entries into memory. Safe to run repeatedly — unchanged entries are detected by content hash and skipped.

  • generate

    Writes a fresh rules.md from whatever is already in memory. Use this on first setup if memory was built through other means (CLI commands, MCP, git hooks).

  • diff

    Compares the file and memory without writing anything. Useful before syncing to confirm exactly what will change.

Auto-Sync with Watch

When contxt watch is running, you do not need to run contxt rules sync manually. The daemon monitors .contxt/rules.md for file system changes and automatically triggers a sync the moment you save the file in your editor. Changes appear in memory within seconds.

$ contxt watch --daemon
✓ Watcher started (PID 48291)

# Edit .contxt/rules.md in your editor
# Save the file
  15:22  rules    rules.md changed — syncing 2 updates

See the Watch Daemon page for full setup instructions.