Awareness Local — Local-First Memory for AI Agents

One command. No account. Your data stays on your machine.

Overview

Awareness Local is the offline-first, privacy-first version of Awareness. It gives your AI agent persistent memory — decisions, preferences, pitfalls, knowledge — stored as plain Markdown files on your local disk.

• One command setup — npx @awareness-sdk/setup auto-detects your IDE and configures everything
• Works offline — no cloud account, no API key, no internet required
• 13+ IDE support — Claude Code, Cursor, Windsurf, VS Code Copilot, Cline, Kiro, Trae, JetBrains, Zed, OpenCode, and more
• Plain Markdown storage — human-readable, git-friendly, fully portable
• Optional cloud sync — upgrade to Awareness Cloud anytime for semantic search, cross-device sync, and team collaboration

Quick Start

npx @awareness-sdk/setup

What happens:

1. Auto-detects your IDE — scans for Claude Code, Cursor, Windsurf, VS Code, etc.
2. Starts the local daemon — launches a lightweight server on localhost:37800
3. Writes workflow rules — injects behavioral rules into your IDE config (e.g., CLAUDE.md, .cursor/rules/awareness.mdc) so your AI agent knows to use memory proactively
4. Writes MCP config — adds the Awareness MCP endpoint to your IDE's MCP settings

After setup, your AI agent will automatically:

• Load context at session start (awareness_init)
• Recall relevant memories before making decisions (awareness_recall)
• Record important outcomes after completing tasks (awareness_record)

How It Works

┌─────────────────────────────────────────────────────┐
│                    Your IDE                          │
│  (Claude Code / Cursor / Windsurf / VS Code / ...)  │
│                                                      │
│   Workflow Rules          MCP Protocol               │
│   (auto-init,            (tool calls)                │
│    auto-recall,               │                      │
│    auto-record)               │                      │
└───────────────────────────────┼──────────────────────┘
                                │
                     HTTP/SSE (localhost:37800)
                                │
┌───────────────────────────────┼──────────────────────┐
│              Awareness Local Daemon                   │
│                                                       │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────┐ │
│  │  MCP Server  │  │  Search      │  │  Knowledge  │ │
│  │  (5 tools)   │  │  Engine      │  │  Extraction │ │
│  └─────────────┘  │  (FTS5 +     │  └─────────────┘ │
│                    │   optional    │                   │
│  ┌─────────────┐  │   embedding)  │  ┌─────────────┐ │
│  │  Web         │  └──────────────┘  │  File        │ │
│  │  Dashboard   │                    │  Watcher     │ │
│  │  :37800      │                    │  (auto-index)│ │
│  └─────────────┘                     └─────────────┘ │
│                                                       │
│  Storage: ~/.awareness/                               │
│  ├── memories/          (Markdown files)              │
│  ├── knowledge-cards/   (extracted insights)          │
│  ├── tasks/             (action items)                │
│  ├── index.db           (SQLite FTS5 index)           │
│  └── config.json        (settings)                    │
└───────────────────────────────────────────────────────┘

Key Components

MCP Tools

Awareness Local exposes 5 MCP tools over the standard MCP protocol. These are the same tools as Awareness Cloud — your agent code works identically in both modes.

Recommended Workflow

1. awareness_init(source="cursor")              ← load state + session_id (ALWAYS first)
2. awareness_recall(query="...", detail="summary")  ← search before working
3. ... do work ...
4. awareness_record(content="WHAT/WHY/OUTCOME") ← after each significant step
5. awareness_record(content=[step1, step2, ...]) ← session-end batch summary

Progressive Disclosure

Awareness Local supports a two-level retrieval pattern to minimize token usage:

Level 1: Summary (detail=summary)

Returns compact results — titles, categories, and short excerpts. Fast, low-token, ideal for initial exploration.

// awareness_recall(query="database migration strategy", detail="summary")
{
  "results": [
    {
      "category": "decision",
      "title": "Chose manual SQL migrations over Prisma db push",
      "relevance": 0.92,
      "snippet": "Production safety: db push drops columns..."
    },
    {
      "category": "pitfall",
      "title": "Never run db push with live data",
      "relevance": 0.87,
      "snippet": "Discovered after losing memory_vectors table..."
    }
  ]
}

Level 2: Full (detail=full)

Returns complete content for selected results. Use after identifying relevant items from the summary.

// awareness_recall(query="database migration strategy", detail="full")
{
  "results": [
    {
      "category": "decision",
      "title": "Chose manual SQL migrations over Prisma db push",
      "content": "After losing the memory_vectors table in staging, we established...",
      "context": { "date": "2026-03-10", "session": "abc-123", "agent": "developer" }
    }
  ]
}

This pattern lets agents scan broadly with minimal tokens, then drill into relevant memories only when needed.

Web Dashboard

Access the local dashboard at:

http://localhost:37800/

The dashboard provides:

• Memories — browse all recorded events, organized by date and session
• Knowledge Cards — view extracted decisions, skills, pitfalls, preferences, and other structured insights
• Tasks — manage open action items and track completions
• Search — full-text search across all stored content
• Settings — configure embedding model, storage location, cloud sync, and IDE connections

Cloud Sync (Optional)

Awareness Local works perfectly offline. When you are ready, you can enable cloud sync to unlock additional capabilities.

How to Enable

Option A: From the dashboard

Open http://localhost:37800/settings and click Connect to Cloud.

Option B: From the command line

npx @awareness-sdk/setup --cloud

What Cloud Adds

Data Flow

Local is always primary. Cloud is a sync layer.

┌──────────┐     push     ┌──────────────┐
│  Local   │ ──────────►  │  Awareness   │
│  Daemon  │              │  Cloud       │
│          │ ◄──────────  │              │
└──────────┘     pull     └──────────────┘

- Write: always hits local first, then syncs to cloud in background
- Read: local first; falls back to cloud for semantic search results
- Offline: everything works; syncs when connection resumes
- Delete: local delete propagates to cloud on next sync

Cross-Device Sync via Git

Since Awareness Local stores everything as Markdown files, you can sync across devices using git:

Setup

cd ~/.awareness
git init
git remote add origin git@github.com:yourname/my-awareness.git
git add -A && git commit -m "Initial awareness sync"
git push -u origin main

On Another Device

git clone git@github.com:yourname/my-awareness.git ~/.awareness
npx @awareness-sdk/setup   # daemon auto-detects existing data

Ongoing Sync

# Push local changes
cd ~/.awareness && git add -A && git commit -m "sync" && git push

# Pull remote changes (daemon auto-reindexes on file changes)
cd ~/.awareness && git pull

The file watcher detects changes from git pull and rebuilds the search index automatically. No manual reindexing needed.

IDE Plugins

Awareness Local works with the standard Awareness ecosystem:

Configuration

Awareness Local stores its configuration in ~/.awareness/config.json:

{
  "daemon": {
    "port": 37800,
    "auto_start": true
  },
  "storage": {
    "path": "~/.awareness",
    "format": "markdown"
  },
  "search": {
    "engine": "fts5",
    "embedding": {
      "enabled": false,
      "model": "all-MiniLM-L6-v2",
      "device": "cpu"
    }
  },
  "cloud": {
    "enabled": false,
    "url": "https://awareness.market",
    "sync_interval_seconds": 300
  },
  "extraction": {
    "auto_extract_knowledge": true,
    "language": "auto"
  }
}

Key Settings

MCP Configuration

Awareness Local uses the standard MCP HTTP/SSE transport. After running npx @awareness-sdk/setup, your IDE MCP config will look like:

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

No API key or authentication is needed for local mode.

Local vs Cloud — Feature Comparison

FAQ

Can I switch from Local to Cloud later? Yes. Run npx @awareness-sdk/setup --cloud or enable cloud sync in the dashboard. Your existing local memories will be uploaded and indexed with semantic search.

Does Local mode support multiple projects? Yes. Each project gets its own memory space under ~/.awareness/memories/. The daemon manages them all.

Can I use Local and Cloud simultaneously? Yes. When cloud sync is enabled, local remains the primary store. Writes go to local first, then sync to cloud in the background.

Is the Markdown format stable? Yes. The Markdown format is the stable, documented storage contract. It will not change in backward-incompatible ways.

Can I edit memory files manually? Yes. They are plain Markdown. Edit them in any text editor. The file watcher will detect changes and update the search index automatically.