Autonomous Agent Guide

// 1. Initialize with full context (RECOMMENDED - ONE CALL DOES IT ALL)
const init = await session_init({
  agent_name: "cursor",
  task: "Add authentication",
});
// Returns: session ID, workspace briefing, project structure, pending handoffs
 
// 2. Get file context before editing
const fileContext = await file_context({ file_path: "auth/jwt.ts" });
// fileContext includes: learnings, decisions, failures, hotspots
 
// 3. End session when done
await session({
  action: "end",
  outcome: "success",
  summary: "Added JWT refresh tokens",
});

const init = await session_init({
  agent_name: "cursor",
  task: "Add JWT refresh token support",
});

const resumed = await session_resume({
  sessionId: "sess_abc123", // Or use agentType to find latest
});

// Find relevant code
const results = await explore({
  action: "search",
  query: "jwt authentication",
});
 
// Get room context
const rooms = await explore({ action: "rooms" }); // ["api", "auth", "database"]
const authContext = await explore({ action: "context", room: "auth" });
 
// Understand dependencies
const impact = await explore({ action: "impact", path: "auth/jwt.ts" });
const callers = await explore({
  action: "callers",
  symbol: "validateToken",
  file: "auth/jwt.ts",
});

// Check for related learnings
const learnings = await recall({
  action: "query",
  query: "jwt authentication",
});
 
// Check for active decisions
const decisions = await recall({
  action: "query",
  type: "decisions",
  query: "token validation",
  status: "active",
});
 
// Learn from past failures
const postmortems = await postmortem({ action: "list", severity: "high" });

const context = await context({
  action: "auto_inject",
  file_path: "auth/jwt.ts",
});

const conflict = await session({ action: "conflict", path: "auth/jwt.ts" });
if (conflict.has_conflict) {
  console.log(`${conflict.agent_name} is already editing this file`);
  // Coordinate or wait
}

await session({
  action: "log",
  activity: "file_edit",
  path: "auth/jwt.ts",
  description: "Added refresh token validation logic",
});

// Store learnings
await store({
  content:
    "JWT refresh tokens should expire in 7 days, access tokens in 1 hour",
  as: "decision",
  scope: "room",
  scopePath: "auth",
  rationale: "Balance security (short access tokens) with UX (longer refresh)",
});
 
// Store learnings from solving problems
await store({
  content:
    "JWT signature validation must happen before expiration check to prevent timing attacks",
  as: "learning",
  scope: "file",
  scopePath: "auth/jwt.ts",
});

await session({
  action: "end",
  outcome: "success",
  summary:
    "Added JWT refresh token support with proper validation and expiration handling",
});

await store_postmortem({
  title: "JWT signature bypass vulnerability",
  what_happened: "Expired tokens were accepted due to wrong validation order",
  root_cause:
    "Checked expiration before signature, allowing signature replay attacks",
  lessons_learned: [
    "Always validate signature first",
    "Add integration tests for expired tokens",
    "Review security checklist before auth changes",
  ],
  prevention_steps: [
    "Reorder validation: signature → expiration → claims",
    "Add test: test_expired_token_rejection()",
    "Add pre-commit hook for auth file changes",
  ],
  severity: "critical",
  affected_files: ["auth/jwt.ts", "middleware/authenticate.ts"],
  related_decision: "d_abc123",
});
 
// Extract learnings from postmortem
await postmortem_to_learnings({ postmortemId: "pm_xyz789" });

await context_focus({
  task: "Implement rate limiting for API endpoints",
  pin: ["l_ratelimit123", "d_api456"], // Pin specific records
});

const context = await context_get({
  file: "api/middleware.ts", // Optional: file-specific
  maxTokens: 2000,
});

// Pin a crucial learning for this session
await context_pin({ id: "l_important123" });
 
// Unpin when no longer needed
await context_pin({ id: "l_important123", unpin: true });

await handoff_create({
  task: "Complete API rate limiting implementation",
  to: "claude-code", // Or "any" for any agent
  context:
    "Started implementing token bucket algorithm. Redis backend configured.",
  pending: [
    "Add rate limit headers to responses",
    "Implement per-user limits",
    "Add monitoring dashboard",
  ],
  pin: ["l_ratelimit123"], // Include relevant learnings
  priority: "high",
});

const handoffs = await handoff_list({ status: "pending" });

