Awareness SDK

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

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

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

Contributing

Contributions welcome! Please open an issue or pull request.

License

Apache 2.0