MCP Tools Reference

Awareness exposes 6 MCP tools that any AI agent (Claude, GPT, Cursor, etc.) can call over the MCP protocol. This page is the complete reference.

Quick Overview

Recommended Workflow

The __awareness_workflow__ meta-tool contains a persistent workflow guide visible in every tool listing. Follow these steps:

1. awareness_init(source="claude-code")              ← load state + get session_id (ALWAYS first)
2. awareness_recall(semantic_query=..., keyword_query=...)  ← search past context before working
3. awareness_record(action="remember", text=...)       ← after EVERY code edit, decision, bug fix
4. If _extraction_instruction returned → process → submit_insights
5. awareness_record(action="remember_batch", steps=[...])   ← session-end summary

Tool Reference

awareness_init

Initialize a new session and load full cross-session persistent memory context. MUST call ONCE at session start, BEFORE any other memory tool.

Returns session_id (pass to all subsequent awareness_record calls), recent narratives, open tasks, and top knowledge cards.

Returns: { session_id, context: { recent_days, open_tasks, knowledge_cards }, agent_profiles: [{ agent_role, title, when_to_use }], active_skills?: [{ title, summary, methods }] }

• active_skills — reusable skill prompts pre-loaded from this memory and any installed memories. When present, apply each skill's summary as behavioral guidance and follow its methods steps. Skills are delivered at session start so no extra awareness_recall call is needed for known procedures.

Note: agent_profiles contains only lightweight summaries (no activation_prompt). Use awareness_get_agent_prompt to fetch the full prompt when spawning a sub-agent.

awareness_get_agent_prompt

Fetch the full activation prompt for a specific agent role. Use this immediately before spawning a sub-agent so the main agent context stays clean.

Sub-agent spawning workflow:

1. awareness_init() → agent_profiles: [{ agent_role, title, when_to_use }, ...]
2. Identify which role matches the task
3. awareness_get_agent_prompt(agent_role="developer_agent")
   → { activation_prompt: "# Developer Agent\n...\n## Memory Integration\n..." }
4. Spawn sub-agent with activation_prompt as its system prompt
5. Sub-agent calls awareness_recall/record with agent_role="developer_agent"

Returns: { agent_role, title, activation_prompt, system_prompt }

Error responses:

• { "error": "agent_role is required." } — empty agent_role
• { "error": "Agent role '<role>' not found in memory <id>." } — role does not exist
• { "error": "Authentication required..." } — missing API key

awareness_recall

Search cross-session persistent memory for relevant context. Primary mid-session read tool.

RETRIEVAL NECESSITY — do NOT call for:

• Simple greetings, acknowledgments, or generic knowledge questions
• Questions answerable from the current conversation alone
• If unsure, call it — false positive is better than missing context

BEFORE CALLING — rewrite the query:

1. SEMANTIC_QUERY: Expand into full natural-language question with context.
   • Example: user says "auth bug" → "authentication bug in login flow, JWT token handling, session management, and OAuth integration"
2. KEYWORD_QUERY: Extract 2–5 precise terms for full-text matching. Use exact identifiers.
   • Example: "auth.py JWT session_cookies OAuth2 login"
3. SCOPE: Choose the right layer to search.
4. WEIGHTS: Factual → vector_weight=0.8; Keyword-heavy → vector_weight=0.5

Recall modes:

Cards in structured/hybrid are split by evidence confidence into verified and unverified tiers.

Scope layers:

awareness_lookup

Get structured data from cross-session persistent memory — no vector search, pure DB lookup (<50ms).

Type reference:

awareness_record

Write to cross-session persistent memory. Handles all write operations.

Action reference:

remember — Store a single event

Call after each significant step: architecture decision, code change, bug fix, test result.

TEXT QUALITY: Include ALL of: WHAT happened · WHY it matters · OUTCOME · FILES affected.

Good examples:

"Decision: Switched auth from JWT to session cookies. Reason: simpler refresh logic.
 Affected: backend/auth.py, frontend/lib/auth.ts."

"Bug fixed: Memory leak in background worker caused by unclosed DB connections.
 Fix: added finally block in server/awareness/tasks.py line 89."

Bad examples: "Updated auth" / "Fixed bug" / "Tests pass" (too vague)

remember_batch — Store multiple events at once

Use for session-end summaries or history import (not periodic checkpoints — use remember after each change instead).

