Awareness SDK
Local-first AI agent memory — one command, 13+ IDEs, works offline. Persistent memory for Claude Code, Cursor, Windsurf, OpenClaw. Zero-code interceptors for OpenAI/Anthropic. Python & TypeScript SDKs.
Install / Use
/learn @edwin-hao-ai/Awareness SDKQuality Score
Category
Development & EngineeringSupported Platforms
README
Why Awareness?
AI agents forget everything when a session ends. Your agent spent hours making architectural decisions, fixing bugs, and planning next steps — and the next session starts from zero.
Awareness gives your AI agent persistent memory — it remembers what it built, what it decided, what's still pending, and why.
How It Works
Session 1: Agent makes decisions, fixes bugs, creates TODOs
→ awareness_record() saves everything as structured knowledge
Session 2: Agent starts fresh
→ awareness_init() loads context: "Last time you were working on JWT auth..."
→ awareness_recall() finds relevant past decisions
→ Agent picks up where it left off — no re-explaining needed
Quick Start
Option 1: One Command Setup (Recommended)
Works with Claude Code, Cursor, Windsurf, Cline, GitHub Copilot, Codex, and 7 more IDEs.
npx @awareness-sdk/setup
That's it. Your AI agent now has persistent memory. No account needed. Works offline.
Want cloud features later? npx @awareness-sdk/setup --cloud
Option 2: Zero-Code Interceptor (Python/TypeScript SDK)
The fastest way to add memory to existing AI apps. One line — zero code changes.
Python — AwarenessInterceptor.wrap_openai() / .wrap_anthropic()
pip install awareness-memory-cloud
from openai import OpenAI
from memory_cloud import AwarenessInterceptor
client = OpenAI()
# Local mode (no API key needed — data stays on your machine)
interceptor = AwarenessInterceptor(mode="local")
# Cloud mode (team collaboration, semantic search, multi-device sync)
interceptor = AwarenessInterceptor(api_key="aw_...", memory_id="...")
# One line — all conversations automatically remembered
interceptor.wrap_openai(client)
# Use OpenAI as normal — memory happens in the background
response = client.chat.completions.create(
model="gpt-4",
messages=[{"role": "user", "content": "Refactor the auth module"}]
)
TypeScript — AwarenessInterceptor.wrapOpenAI() / .wrapAnthropic()
npm install @awareness-sdk/memory-cloud
import OpenAI from "openai";
import { AwarenessInterceptor } from "@awareness-sdk/memory-cloud";
const openai = new OpenAI();
// Local mode (no API key needed — data stays on your machine)
const interceptor = new AwarenessInterceptor({ mode: "local" });
// Cloud mode (team collaboration, semantic search, multi-device sync)
const interceptor = new AwarenessInterceptor({ apiKey: "aw_...", memoryId: "..." });
// One line — all conversations automatically remembered
interceptor.wrapOpenAI(openai);
// Use as normal — memory happens in the background
const response = await openai.chat.completions.create({
model: "gpt-4",
messages: [{ role: "user", content: "What did we decide about the database?" }],
});
Option 3: IDE Plugins
Claude Code
/plugin marketplace add edwin-hao-ai/Awareness-SDK
/plugin install awareness-memory@awareness
Skills: /awareness-memory:session-start · /awareness-memory:recall · /awareness-memory:save · /awareness-memory:done
OpenClaw
# Plugin (full integration):
openclaw plugins install @awareness-sdk/openclaw-memory
# Or Skill (via ClawHub):
npx clawhub@latest install awareness-memory
Auto-recall on session start. Auto-capture on session end. Zero configuration.
Features
| Feature | Local | + Cloud |
|---------|-------|---------|
| Persistent memory across sessions | ✅ | ✅ |
| 13+ IDE support (Claude Code, Cursor, Windsurf...) | ✅ | ✅ |
| Zero-code interceptor (wrap_openai / wrap_anthropic) | — | ✅ |
| Knowledge card extraction (decisions, solutions, risks) | ✅ | ✅ + LLM |
| Workflow rules injection (agent auto-recalls) | ✅ | ✅ |
| Full-text + semantic search | ✅ | ✅ |
| Progressive disclosure (summary → full) | ✅ | ✅ |
| Cross-device sync | Git | Real-time |
| Semantic vector search (100+ languages) | — | ✅ |
| Multi-agent collaboration | ✅ | ✅ |
| Memory marketplace | — | ✅ |
| Team collaboration | — | ✅ |
Local-First Architecture
Your machine Cloud (optional)
┌─────────────────────┐ ┌─────────────────┐
│ .awareness/ │ sync → │ Awareness Cloud │
│ ├── memories/*.md │ ← sync │ (semantic search│
│ ├── knowledge/ │ │ team sync, │
│ └── index.db │ │ marketplace) │
│ │ └─────────────────┘
│ Daemon :37800 │
│ ├── FTS5 search │
│ ├── MCP server │
│ └── Web dashboard │
└─────────────────────┘
- Data stays on your machine by default
- Works offline — no internet required
- Markdown files — human-readable, git-friendly, portable
- Cloud is optional — one click to enable sync, semantic search, team features
Packages
| Package | Description | Install |
|---------|-------------|---------|
| @awareness-sdk/local | Local daemon + MCP server | npx @awareness-sdk/local start |
| @awareness-sdk/setup | CLI setup for all 13+ IDEs | npx @awareness-sdk/setup |
| awareness-memory-cloud | Python SDK with interceptors | pip install awareness-memory-cloud |
| @awareness-sdk/memory-cloud | TypeScript SDK with interceptors | npm i @awareness-sdk/memory-cloud |
| @awareness-sdk/openclaw-memory | OpenClaw plugin | openclaw plugins install @awareness-sdk/openclaw-memory |
| claudecode/ | Claude Code plugin | /plugin marketplace add edwin-hao-ai/Awareness-SDK then /plugin install awareness-memory@awareness |
Integrations
Works with any AI framework:
- LangChain — Integration guide
- CrewAI — Integration guide
- AutoGen — Integration guide
- PraisonAI — Integration guide
- Custom agents — MCP protocol or REST API
Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| AWARENESS_MCP_URL | MCP endpoint | http://localhost:37800/mcp |
| AWARENESS_API_KEY | Cloud API key (aw_...) | — (local mode: not needed) |
| AWARENESS_MEMORY_ID | Cloud memory ID | — (local mode: auto) |
| AWARENESS_AGENT_ROLE | Agent role filter | builder_agent |
Contributing
Contributions welcome! Please open an issue or pull request.
License
Apache 2.0
