mcp-awareness

<!-- SPDX-License-Identifier: AGPL-3.0-or-later | Copyright (C) 2026 Chris Means --> <p align="center"> <img src="docs/branding/awareness-logo-wordmark.svg" alt="awareness" width="400"> </p> <p align="center"> <a href="https://github.com/cmeans/mcp-awareness/actions/workflows/ci.yml"><img src="https://github.com/cmeans/mcp-awareness/workflows/CI/badge.svg" alt="CI"></a> <a href="https://codecov.io/gh/cmeans/mcp-awareness"><img src="https://codecov.io/gh/cmeans/mcp-awareness/branch/main/graph/badge.svg" alt="codecov"></a> <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-blue" alt="License"></a> <a href="https://ghcr.io/cmeans/mcp-awareness"><img src="https://img.shields.io/badge/docker-ghcr.io-blue" alt="Docker"></a> </p>

Your AI's memory shouldn't be locked to one app. It should follow you everywhere.

[!NOTE] Early-stage but actively deployed — 17 releases, in daily use across Claude.ai, Claude Code, and Claude Desktop. See Current status for what's working and what's planned.

What this is

mcp-awareness is shared memory for every AI you use. Any AI assistant can store and retrieve knowledge through it using the open Model Context Protocol (MCP). Self-host it today, or use the managed service when it launches. It works with any MCP-compatible client — Claude (all platforms), Cursor, VS Code, and more.

The problem: Every AI platform keeps its own memory silo. What you teach Claude doesn't exist in ChatGPT. Your desktop assistant's context doesn't follow you to mobile. Switch platforms, and you start over.

The fix: Externalize that knowledge into a service you control. Tell one AI about your infrastructure, your projects, your preferences — and every AI knows it. Permanently, portably, privately.

What this looks like in practice

<img src="docs/images/android-briefing-demo.png" alt="Claude on Android surfacing an awareness briefing" width="220" align="right">

This morning, you drafted a plan with Claude on your phone during a commute. Back at your desk, Claude Desktop already had the context — you refined the engineering approach together. You moved to Claude Code for implementation and deployment, updating shared project status so every platform knows what happened. No copy-paste. No "remember what we discussed." The knowledge just follows you.

Tell one AI about your infrastructure, your preferences, or a design decision — and every AI knows it. Correct a mistake on your phone, and your desktop assistant never repeats it. That cross-platform continuity works today.

The store also provides ambient awareness: a collation engine applies learned patterns and suppressions, and your AI receives a compact briefing (~200 tokens) at the start of each conversation. If something needs attention, it says so. If not, silence — and that silence is the product.

<br clear="both">

How it started

What started as a homelab monitoring experiment turned into a portable knowledge layer for your entire life. The original LinkedIn post tells the origin story.

<details> <summary>The full origin story</summary>

This project began with a single memory instruction in Claude.ai:

"On the first turn of each conversation, call synology-admin:get_resource_usage. If CPU > 90%, RAM > 85%, any disk > 90% busy, or network/disk I/O looks abnormally high, briefly mention it as an FYI before responding."

That worked surprisingly well. Infrastructure awareness surfaced inline during unrelated conversations. The AI applied contextual judgment — it knew the NAS was a seedbox, so it didn't flag normal seeding activity. Conversational tuning worked too: "don't bug me until it's 97%" adjusted behavior immediately.

But it had obvious limits. Diagnostics weren't captured at detection time. There was no structural detection — if a key process stopped, every metric looked better, and nothing alerted. Knowledge lived in platform-locked memory. It only worked with one system, on one platform.

</details>

Today it's a portable knowledge store that tracks personal facts, project history, design decisions, and intentions alongside infrastructure monitoring. As edge providers come online, it will extend to calendars, location, health, and more — but the core store and cross-platform continuity work now.

Core capabilities

Shared knowledge store

Any AI can write knowledge. Any AI can read it. Knowledge accumulates through conversation, not configuration:

• remember — store permanent knowledge (still true in 30 days?): personal facts, project notes, design decisions
• add_context — store temporal knowledge that auto-expires (happening now, will become stale?)
• learn_pattern — record if/then rules for alert matching (when X happens, expect Y)
• update_entry — modify entries in place with automatic changelog tracking
• get_knowledge — retrieve by source, tags, or entry type with optional change history

This is the key differentiator from platform-specific memory: the knowledge belongs to you, not to Claude, ChatGPT, or any single tool.

Cross-platform continuity

Every AI you use shares the same knowledge base. Plan on your phone, implement on your laptop, review from your desktop — context follows automatically. Your AIs can also maintain shared project status, so any platform knows what's been done and what's next.

Intentions — todos that manage themselves

Create a todo, reminder, or planned action from any platform. Intentions have a lifecycle — pending → fired → active → completed — and agents advance them through conversation. Time-based intentions fire automatically at deliver_at timestamps. As signal sources come online (GPS, calendar), intentions will also fire based on location and context.

Knowledge that outlives you

Over time, your awareness store becomes a living estate document — financial accounts, insurance details, medical info, system access, family contacts. Not because you sat down to write a manual, but because you asked your AI to remember important details as you mentioned them. If you weren't here tomorrow, someone could find what they need.

Ambient awareness

