MCP Tools Reference

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

Note: Awareness is not just an MCP server — it ships with workflow rules that teach your IDE agent to use memory proactively (auto-init, auto-recall, auto-record). See the Quick Start for setup instructions that include both MCP config and behavioral rules.

Quick Overview

Recommended Workflow

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(content="WHAT/WHY/OUTCOME")   ← after EVERY code edit, decision, bug fix
4. awareness_record(content=[step1, step2, ...])   ← session-end batch summary

Tool Reference

awareness_init

Call ONCE at session start. Returns session_id, recent narratives, open tasks, and top knowledge cards.

Essential parameters:

Response highlights:

{
  "session_id": "abc-123",
  "context": {
    "recent_days": [{ "date": "2026-03-15", "narrative": "..." }],
    "open_tasks": [{ "id": "...", "title": "...", "priority": "high" }],
    "knowledge_cards": [{ "id": "...", "category": "decision", "title": "..." }],
    "synthesized_rules": { "rules": ["..."] }
  },
  "agent_profiles": [{ "agent_role": "developer_agent", "title": "Developer" }],
  "active_skills": [{ "title": "Code Review", "summary": "...", "methods": ["Step 1..."] }]
}

• session_id — pass to all subsequent awareness_record calls.
• active_skills — reusable skill prompts pre-loaded at session start. No extra recall needed for known procedures.
• synthesized_rules — behavioral rules auto-generated from accumulated knowledge cards.
• _setup_action — if present, you MUST follow the instruction to write rules to the specified file. This enables persistent memory for all future sessions.

agent_profiles contains only lightweight summaries. 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 immediately before spawning a sub-agent.

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: "..." }
4. Spawn sub-agent with activation_prompt as its system prompt

Returns: { agent_role, title, activation_prompt, system_prompt }

awareness_recall

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

Before calling — rewrite the query:

1. SEMANTIC_QUERY: Expand into a full natural-language question with context.
   • "auth bug" → "authentication bug in login flow, JWT token handling, session management"
2. KEYWORD_QUERY: Extract 2–5 precise terms for full-text matching.
   • "auth.py JWT session_cookies OAuth2 login"

Essential parameters:

Recall modes:

Scope layers:

awareness_lookup

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

Essential parameters:

Type reference:

awareness_record

Write to memory. Handles all write operations.

Essential parameters:

Usage patterns:

Store a single event

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

Content quality: Include ALL of: WHAT happened · WHY it matters · OUTCOME · FILES affected.

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

Store multiple events (batch)

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

Ingest external content

Set content_scope="knowledge" to store documents/specs in the knowledge layer (separate from timeline events).

Update task status

Use action="update_task" with task_id (from awareness_lookup(type="tasks")) and status.

Advanced Topics

Insight Extraction

When you pass content to awareness_record, the system can automatically extract structured insights — knowledge cards, action items, risks, and entity relationships.

Recommended: Pass insights directly in your awareness_record call to process events and insights in a single call.

Alternative: If you don't pass insights, the response may include an _extraction_instruction. Process it with your LLM, then call awareness_record(insights=<result>). The server handles deduplication, conflict detection, and evidence scoring automatically.

14 auto-detected categories:

The system also auto-detects status (open, resolved, in_progress, noted) and performs conflict detection against existing knowledge cards (new, update, duplicate, contradiction).

IDE Rules Auto-Injection

When awareness_init is called with a recognized source, the response includes setup_hints.ide_rules — a structured contract for syncing workflow rules to the IDE's rules file.

Supported IDEs:

Alternative: For deterministic sync without MCP, run:

npx @awareness-sdk/setup              # auto-detect IDE
npx @awareness-sdk/setup --ide cursor # force specific IDE