alekspetrov/navigator/nav-marker

mkdir -p .agent/.context-markers

Creating marker: [name]
 
Add a note? (optional - helps remember context later)
Example: "OAuth working, need to add tests"
 
Note:

# Context Marker: [name]
 
**Created**: [YYYY-MM-DD HH:MM]
**Note**: [user's note or "No note provided"]
 
---
 
## Conversation Summary
 
[Summarize last 10-15 messages:
-What user was working on
-Key decisions made
-Problems solved
-Current progress state
]
 
## Documentation Loaded
 
[List docs that were Read during session:
-Navigator: ✅ .agent/DEVELOPMENT-README.md
-Task: TASK-XX-feature.md
-System: project-architecture.md
-SOPs: [if any]
]
 
## Files Modified
 
[List files with Write/Edit calls:
-src/auth/login.ts (implemented OAuth)
-src/routes/auth.ts (added endpoints)
-tests/auth.test.ts (created tests)
]
 
## Current Focus
 
[What user is working on right now:
-Feature: Authentication with OAuth
-Phase: Integration complete, testing pending
-Blockers: [if any]
]
 
## Technical Decisions
 
[Key architectural choices:
-Using passport.js over next-auth (better control)
-JWT tokens in httpOnly cookies (XSS protection)
-Redis for session storage (scalability)
]
 
## Next Steps
 
[What to do after restore:
1.Finish writing tests for OAuth flow
2.Add error handling for failed logins
3.Document setup in README
]
 
## User Intent & Goals (ToM) [CAPTURE ACTIVELY]
 
[Theory of Mind section - captures user's mental state for better restoration]
 
**⚠️ CRITICAL: Analyze conversation to extract these - do not leave empty!**
 
**Primary goal this session**:
[What the user was ultimately trying to accomplish - not just the surface task]
-Review conversation for "I want to...", "The goal is...", "We need to..."
-Infer from task context if not explicitly stated
 
**Stated preferences**:
[Any preferences expressed during session:
-Communication style (concise/detailed)
-Code patterns preferred
-Confirmation behavior wanted
]
-Look for "I prefer...", "Don't do...", "Always use..."
 
**Corrections made**:
[Important corrections that should persist:
-"Should be /users not /user (plural convention)"
-"Prefer functional components over class"
-"Always use TypeScript strict mode"
]
-Look for "No, I meant...", "Actually...", "Not X, use Y"
-These MUST be captured to avoid repeating mistakes
 
## Belief State [CAPTURE ACTIVELY]
 
[Captures mutual understanding state for accurate restoration]
 
**⚠️ CRITICAL: Infer from conversation - do not leave empty!**
 
**What user knows**:
[User's demonstrated knowledge level:
-Familiar with Express, new to Passport
-Knows about JWT, unfamiliar with refresh tokens
-Senior developer, skip basics
]
 
**Assumptions I made**:
[Key assumptions during session:
-Using Redis for sessions (confirmed by user)
-Auth endpoints follow /api/auth/* pattern
-Testing with Jest + React Testing Library
]
 
**Uncertainty areas**:
[Questions that weren't fully resolved:
-Not sure if user wants social logins beyond Google
-Rate limiting requirements unclear
-Error message format preferences unknown
]
 
## Loop State (if in loop mode)
 
[Capture loop mode state for resumption - skip if not in loop mode]
 
**Iteration**: [N]/[MAX] (e.g., 3/5)
**Phase**: [INIT|RESEARCH|IMPL|VERIFY|COMPLETE]
**State Hash**: [6-char hash for continuity]
**Completion Indicators**:
-[ ] Code committed
-[ ] Tests passing
-[ ] Documentation updated
-[ ] Ticket closed
-[ ] Marker created
 
**EXIT_SIGNAL**: [true/false]
**Stagnation Count**: [N]/[THRESHOLD]
 
## Knowledge Graph State (v6.0.0+)
 
[Capture graph state for restoration - skip if no knowledge graph]
 
**Check if graph exists**:

 
**Memories surfaced this session**:
[List memories that were queried or created:
- mem-001: "Auth changes break session tests" (surfaced)
- mem-002: "Use plural REST endpoints" (created from correction)
]
 
**Concepts active**:
[Concepts relevant to current work:
- authentication
- testing
- api
]
 
**Graph queries made**:
[Knowledge graph queries from this session:
- "What do we know about auth?" → 3 tasks, 1 memory
]
 
This allows restoration to re-surface relevant memories when resuming.
 
## Restore Instructions
 
To restore this marker:
\```bash
Read .agent/.context-markers/[filename]
\```
 
Or use: `/nav:markers` and select this marker

Write(
  file_path: ".agent/.context-markers/[timestamp]_[name].md",
  content: [generated marker content]
)

# Verify file exists and is non-empty
if [ -f ".agent/.context-markers/[filename]" ] && [ -s ".agent/.context-markers/[filename]" ]; then
  # Calculate checksum for verification
  checksum=$(md5 -q ".agent/.context-markers/[filename]" 2>/dev/null || md5sum ".agent/.context-markers/[filename]" | cut -d' ' -f1)
 
  # Log to central marker log
  echo "[$(date -u +"%Y-%m-%dT%H:%M:%SZ")] ✅ Marker created: [filename] (checksum: $checksum)" >> .agent/.marker-log
 
  echo "✅ Marker verified successfully"
else
  echo "❌ Marker creation failed - file missing or empty"
  exit 1
fi

✅ Context marker created!
 
Marker: [name]
File: .agent/.context-markers/[filename]
Size: [X] KB (~[Y] tokens)
Checksum: [md5-hash]
Verified: ✅
 
This marker captures:
- Last [N] messages of conversation
- Files you were working on
- Technical decisions made
- Next steps to continue
 
To restore later:
- Start new session
- Say "load marker [name]"
- Or use /nav:markers to list all markers
 
Logged to: .agent/.marker-log

User: "Save my progress, taking lunch"
→ Creates marker: "lunch-break-2025-10-16"
→ Captures current state
→ User resumes after lunch: "Load my lunch marker"

User: "Mark this before I refactor routing"
→ Creates marker: "before-routing-refactor"
→ If refactor fails, restore marker
→ If refactor succeeds, delete marker

User: "End of day checkpoint"
→ Creates marker: "eod-2025-10-16"
→ Note: "OAuth done, tests tomorrow"
→ Next morning: "Load yesterday's marker"

Automatic (via nav-compact skill):
→ Creates marker: "before-compact-2025-10-16-1500"
→ Compact clears conversation
→ Marker preserves knowledge
→ Next session: Auto-offers to restore

Creating .agent/.context-markers/ directory...
✅ Ready to save markers

⚠️  Marker "[name]" already exists
 
Options:
1. Overwrite (replace existing)
2. Append timestamp (create "[name]-v2")
3. Choose different name
 
Your choice [1-3]:

⚠️  Very little context to save (< 5 messages)
 
Markers work best when there's significant progress to preserve.
Continue anyway? [y/N]: