Quick Start

Get Awareness running with your IDE agent in 5 minutes.

Prerequisites

• An Awareness account (sign up at your instance URL)
• An IDE with MCP support (Cursor, Claude Code, Windsurf, Cline, VS Code GitHub Copilot, or OpenCode)

Step 1: Create a Memory

A Memory is a container that stores all knowledge for a project or workspace.

Option A: Dashboard UI

1. Log in to Awareness
2. Click Memories in the sidebar
3. Click Create Memory
4. Enter a name (e.g., my-project) and click Create

Option B: Python SDK

from memory_cloud import MemoryCloudClient

client = MemoryCloudClient(api_key="$AWARENESS_API_KEY", base_url="$AWARENESS_API_BASE")
memory = client.create_memory(name="my-project")
print(memory["id"])  # Save this ID

Save the returned id — you will need it in the next steps.

Step 2: Get Your API Key

1. Go to Settings in the sidebar
2. Under API Keys, click Generate New Key
3. Copy the key (starts with aw_)
4. Store it securely — you will not see it again

Step 3: Connect Your IDE

Add the following MCP server configuration to your IDE:

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "awareness-memory": {
      "url": "$AWARENESS_MCP_URL",
      "headers": {
        "Authorization": "Bearer $AWARENESS_API_KEY",
        "X-Awareness-Memory-Id": "$YOUR_MEMORY_ID",
        "X-Awareness-Agent-Role": "builder_agent"
      }
    }
  }
}

Claude Code

Add to ~/.claude/settings.json or your project-level .claude/settings.json:

{
  "mcpServers": {
    "awareness-memory": {
      "url": "$AWARENESS_MCP_URL",
      "headers": {
        "Authorization": "Bearer $AWARENESS_API_KEY",
        "X-Awareness-Memory-Id": "$YOUR_MEMORY_ID",
        "X-Awareness-Agent-Role": "builder_agent"
      }
    }
  }
}

Windsurf

Add to .windsurf/mcp.json:

{
  "mcpServers": {
    "awareness-memory": {
      "url": "$AWARENESS_MCP_URL",
      "headers": {
        "Authorization": "Bearer $AWARENESS_API_KEY",
        "X-Awareness-Memory-Id": "$YOUR_MEMORY_ID",
        "X-Awareness-Agent-Role": "builder_agent"
      }
    }
  }
}

VS Code GitHub Copilot

Add to .vscode/mcp.json:

{
  "mcpServers": {
    "awareness-memory": {
      "url": "$AWARENESS_MCP_URL",
      "headers": {
        "Authorization": "Bearer $AWARENESS_API_KEY",
        "X-Awareness-Memory-Id": "$YOUR_MEMORY_ID",
        "X-Awareness-Agent-Role": "builder_agent"
      }
    }
  }
}

Replace the placeholder variables:

• $AWARENESS_MCP_URL — Your MCP server URL (e.g., https://mcp.your-domain.com/mcp)
• $AWARENESS_API_KEY — The API key from Step 2
• $YOUR_MEMORY_ID — The memory ID from Step 1

Tip: Use the MCP Server page in the dashboard to auto-generate this config with your actual values filled in.

Recommended fastest path

Choose the shortest path based on your tool:

Faster setup options

• Claude Code: open the Claude Code page in Awareness and copy the one-click install prompt. It merges awareness-memory into your Claude config and verifies the setup with claude mcp list.
• OpenClaw: open the OpenClaw page in Awareness and copy the generated install prompt. It downloads the plugin, installs it, patches ~/.openclaw/openclaw.json, and verifies the plugin.
• Antigravity / Augment: use the same setup prompt pattern as Cursor or Windsurf. If the product build exposes MCP settings, paste the universal MCP config there. If not, keep the Awareness workflow in the repo rule file and use the SDK / REST path for explicit writes.
• Devin: bootstrap Awareness at the workspace or repo level. Keep the workflow visible in AGENTS.md or the repo instructions, and use the SDK / HTTP path for explicit writes when native MCP is unavailable.
• Claude Code plugin: if you want a higher-level Claude workflow, install:

claude plugin install awareness-memory

What the one-click prompts do

Claude Code one-click prompt

The Claude Code prompt will:

1. Read your current ~/.claude/settings.json
2. Add or update the awareness-memory MCP server
3. Ask for missing API Key and Memory ID
4. Run claude mcp list
5. Test the setup with awareness_init(source="claude-code")

OpenClaw one-click prompt

The OpenClaw prompt will:

1. Download @awareness-sdk/openclaw-memory
2. Install the plugin into OpenClaw
3. Update ~/.openclaw/openclaw.json
4. Apply apiKey, memoryId, baseUrl, and agentRole
5. Run openclaw plugins list to verify the plugin is loaded

Plugin overview

Claude Code plugin

claude plugin install awareness-memory

Available slash commands:

OpenClaw plugin

openclaw plugins install @awareness-sdk/openclaw-memory

Current public tool set:

• __awareness_workflow__
• awareness_init
• awareness_recall
• awareness_lookup
• awareness_record

Optional: Inject IDE Workflow Rules

Run this in your project root to sync Awareness workflow rules into your IDE config:

npx @awareness-sdk/setup

This auto-detects your IDE and syncs the managed rules file (e.g. CLAUDE.md for Claude Code, .cursor/rules/awareness.mdc for Cursor, .github/copilot-instructions.md for VS Code Copilot). Re-running the command upgrades existing managed rules in place. You can also specify the IDE explicitly:

npx @awareness-sdk/setup --configure-mcp --ide copilot
npx @awareness-sdk/setup --ide cursor
npx @awareness-sdk/setup --ide copilot
npx @awareness-sdk/setup --ide copilot --mcp-url https://awareness.market/mcp --api-key aw_xxx --memory-id mem_xxx
npx @awareness-sdk/setup --dry-run
npx @awareness-sdk/setup --force

Use --configure-mcp if you want the CLI to prompt for missing MCP values interactively instead of passing them all on the command line.

Step 4: Write Your First Memory

Once your IDE is connected via MCP, the agent will automatically write memories during your sessions. You can also write programmatically using the SDK:

Python SDK

from memory_cloud import MemoryCloudClient

client = MemoryCloudClient(
    api_key="$AWARENESS_API_KEY",
    base_url="$AWARENESS_API_BASE",
)

client.write(
    memory_id="$YOUR_MEMORY_ID",
    content="We decided to use JWT with refresh tokens, stored in httpOnly cookies.",
    agent_role="builder_agent",
)

TypeScript SDK

import { MemoryCloudClient } from "@awareness-sdk/memory-cloud";

const client = new MemoryCloudClient({
  apiKey: "$AWARENESS_API_KEY",
  baseUrl: "$AWARENESS_API_BASE",
});

await client.write({
  memoryId: "$YOUR_MEMORY_ID",
  content: "We decided to use JWT with refresh tokens, stored in httpOnly cookies.",
  agentRole: "builder_agent",
});

Step 5: Recall Your Memory

Your IDE agent will automatically recall relevant context via MCP. You can also query programmatically:

Python SDK

results = client.retrieve(
    memory_id="$YOUR_MEMORY_ID",
    query="authentication approach",
    limit=5,
)

for item in results:
    print(item["content"][:200])

TypeScript SDK

const results = await client.retrieve({
  memoryId: "$YOUR_MEMORY_ID",
  query: "authentication approach",
  limit: 5,
});

results.forEach((item) => console.log(item.content.slice(0, 200)));

What Happens Next?

Once connected, your IDE agent will automatically:

1. Initialize — Call awareness_init at session start to load context
2. Recall — Search past knowledge before making decisions
3. Record — Save important steps, decisions, and outcomes
4. Extract insights — Client-side LLM extracts structured knowledge cards

For OpenClaw specifically, the current tool set is:

• __awareness_workflow__
• awareness_init
• awareness_recall
• awareness_lookup
• awareness_record

See Core Concepts to understand the full architecture, or browse the MCP Tools Reference for all available tools.

Troubleshooting

"Unauthorized" error?

• Check that your API key is correct and not expired
• Ensure the Authorization: Bearer header is set

No results from recall?

• Make sure you wrote at least one event to the memory
• Try a broader query term
• Check that the memory_id matches

MCP not connecting?

• Verify the MCP URL is reachable from your machine
• Check IDE logs for connection errors
• Try the MCP Server page to test your config