Give your AI agent persistent memory across sessions.
Local-first. Works offline. One command to set up. 13+ IDE support.
Docs · Cloud · Discord · Quick Start

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