by edwin-hao-ai
Local-first AI agent memory — one command, works offline, no account needed. Give your Claude Code, Cursor, Windsurf, OpenClaw agent persistent memory. Markdown storage, hybrid search (FTS5 + embedding), MCP protocol, Web dashboard.
# Add to your Claude Code skills
git clone https://github.com/edwin-hao-ai/Awareness-LocalGuides for using ai agents skills like Awareness-Local.
No comments yet. Be the first to share your thoughts!
Give your AI agent persistent memory. One command. No account. Works offline.
Awareness Local is a local-first MCP memory server for AI coding agents. It gives Cursor, Claude Code, Copilot, Cline, and other MCP IDEs persistent memory, hybrid semantic + keyword retrieval, and reusable knowledge cards for long-running software projects.
It runs a lightweight daemon on your machine, stores memory as Markdown, indexes recall with SQLite FTS5 + embeddings, and keeps your AI workflow fast, explainable, and offline-ready.
npx @awareness-sdk/setup
That's it. Your AI agent now remembers everything across sessions.
AI coding agents lose context between sessions. Awareness Local provides cross-session memory recall so agents can continue work without re-explaining architecture, past decisions, pending tasks, and implementation constraints.
npx @awareness-sdk/setup
Then open your IDE and start coding. Awareness tools become available for recall, record, and session initialization.
Yes. Local mode works fully offline with memory stored on your machine.
Memory is stored as Markdown in .awareness/, with a local SQLite index for retrieval.
No. Cloud sync is optional and can be enabled later.
Any MCP-compatible IDE, including Cursor, Claude Code, Copilot, Cline, Windsurf, and others.
Evaluated on LongMemEval — the industry standard benchmark for long-term conversational memory. 500 human-curated questions across 5 core capabilities.
╔══════════════════════════════════════════════════════════════╗
║ ║
║ Awareness Memory — LongMemEval Benchmark Results ║
║ ───────────────────────────────────────────────── ║
║ ║
║ Benchmark: LongMemEval (ICLR 2025) ║
║ Dataset: 500 human-curated questions ║
║ Variant: LongMemEval_S (~115k tokens per question) ║
║ ║
║ ┌─────────────────────────────────────────────────┐ ║
║ │ │ ║
║ │ Recall@1 77.6% (388 / 500) │ ║
║ │ Recall@3 91.8% (459 / 500) │ ║
║ │ Recall@5 95.6% (478 / 500) ◀ PRIMARY │ ║
║ │ Recall@10 97.4% (487 / 500) │ ║
║ │ │ ║
║ └─────────────────────────────────────────────────┘ ║
║ ║
║ Method: Hybrid RRF (BM25 + Semantic Vector Search) ║
║ Embedding: all-MiniLM-L6-v2 (384d) ║
║ LLM Calls: 0 (pure retrieval, no generation cost) ║
║ Hardware: Apple M1, 8GB RAM — 14 min total ║
║ ║
╚══════════════════════════════════════════════════════════════╝
┌─────────────────────────────────────────────────────────────┐
│ Long-Term Memory Retrieval — R@5 Leaderboard │
│ LongMemEval (ICLR 2025, 500 questions) │
├─────────────────────────────────┬───────────┬───────────────┤
│ System │ R@5 │ Note │
├─────────────────────────────────┼───────────┼───────────────┤
│ MemPalace (ChromaDB raw) │ 96.6% │ R@5 only * │
│ ★ Awareness Memory (Hybrid) │ 95.6% │ Hybrid RRF │
│ OMEGA │ 95.4% │ QA Accuracy │
│ Mastra (GPT-5-mini) │ 94.9% │ QA Accuracy │
│ Mastra (GPT-4o) │ 84.2% │ QA Accuracy │
│ Supermemory │ 81.6% │ QA Accuracy │
│ Zep / Graphiti │ 71.2% │ QA Accuracy │
│ GPT-4o (full context) │ 60.6% │ QA Accuracy │
├─────────────────────────────────┴───────────┴───────────────┤
│ * MemPalace 96.6% is Recall@5 only, not QA Accuracy. │
│ Palace hierarchy was NOT used in the evaluation. │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Awareness Memory — R@5 by Question Type │
│ │
│ knowledge-update ████████████████████████████ 100% │
│ multi-session ███████████████████████████▋ 98.5%│
│ single-session-asst ███████████████████████████▌ 98.2%│
│ temporal-reasoning █████████████████████████▊ 94.7%│
│ single-session-user ████████████████████████▎ 88.6%│
│ single-session-pref ███████████████████████▏ 86.7%│
│ │
│ Overall █████████████████████████▉ 95.6%│
│ │
│ ┌───────────────────────────────────────────────┐ │
│ │ Ablation Study │ │
│ │ ───────────────────────────────────────── │ │
│ │ Vector-only: 92.6% ▓▓▓▓▓▓▓▓▓▓▓▓▓░░░ │ │
│ │ BM25-only: 91.4% ▓▓▓▓▓▓▓▓▓▓▓▓▓░░░ │ │
│ │ Hybrid RRF: 95.6% ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░ ★ │ │
│ │ Hybrid = +3% over any │ │
│ │ single method alone │ │
│ └───────────────────────────────────────────────┘ │
│ │
│ arxiv.org/abs/2410.10813 awareness.market │
└─────────────────────────────────────────────────────────────┘
Zero LLM calls. Reproducible benchmark scripts →
Before: Every session starts from scratch. You re-explain the codebase, re-justify decisions, watch the agent redo work.
After: Your agent says "I remember you were migrating from MySQL to PostgreSQL. Last session you completed the schema changes and had 2 TODOs remaining..."
Session 1 Session 2
┌─────────────────────────┐ ┌─────────────────────────┐
│ Agent: "What database?" │ │ Agent: "I remember we │
│ You: "PostgreSQL..." │ │ chose PostgreSQL for │
│ Agent: "What framework?"│ → │ JSON support. You had │
│ You: "FastAPI..." │ │ 2 TODOs left. Let me │
│ (repeat every session) │ │ continue from there." │
└─────────────────────────┘ └─────────────────────────┘
| IDE | Auto-detected | Plugin |
|-----|:---:|:---:|
| Claude Code | ✅ | awareness-memory |
| Cursor | ✅ | via MCP |
| Windsurf | ✅ | via MCP |
| OpenClaw | ✅ | @awareness-sdk/openclaw-memory |
| Cline | ✅ | via MCP |
| GitHub Copilot | ✅ | via MCP |
| Codex CLI | ✅ | via MCP |
| Kiro | ✅ | via MCP |
| Trae | ✅ | via MCP |
| Zed | ✅ | via MCP |
| JetBrains (Junie) | ✅ | via MCP |
| Augment | ✅ | via MCP |
| AntiGravity (Jules) | ✅ | via MCP |
Your IDE / AI Agent
│
│ MCP Protocol (localhost:37800)
▼
┌────────────────────────────────────┐
│ Awareness Local Daemon