Connect Awareness Memory to Your IDE

Configure Awareness Memory in local-first mode for Cursor. The local daemon runs on your machine — no cloud account, API key, or Memory ID needed. Follow these steps exactly:

## Step 0: Start Local Daemon

Run this in a terminal (if not already running):
```
npx @awareness-sdk/local start
```

## Step 1: Configure MCP Server

Read .cursor/mcp.json (create it if it doesn't exist with `{}`).
Merge the following into "mcpServers" (do NOT overwrite existing servers):
{
  "awareness-local": {
    "url": "http://localhost:37800/mcp",
    "headers": {
      "X-Awareness-Agent-Role": "builder_agent"
    }
  }
}
No API key or Memory ID needed for local mode.

## Step 2: Add Workflow Rules

Open .cursor/rules/awareness.mdc (create it if it doesn't exist).
Write the following content:

---
description: Awareness cross-session memory integration rules
globs: 
alwaysApply: true
---

<!-- AWARENESS_RULES_START -->
# Awareness Memory Rules

## Awareness Memory Integration (MANDATORY)

awareness_* = cross-session persistent memory (past decisions, knowledge, tasks).
Other tools = current codebase navigation (file search, code index).
Use BOTH - they serve different purposes.

STEP 1 - SESSION START:
  Call awareness_init(source="cursor") -> get session_id, review context.
  If active_skills[] is returned: skill = reusable procedure done 2+ times;
  summary = injectable instruction, methods = steps. Apply matching skills to tasks.

STEP 2 - RECALL BEFORE WORK (progressive disclosure):
  1. awareness_recall(semantic_query=..., keyword_query=..., detail='summary') → lightweight index.
  2. Review summaries/scores, pick relevant IDs.
  3. awareness_recall(detail='full', ids=[...]) → expand only what you need.

STEP 3 - RECORD EVERY CHANGE:
  After EVERY file edit, call awareness_record IMMEDIATELY. Do NOT batch — record each change as it happens.
  awareness_record(content=<detailed natural language description>,
    insights={knowledge_cards:[...], action_items:[...], risks:[...]})
  Content should be RICH and DETAILED — include reasoning, key code snippets,
  user quotes, alternatives considered, and files changed. Do NOT compress into
  a single-line summary. The content IS the memory — more detail = better recall.
  Include insights to create searchable knowledge in ONE step (recommended).
  Skipping = permanent data loss.

STEP 4 - CATEGORY GUIDE (for insights.knowledge_cards):
  Engineering:
  - decision = choice made between alternatives.
  - problem_solution = bug/problem plus the fix that resolved it.
  - workflow = process, setup, or configuration steps only.
  - pitfall = blocker, warning, or limitation without a fix yet.
  - insight = reusable pattern or general learning.
  - skill = reusable procedure done 2+ times; summary = injectable instruction, methods = steps.
  - key_point = important technical fact when nothing else fits.
  Personal (use when user shares preferences or personal info):
  - personal_preference = user's preferences, style, habits (e.g. 'I prefer dark mode', 'always use TypeScript').
  - important_detail = user's role, team, project context, relationships.
  - plan_intention = user's goals, plans, upcoming deadlines.
  - activity_preference = hobbies, interests, routines.
  - health_info = health-related notes shared by user.
  - career_info = job, skills, career goals.
  - custom_misc = anything personal that doesn't fit above.
  Never default everything to workflow.
  DO NOT record: greetings, confirmations, debug logs, news/search results, sender metadata, API keys/tokens/credentials, system bootstrap instructions, or trivial interactions.

STEP 5 - SESSION END:
  awareness_record(content=[step1, step2, ...], insights={...}) with final summary.

BACKFILL (if applicable):
  If MCP connected late: awareness_record(content=<transcript>)

If awareness_init returns rendered_context, inject it as system context verbatim — it contains pre-assembled memory relevant to this session.

RULES VERSION: Pass rules_version="3" to awareness_init so the server knows you have these rules.
If the server returns _setup_action, the rules have been updated — follow the instruction to re-sync.

NOTE: memory_id from X-Awareness-Memory-Id header. source/actor/event_type auto-inferred.

## Cursor-Specific Notes

- Call awareness_init at the start of EVERY new composer/chat session.

- When using Cursor's edit/apply features, record each apply as a awareness_record.

- The MCP server is configured in .cursor/mcp.json - memory_id is in the headers.
<!-- AWARENESS_RULES_END -->


## Step 3: Verify

- Confirm the MCP server config is in place
- Restart Cursor to activate the MCP connection
- All data stays on your machine as Markdown files