Awareness Cloud Memory

Awareness Cloud Memory

You have access to persistent cloud memory. Memory persists across sessions, devices, and projects.

Automatic Hooks (no action needed)

Hooks run automatically — you don't need to do anything:

Manual Tools

When you need more control beyond automatic hooks, use these Bash commands. All scripts are at ${CLAUDE_SKILL_DIR}/scripts/.

1. Initialize Session

Load cross-session context (summaries, tasks, knowledge cards):

node ${CLAUDE_SKILL_DIR}/scripts/init.js [days=7] [max_cards=20] [max_tasks=20]

Call this ONCE at session start if the auto-recall didn't provide enough context.

2. Search Memory (awareness_recall)

Semantic + keyword hybrid search for past decisions, solutions, and knowledge:

# Basic search
node ${CLAUDE_SKILL_DIR}/scripts/search.js "how was auth implemented?"
With keyword boost
node ${CLAUDE_SKILL_DIR}/scripts/search.js "auth implementation" keyword_query="JWT HKDF"
Advanced options
node ${CLAUDE_SKILL_DIR}/scripts/search.js "deployment issues" \
  scope=timeline limit=10 recall_mode=session \
  multi_level=true cluster_expand=true
Progressive disclosure: get summaries first, then expand specific items
node ${CLAUDE_SKILL_DIR}/scripts/search.js "auth" detail=summary
node ${CLAUDE_SKILL_DIR}/scripts/search.js "auth" detail=full ids=id1,id2

Parameters:

Call BEFORE starting work to avoid re-solving solved problems.

3. Record to Memory (awareness_record)

Save decisions, implementations, and learnings:

# Single event — ALWAYS include reasoning, not just what but WHY
node ${CLAUDE_SKILL_DIR}/scripts/record.js "Implemented JWT auth with HKDF key derivation because NextAuth v5 uses JWE A256CBC-HS512. Files changed: jwt_verify.py, auth.ts"
Batch recording
echo '{"steps":["Step 1: analyzed auth flow","Step 2: implemented JWT verify","Step 3: added tests"]}' | node ${CLAUDE_SKILL_DIR}/scripts/record.js --batch
With structured insights (knowledge cards, tasks, risks)
echo '{"content":"Auth refactor complete","insights":{"knowledge_cards":[{"title":"JWT Auth","category":"architecture","summary":"HKDF derivation for NextAuth v5"}],"action_items":[{"title":"Add rate limiting","priority":"high"}]}}' | node ${CLAUDE_SKILL_DIR}/scripts/record.js --with-insights
Update task status
node ${CLAUDE_SKILL_DIR}/scripts/record.js --update-task task_id=abc123 status=completed

Call AFTER every meaningful action. If you don't record it, it's lost.

4. Lookup Structured Data (awareness_lookup)

Fast DB queries without vector search (<50ms):

# Open tasks
node ${CLAUDE_SKILL_DIR}/scripts/lookup.js type=tasks status=pending priority=high
Knowledge cards
node ${CLAUDE_SKILL_DIR}/scripts/lookup.js type=knowledge query=auth category=architecture
Risks
node ${CLAUDE_SKILL_DIR}/scripts/lookup.js type=risks level=high
Timeline
node ${CLAUDE_SKILL_DIR}/scripts/lookup.js type=timeline limit=20
Session history
node ${CLAUDE_SKILL_DIR}/scripts/lookup.js type=session_history session_id=xxx
Handoff context (for agent transitions)
node ${CLAUDE_SKILL_DIR}/scripts/lookup.js type=handoff
Project rules
node ${CLAUDE_SKILL_DIR}/scripts/lookup.js type=rules format=markdown
Knowledge graph
node ${CLAUDE_SKILL_DIR}/scripts/lookup.js type=graph search=auth
node ${CLAUDE_SKILL_DIR}/scripts/lookup.js type=graph entity_id=xxx max_hops=2
List agent roles
node ${CLAUDE_SKILL_DIR}/scripts/lookup.js type=agents

Use lookup instead of search when you know WHAT you want (type-based, not semantic).

5. Get Agent Prompt (sub-agent spawning)

Fetch the activation prompt for a specific agent role:

node ${CLAUDE_SKILL_DIR}/scripts/agent-prompt.js role=developer_agent

Use the returned prompt as the sub-agent's system prompt for memory isolation.

Workflow Checklist

Follow this workflow every session:

1. Session start: Auto-recall hook loads context. If insufficient, run init.js manually. 2. Before work: Search memory for relevant past context with search.js. 3. After each change: Record what you did and WHY with record.js. 4. Handle insights: When you make decisions or identify risks, use --with-insights to create searchable knowledge cards. 5. Session end: Auto-capture hook saves a checkpoint.

Setup

One-click setup (recommended)

Run this command — it opens your browser, you sign in, and everything is configured automatically:

node ${CLAUDE_SKILL_DIR}/scripts/setup.js

The setup script will: 1. Open your browser to sign in / register 2. You click "Authorize" — that's it 3. Auto-create or select a memory 4. Write AWARENESS_API_KEY and AWARENESS_MEMORY_ID to your shell profile

Other setup commands:

node ${CLAUDE_SKILL_DIR}/scripts/setup.js --status   # Check current config
node ${CLAUDE_SKILL_DIR}/scripts/setup.js --logout    # Clear credentials

Manual setup (alternative)

Set environment variables directly:

export AWARENESS_API_KEY="aw_your-key"
export AWARENESS_MEMORY_ID="your-memory-uuid"

Local mode (privacy-first, no account needed)

export AWARENESS_LOCAL_URL="http://localhost:37800"

Not configured?

If the auto-recall hook outputs nothing (no block appears), the skill is not configured. Run the setup script above or tell the user to run it.

One-click setup (recommended)

Run this command — it opens your browser, you sign in, and everything is configured automatically:

node ${CLAUDE_SKILL_DIR}/scripts/setup.js

The setup script will: 1. Open your browser to sign in / register 2. You click "Authorize" — that's it 3. Auto-create or select a memory 4. Write AWARENESS_API_KEY and AWARENESS_MEMORY_ID to your shell profile

Other setup commands:

node ${CLAUDE_SKILL_DIR}/scripts/setup.js --status   # Check current config
node ${CLAUDE_SKILL_DIR}/scripts/setup.js --logout    # Clear credentials

Manual setup (alternative)

Set environment variables directly:

export AWARENESS_API_KEY="aw_your-key"
export AWARENESS_MEMORY_ID="your-memory-uuid"

Local mode (privacy-first, no account needed)

export AWARENESS_LOCAL_URL="http://localhost:37800"

Not configured?

If the auto-recall hook outputs nothing (no block appears), the skill is not configured. Run the setup script above or tell the user to run it.