const handoff = await handoff_accept({ id: "hoff_12345678" });
// Automatically sets your context focus to the handoff task
// Pins the handoff's records to your context

await handoff_complete({
  id: "hoff_12345678",
  summary: "Implemented all rate limiting features with Redis backend",
});

const health = await analytics_health();
// Returns: health score (0-100), knowledge health, contradictions,
// session success rates, failure tracking, handoff status

const stats = await analytics_sessions({ days: 30 });
// Returns: session counts, completion rates, average duration,
// activity outcomes, agent breakdown

const effectiveness = await analytics({
  type: "learnings",
  limit: 20,
  sort: "use_count", // or "confidence" or "combined"
});
// Shows which learnings are most used and effective

// Conceptual search - finds related concepts even without keyword match
await search({
  mode: "semantic",
  query: "retry logic with exponential backoff",
});
 
// Hybrid: keyword + semantic (best of both)
await search({ mode: "hybrid", query: "error handling" });
 
// Find similar records
await search({ mode: "similar", recordId: "l_abc123" });

// Check for contradicting records
await contradiction({
  action: "check",
  record1Id: "l_abc123",
  record2Id: "d_xyz789",
});
 
// Resolve contradiction
await contradiction({ action: "resolve", conflictId: "conflict_123" });

// Preview what would decay
await decay({ action: "check" });
 
// Apply decay (reduces confidence of unused learnings)
// NEVER do this without preview + user approval
await decay({ action: "prune" });

// Link learning to decision for automatic feedback
await recall({
  action: "link",
  decisionId: "d_abc123",
  learningId: "l_xyz789",
});
// Now when decision outcome is recorded, learning confidence auto-updates
 
// Record decision outcome
await recall({
  action: "outcome",
  decisionId: "d_abc123",
  outcome: "success",
  note: "Reduced DB queries by 60%, no issues in production",
});
 
// Mark learning as obsolete
await recall({
  action: "obsolete",
  learningId: "l_old123",
  reason: "Superseded by new approach using Redis caching",
});

// Get personal learnings from all your projects
await corridor({ action: "learnings", query: "error handling" });
 
// Promote workspace learning to personal corridor
await corridor_promote({ learningId: "l_abc123" });
// Now this learning follows you to every project
 
// Reinforce corridor learning when it helps
await corridor_reinforce({ learningId: "l_corridor456" });

# Initialize Mind Palace in your project
palace init
palace scan
 
# Install MCP config and agent rules
palace mcp-config --for claude-code --install

palace mcp-config --for cursor --install

// 1. Initialize (single call)
const init = await session_init({
  agent_name: "claude",
  task: "Add rate limiting to API",
});
// Check init.pendingHandoffs for any waiting tasks
 
// 2. Explore
const apiFiles = await explore({ action: "context", room: "api" });
const rateLimitCode = await explore({
  action: "search",
  query: "rate limiting middleware",
});
 
// 3. Recall Knowledge
const learnings = await recall({ action: "query", query: "rate limiting" });
const decisions = await recall({
  action: "query",
  type: "decisions",
  query: "api security",
  status: "active",
});
const failures = await postmortem({ action: "list", severity: "high" });
 
// 4. Get File Context
const ctx = await file_context({ file_path: "api/middleware/rateLimit.ts" });
 
// 5. Check Conflicts
await session({ action: "conflict", path: "api/middleware/rateLimit.ts" });
 
// 6. Make Changes
// [Edit file with full context]
 
// 7. Log Activity
await session({
  action: "log",
  activity: "file_edit",
  path: "api/middleware/rateLimit.ts",
  description: "Implemented token bucket rate limiting",
});
 
// 8. Store Knowledge
await store({
  content:
    "Use token bucket algorithm for API rate limiting - allows bursts while maintaining average rate",
  as: "decision",
  scope: "room",
  scopePath: "api",
  rationale: "More flexible than fixed window, prevents thundering herd",
});
 
await store({
  content:
    "Rate limit counters should use Redis with TTL, not in-memory - enables multi-instance deployment",
  as: "learning",
  scope: "file",
  scopePath: "api/middleware/rateLimit.ts",
});
 
// 9. End Session
await session({
  action: "end",
  outcome: "success",
  summary: "Implemented token bucket rate limiting with Redis backend",
});