{
  "action": "remember_batch",
  "steps": [
    {"text": "Session summary: Added user authentication with JWT tokens"},
    {"text": "Files changed: auth.py, middleware.py, login.tsx"},
    {"text": "Decisions: Chose bcrypt over argon2 for password hashing (wider library support)"},
    {"text": "TODO: Add rate limiting to login endpoint"}
  ]
}

backfill — Import conversation history

Use when MCP is connected late and prior chat exists.

ingest — Import external content

Use for uploading documents, specs, or knowledge base content. Set content_scope="knowledge" to store in the knowledge layer (separate from timeline events).

update_task — Update task status

Requires task_id (from awareness_lookup(type="tasks")) and status.

submit_insights — Submit pre-extracted insights

Submit insights extracted by your LLM. Every awareness_record(action="remember") call may return an _extraction_instruction in the response — process it with your LLM and submit the extracted JSON result via this action. The server handles dedup, conflict resolution, and evidence scoring automatically.

Insight Auto-Extraction

The system extracts structured insights from your written events using your LLM (zero server-side LLM cost):

1. Every awareness_record call can return an _extraction_instruction in the response
2. Process the instruction with your LLM and call awareness_record(action="submit_insights") with the JSON result
3. The server automatically handles deduplication, conflict detection, and evidence scoring

Categories auto-extracted (13 total):

Engineering categories (for technical/work content):

• decision — A choice was made between alternatives
• workflow — A process, setup, or configuration described
• problem_solution — A specific bug/error was identified AND fixed
• pitfall — A trap, gotcha, or limitation discovered
• insight — A reusable pattern or learning
• skill — A reusable procedure done 2+ times; summary = injectable instruction prompt, methods = numbered execution steps. Delivered via active_skills at every session start — no recall needed.
• key_point — Important technical fact or architecture detail

Personal categories (for user-specific information):

• personal_preference, important_detail, plan_intention, activity_preference, health_info, career_info, custom_misc

The extraction prompt uses a step-by-step decision tree for accurate classification. Categories are assigned automatically based on content — no manual categorization needed.

Status detection:

• Events mentioning BLOCKED, TODO, or need to are automatically marked as open
• Completed work is marked as resolved
• Work in progress is marked as in_progress
• Observations without action are marked as noted

Write clearly so the extraction system can identify these patterns.

IDE Rules Auto-Injection

When you call awareness_init with a recognized source (e.g. "claude-code", "cursor", "copilot", "codex"), the response includes an ide_rules object in setup_hints:

{
  "setup_hints": {
    "ide_rules": {
      "ide": "claude-code",
      "rules_file": "CLAUDE.md",
      "rules_content": "...",
      "strategy": "managed_block",
      "start_marker": "<!-- AWARENESS_RULES_START -->",
      "end_marker": "<!-- AWARENESS_RULES_END -->",
      "conflict_policy": "error_on_invalid_markers",
      "instruction": "Sync the Awareness managed block in 'CLAUDE.md'..."
    }
  }
}

The agent should use the structured contract to sync the managed rules safely:

• managed_block (CLAUDE.md, AGENTS.md, .windsurfrules, .clinerules, .github/copilot-instructions.md): create if missing, append when no markers exist, replace only the managed block when markers exist.
• managed_file (.cursor/rules/awareness.mdc): create if missing, replace the full file when markers exist, conflict on unmanaged existing files unless an explicit force mode is used.

Supported IDEs:

The marker pair (<!-- AWARENESS_RULES_START --> / <!-- AWARENESS_RULES_END -->) is used to upgrade existing managed rules instead of permanently skipping future syncs.

Alternative: CLI setup tool

For deterministic sync without relying on the MCP agent, run:

npx @awareness-sdk/setup              # auto-detect IDE
npx @awareness-sdk/setup --configure-mcp --ide copilot
                                       # prompt for MCP values interactively
npx @awareness-sdk/setup --ide cursor # force specific IDE
npx @awareness-sdk/setup --ide copilot # force VS Code Copilot
npx @awareness-sdk/setup --ide copilot --mcp-url https://awareness.market/mcp --api-key aw_xxx --memory-id mem_xxx
                                       # also create/merge the MCP config file
npx @awareness-sdk/setup --dry-run    # preview without writing
npx @awareness-sdk/setup --force      # allow Cursor managed_file takeover