Your AI receives a compact briefing (~200 tokens) at the start of each conversation. The collation engine applies learned patterns and active suppressions, then decides what to surface. If something needs attention, it mentions it. Otherwise, silence — and that silence is the product, confirming that everything was checked and nothing needs you.

For infrastructure monitoring, three layers of detection apply:

| Layer | Question | Catches | |-------|----------|---------| | Threshold | "Is this number too high?" | CPU > 90%, disk > 95% full | | Baseline | "Is this abnormal for THIS system?" | Deviation from rolling average | | Knowledge | "Does this match what I expect?" | Process stopped, replication stalled, unexpected quiet |

The third layer is where the value is. Knowledge accumulates through conversation, not YAML.

Safe data management

Soft delete with 30-day trash retention. Bulk deletes show a dry-run count and require confirmation before committing. Restore from trash at any time. In-place updates track all changes in a changelog. No data is permanently destroyed without a retention period.

Store introspection

get_stats shows entry counts by type and lists all sources — so your AI can decide whether to pull everything or filter first. get_tags lists all tags with usage counts, preventing tag drift across platforms (e.g., one AI tagging "infrastructure" while another uses "infra").

Architecture

flowchart TB
    subgraph Clients["Any MCP Client"]
        A1["Claude.ai"]
        A2["Claude Code"]
        A3["Claude Desktop"]
        A4["Cursor / VS Code / ..."]
    end

    subgraph Security["Cloudflare Edge"]
        WAF["WAF (path filter)"]
        TLS["TLS + Tunnel"]
    end

    subgraph Signals["Signal Sources (planned)"]
        direction TB
        S1["📅 Calendar"]
        S2["📍 GPS / Location"]
        S3["💬 SMS / Messaging"]
        S4["🏠 Home Assistant"]
        S5["🖥️ NAS / Docker / CI"]
    end

    subgraph Server["mcp-awareness"]
        direction LR
        Store["Store\n(Postgres + pgvector)"]
        Collator["Collator\n• patterns\n• suppressions\n• intentions"]
        Briefing["Briefing\n~200 tokens"]
        Store --> Collator --> Briefing
    end

    Clients <-- "MCP\n(stdio or HTTPS)" --> Security
    Security <--> Server
    Signals -- "remember\nadd_context\nremind" --> Server

Quick start

Try the demo (easiest)

One script, three containers, a public URL. No account needed.

curl -sSL https://raw.githubusercontent.com/cmeans/mcp-awareness/main/install-demo.sh | bash

Prefer to review the script first? View it on GitHub, then download and run locally.

This starts the Awareness server, Postgres, and a Cloudflare quick tunnel. You'll get a public URL and ready-to-paste config snippets for all major MCP clients. The instance comes pre-loaded with demo data — your AI will discover it automatically.

Note: The tunnel URL is ephemeral — it changes on restart. For a stable URL, see the Deployment Guide.

Model matters: Best experience with Claude Sonnet 4.6 or Opus 4.6. Smaller models (Haiku, GPT-4o-mini) may not follow MCP prompts reliably.

Local development

git clone https://github.com/cmeans/mcp-awareness.git
cd mcp-awareness
docker compose up -d

The server is running on port 8420. Point any MCP client at http://localhost:8420/mcp.

Connect your AI

Claude Desktop / Claude Code (local):

{
  "mcpServers": {
    "awareness": {
      "url": "http://localhost:8420/mcp"
    }
  }
}

Claude.ai (remote, requires Deployment Guide setup):

1. Settings → Connectors → Add custom connector
2. Name: awareness
3. URL: https://your-domain.com/your-secret/mcp
4. Leave OAuth fields blank

Configuration

Server

| Variable | Default | Description | |----------|---------|-------------| | AWARENESS_TRANSPORT | stdio | Transport: stdio or streamable-http | | AWARENESS_HOST | 0.0.0.0 | Bind address (HTTP mode) | | AWARENESS_PORT | 8420 | Port (HTTP mode) | | AWARENESS_DATABASE_URL | (required) | PostgreSQL connection string. Accepts URL format (postgresql://user:pass@host:5432/db) or psycopg DSN format (host=X dbname=Y user=Z password=W). If using DSN format in an env file, quote the value — unquoted spaces cause the shell to split it into separate assignments. Example: AWARENESS_DATABASE_URL="host=db dbname=awareness user=awareness password=secret" | | AWARENESS_MOUNT_PATH | (none) | Secret path prefix for access control (e.g., /my-secret). When set, only /<secret>/mcp is served; all other paths return 404. Use with a Cloudflare WAF rule. |

Embedding (optional)

| Variable | Default | Description | |----------|---------|-------------| | AWARENESS_EMBEDDING_PROVIDER | (none) | Set to ollama to enable the vector branch of hybrid search. Without it, search uses FTS only and backfill_embeddings is unavailable. | | AWARENESS_EMBEDDING_MODEL | granite-embedding:278m | Ollama model name for embeddings. Must match the model pulled in the Ollama container. | | AWARENESS_OLLAMA_URL | http://ollama:11434 | Ollama API endpoint. Default works with Docker Compose; change for external Ollama instances. | | AWARENESS_EMBEDDING_DIMENSIONS | 768 | Vector dimensions. Must