﻿# Quick Start

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

## Fastest Way: Local Mode (No Account Needed)

```bash
npx @awareness.market/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](http://localhost:37800) to browse memories, knowledge cards, and tasks.

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

[Full Awareness Local documentation →](AWARENESS_LOCAL.md)

---

## Cloud Mode: Full Features

### Prerequisites

- An Awareness account (sign up at [awareness.market](https://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

```python
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:

```bash
npx @awareness.market/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:**

```bash
npx @awareness.market/setup --ide cursor    # Force a specific IDE
npx @awareness.market/setup --no-auth       # Rules only, skip login (no MCP config)
npx @awareness.market/setup --logout        # Clear saved credentials
npx @awareness.market/setup --dry-run       # Preview changes without writing
npx @awareness.market/setup --list          # Show all supported IDEs
npx @awareness.market/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:

```bash
npx @awareness.market/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:**

| IDE | Config Target | Rules File |
|-----|--------------|------------|
| Claude Code | `.mcp.json` | `CLAUDE.md` |
| Cursor | `.cursor/mcp.json` | `.cursor/rules/awareness.mdc` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` | `.windsurfrules` |
| Cline | Cline Settings UI | `.clinerules` |
| VS Code Copilot | `.vscode/mcp.json` | `.github/copilot-instructions.md` |
| OpenClaw | `~/.openclaw/openclaw.json` | Plugin config |

### Method C: Manual MCP Configuration

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

```json
{
  "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](IDE_PLUGINS.md) guide for manual rules setup.

**IDE config file locations:**

| IDE | MCP Config File |
|-----|----------------|
| Cursor | `.cursor/mcp.json` |
| Claude Code | `.mcp.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| VS Code Copilot | `.vscode/mcp.json` |
| Cline | Cline MCP Settings UI |
| Zed | `~/.config/zed/settings.json` (under `context_servers`) |

### Fastest path by tool

| Tool | Fastest path |
|------|-------------|
| Cursor / Windsurf / Cline / Copilot | `npx @awareness.market/setup` |
| Claude Code | Connect one-click prompt or `npx @awareness.market/setup` |
| Claude Code Plugin | `/plugin marketplace add everest-an/Awareness-SDK` then `/plugin install awareness-memory@awareness` (adds slash commands on top of MCP) |
| OpenClaw | Connect one-click prompt |
| Kiro / Trae / JetBrains | `npx @awareness.market/setup` |
| Zed | `npx @awareness.market/setup` or manual config |
| Devin | SDK / rule-file bootstrap |
| Antigravity / Augment | Connect prompt or `npx @awareness.market/setup` |
| Python / TypeScript SDK | SDK install + interceptor pattern (see [SDK Usage](SDK_USAGE.md)) |

---

## 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)

```python
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)

```typescript
import { MemoryCloudClient, AwarenessInterceptor } from "@awareness.market/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](SDK_USAGE.md) 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](CORE_CONCEPTS.md) to understand the full architecture, or browse the [MCP Tools Reference](MCP_TOOLS_REFERENCE.md) for all available tools.

---

## Plugin Overview

### Claude Code Plugin

```bash
/plugin marketplace add everest-an/Awareness-SDK
/plugin install awareness-memory@awareness
```

Available slash commands:

| Skill | Command | Use it when |
|-------|---------|-------------|
| `session-start` | `/awareness-memory:session-start` | Start a new coding session |
| `recall` | `/awareness-memory:recall <query>` | Check prior work before coding |
| `save` | `/awareness-memory:save` | Persist an important intermediate step |
| `done` | `/awareness-memory:done` | End a session with a summary |

### OpenClaw Plugin

```bash
# 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.market/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](../mcp) 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
