Awareness SDK

Give your AI agent persistent memory across sessions.
Local-first MCP memory platform for AI coding agents, SDK apps, and production workflows.
Docs · Cloud · Discord · Quick Start

Awareness SDK is a local-first memory layer for AI agents and AI coding workflows. It provides persistent memory, cross-session recall, hybrid retrieval, and easy integration through MCP, Python, and TypeScript SDKs.

Quick Navigation

• Quick Start
• Features
• Packages
• Integrations
• Environment Variables
• FAQ

FAQ

Does it work offline?

Yes. Local mode runs fully on your machine.

Is cloud required?

No. Cloud features are optional.

How do I add memory to an existing app?

Use AwarenessInterceptor.wrap_openai() / wrap_anthropic() (Python) or wrapOpenAI() / wrapAnthropic() (TypeScript).

---

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

Documentation · Online docs

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.

Documentation · npm

---

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