Quick Start

Get Awareness running with your IDE agent in under 2 minutes.

Fastest Way: Local Mode (No Account Needed)

npx @awareness-sdk/setup

That's it. Works with Claude Code, Cursor, Windsurf, Cline, GitHub Copilot, and 8 more IDEs. No account, no cloud, no API key needed.

What happens: Starts a local daemon → auto-detects your IDE → writes workflow rules + MCP config → your agent now has persistent memory.

Web dashboard: Open http://localhost:37800 to browse memories, knowledge cards, and tasks.

Want cloud features? Run npx @awareness-sdk/setup --cloud anytime to add semantic search, team sync, and the memory marketplace.

Full Awareness Local documentation →

Cloud Mode: Full Features

Prerequisites

• An Awareness account (sign up at awareness.market)
• An IDE with MCP support (Cursor, Claude Code, Windsurf, Cline, VS Code GitHub Copilot, Kiro, Trae, JetBrains, Zed, or OpenCode)

Step 1: Create a Memory

A Memory is a persistent container that stores all knowledge, decisions, and context 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="https://awareness.market/api/v1")
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

Choose the method that works best for you. We recommend Method A for the fastest setup.

Method A: One-Command Setup (Recommended)

Run this in your project root — it handles login, memory selection, and IDE configuration all at once:

npx @awareness-sdk/setup

What happens:

1. Log in — opens your browser for one-click authentication (credentials saved to ~/.awareness/credentials.json)
2. Pick memory — select an existing memory or create a new one via the wizard
3. Configure IDE — auto-detects your IDE, writes workflow rules + MCP config

The CLI supports 12 IDEs: Cursor, Claude Code, Windsurf, Cline, VS Code Copilot, Codex, Kiro, Trae, JetBrains (Junie), Zed, Augment, and Google AntiGravity. Re-running the command safely upgrades existing rules in place.

Common options:

npx @awareness-sdk/setup --ide cursor    # Force a specific IDE
npx @awareness-sdk/setup --no-auth       # Rules only, skip login (no MCP config)
npx @awareness-sdk/setup --logout        # Clear saved credentials
npx @awareness-sdk/setup --dry-run       # Preview changes without writing
npx @awareness-sdk/setup --list          # Show all supported IDEs
npx @awareness-sdk/setup --api-base <url> # Use a custom API base URL

If you already have an API key and memory ID, you can skip the interactive login:

npx @awareness-sdk/setup --api-key aw_xxx --memory-id mem_xxx

Method B: One-Click Connect Prompt (Best for MCP + Rules)

Why not just paste MCP JSON? Awareness is more than a standard MCP server — it includes workflow rules that teach your IDE agent when and how to use memory proactively (auto-init at session start, auto-recall before decisions, auto-record after changes). The Connect prompt sets up both MCP config and these behavioral rules in one step.

Open your memory's detail page in the Awareness dashboard, click Connect, and copy the one-click install prompt for your IDE.

What the Connect prompt does:

1. Reads your IDE's current config file
2. Adds or updates the awareness-memory MCP server with your credentials pre-filled
3. Injects Awareness workflow rules into the appropriate rules file (e.g., CLAUDE.md, .cursor/rules/awareness.mdc)
4. Verifies the setup by running a test command

Supported one-click prompts:

Method C: Manual MCP Configuration

If you prefer full control, add the MCP server JSON to your IDE config manually:

{
  "mcpServers": {
    "awareness-memory": {
      "url": "https://awareness.market/mcp",
      "headers": {
        "Authorization": "Bearer $AWARENESS_API_KEY",
        "X-Awareness-Memory-Id": "$YOUR_MEMORY_ID",
        "X-Awareness-Agent-Role": "builder_agent"
      }
    }
  }
}

Replace the placeholder variables:

• $AWARENESS_API_KEY — The API key from Step 2
• $YOUR_MEMORY_ID — The memory ID from Step 1

Important: Manual config gives you MCP tools only. To get the full proactive memory experience (auto-init, auto-recall, auto-record workflow), you will also need to add Awareness rules to your IDE's rules file. Use Method A or B to get rules automatically, or see the IDE Plugins guide for manual rules setup.

IDE config file locations:

Fastest path by tool

Step 4: Write Your First Memory

Once your IDE is connected via MCP, the agent will automatically write memories during your sessions — no manual calls needed. The workflow rules injected in Step 3 teach the agent to:

1. Initialize at session start (awareness_init)
2. Recall past context before making decisions (awareness_recall)
3. Record important steps, decisions, and outcomes (awareness_record)
4. Extract insights — your LLM extracts structured knowledge cards from recorded events

You can also integrate memory into your own app or agent code using the Interceptor pattern — wrap your existing LLM client and memory flows happen automatically:

Python — Interceptor (Recommended)

from memory_cloud import MemoryCloudClient, AwarenessInterceptor
import openai

client = MemoryCloudClient(
    api_key="$AWARENESS_API_KEY",
    base_url="https://awareness.market/api/v1",
)
interceptor = AwarenessInterceptor(
    client=client,
    memory_id="$YOUR_MEMORY_ID",
)

oai = openai.OpenAI()
interceptor.wrap_openai(oai)

# Now every LLM call automatically recalls relevant memory
# and stores the conversation back — zero changes to your business logic
response = oai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What auth approach did we decide on?"}]
)

TypeScript — Interceptor (Recommended)

import { MemoryCloudClient, AwarenessInterceptor } from "@awareness-sdk/memory-cloud";
import OpenAI from "openai";

const client = new MemoryCloudClient({
  apiKey: "$AWARENESS_API_KEY",
  baseUrl: "https://awareness.market/api/v1",
});
const interceptor = await AwarenessInterceptor.create({
  client,
  memoryId: "$YOUR_MEMORY_ID",
});

const oai = new OpenAI();
interceptor.wrapOpenAI(oai);

// All LLM calls now have memory injection automatically
const response = await oai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "What auth approach did we decide on?" }],
});

Want more control? See the SDK Usage Guide for interceptor options (relevance threshold, query rewrite modes, auto-extraction) and explicit API methods like recallForTask / record.

What Happens Next?

Once connected with workflow rules, your IDE agent will proactively:

1. Initialize — Call awareness_init at session start to load context, knowledge cards, and open tasks
2. Recall — Search past knowledge before making decisions using hybrid semantic + keyword search
3. Record — Save important steps, decisions, and outcomes with structured context
4. Extract insights — Client-side LLM extracts structured knowledge cards (decisions, solutions, workflows, pitfalls, and more)
5. Detect conflicts — Automatically identify contradictions and supersede outdated knowledge

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

Plugin Overview

Claude Code Plugin

/plugin marketplace add edwin-hao-ai/Awareness-SDK
/plugin install awareness-memory@awareness

Available slash commands:

OpenClaw Plugin

# Plugin (full integration):
# The extra flags bypass OpenClaw 2026.4+'s plugin security scanner,
# which flags child_process + env-read as "dangerous" even though both
# are legitimate features (local daemon auto-start + API key handling).
# See: https://github.com/openclaw/openclaw/issues/11030
openclaw plugins install @awareness-sdk/openclaw-memory@latest \
  --force \
  --dangerously-force-unsafe-install

# Or Skill (via ClawHub):
npx clawhub@latest install awareness-memory

Current public tool set: awareness_init, awareness_recall, awareness_lookup, awareness_record

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

Agent not using memory proactively?

• Ensure workflow rules are installed (not just MCP config)
• Use Method A or B in Step 3 to get rules automatically
• Check your IDE's rules file for the AWARENESS_RULES block