Awareness Local

What Awareness Local MCP server does

Awareness Local MCP server provides persistent memory for AI coding agents working across multiple sessions. It can preserve architecture notes, implementation decisions, pending tasks, coding preferences, risks, and other project context so an agent does not need the same background explanation each time. The local mode is designed for offline use and does not require an account.

Memory is saved as Markdown files under .awareness/. A local SQLite index supports retrieval, while knowledge-card extraction organizes recorded decisions, solutions, and risks. Optional cloud sync is available later, but it is not required for local operation.

The project reports a 96.0% Recall@5 result on the LongMemEval benchmark. That result describes its hybrid retrieval evaluation and should be treated as a benchmark figure rather than a guarantee for every project or dataset.

How it works

A lightweight daemon runs on the developer’s machine and exposes the memory functions over MCP. Retrieval combines keyword matching with semantic embeddings. The README identifies SQLite FTS5 and embeddings as the indexing components, and describes the retrieval method as hybrid RRF using BM25 and vector search.

The daemon retrieval path makes zero LLM calls. This keeps recall local and avoids generation-related API costs for searches. Agents can first receive a compact result and then request more detail, following the progressive-disclosure behavior described for memory recall.

Setup and configuration

Run the setup command from a terminal:

npx @awareness.market/setup

After setup, open an MCP-compatible IDE and use the available memory tools. No environment variables or cloud credentials are documented as required. Local data remains on the machine in the .awareness/ directory. Cloud synchronization is optional.

The README also documents a local Streamable HTTP endpoint for ChatGPT Desktop: http://127.0.0.1:37800/mcp. It specifies that the local daemon endpoint does not require authentication.

Tools and capabilities

The Awareness Local MCP server exposes these tools:

• awareness_init loads recent knowledge, tasks, and rules for a session.
• awareness_recall searches stored memories and supports summary-to-full-detail retrieval.
• awareness_record saves decisions, code changes, and insights, with knowledge extraction.
• awareness_lookup provides fast access to tasks, knowledge cards, session history, and risks.
• awareness_get_agent_prompt returns agent-specific prompts for multi-agent configurations.

These capabilities fit long-running migrations, team handoffs, personal coding conventions, and multi-agent workflows that share task or decision history.

Limitations and notes

The README establishes support for MCP-compatible IDEs, including Cursor, Claude Code, Copilot, Cline, and Windsurf. It does not describe a separate authentication model for local mode, because local operation does not require an account. Cloud sync is optional rather than part of the required local setup.

The benchmark measures memory retrieval, not general coding quality. The documented evaluation used 500 questions and reported Recall@1 of 80.2%, Recall@3 of 92.8%, Recall@5 of 96.0%, and Recall@10 of 98.6%.