Core Concepts
How Awareness thinks about memory — and why it's different from just storing text.
Memory Space
A Memory in Awareness is a project-level container — like a dedicated workspace for one team, project, or AI application. Everything stored inside stays together: conversations, decisions, team preferences, and knowledge history.
You can create one memory per project, or share a memory across multiple AI agents working on the same codebase.
Events: The Raw Feed
Events are the raw material Awareness processes. Anything worth remembering is an event:
- A conversation between you and your AI assistant
- A tool call result (e.g., ran tests, deployment succeeded)
- A code change with a description
- A design decision made during a session
Events are lightweight to record. You don't need to organize them — Awareness does that automatically.
Knowledge Cards: Where Understanding Lives
Knowledge Cards are what Awareness creates from events. If an event is a raw conversation, a knowledge card is the insight extracted from it.
Think of it this way: a conversation where you say "we tried Redis for session storage but it caused memory spikes under load" becomes a knowledge card of type pitfall with the summary: "Redis session storage causes memory spikes at scale — prefer Postgres-backed sessions."
Awareness extracts 13 types of knowledge cards:
| Type | What it captures | Example |
|---|---|---|
| skill | Repeatable steps (muscle memory) | "Deploy: pull → build → nginx reload" |
| decision | Architecture or product choices | "Auth uses RS256 — HS256 rejected due to key rotation complexity" |
| problem_solution | Bug fixes and diagnosis | "502 error after deploy = nginx not reloaded" |
| pitfall | Risk warnings and known traps | "Never run db push in production — drops columns" |
| insight | High-level patterns worth repeating | "Feature flags reduce rollback risk for DB migrations" |
| workflow | First-time process recordings | "How we set up the CI pipeline" |
| key_point | Important facts | "Backend stack: FastAPI + PostgreSQL" |
| personal_preference | Individual coding habits | "Always use snake_case; TypeScript strict mode required" |
| activity_preference | Work style habits | "No major refactors on Fridays" |
| important_detail | Easy-to-miss context | "API keys use the prefix aw_" |
| plan_intention | Future plans | "Planning to migrate auth to OAuth2 next sprint" |
| health_info | Personal context | "Prefers dark mode; sensitive to bright screens" |
| career_info | Background context | "Full-stack engineer, Python/Go primary" |
Conflict Detection
When a new card contradicts an existing one, Awareness automatically detects it. The old card is marked superseded, and the new card is linked to it — so you can always trace the evolution of a decision or fact.
Intelligent Recall
When you ask Awareness a question, it doesn't just do a text search. It combines:
- Semantic matching — finding conceptually related knowledge, not just keyword hits
- Freshness scoring — recent, actively used cards rank higher
- Knowledge graph traversal — following relationships between connected cards
The result is relevant, not just recent. You get what matters for this situation, not everything ever stored.
Recall Modes
| Mode | Best for |
|---|---|
| hybrid | Default. Combined vector + keyword + structured search for best overall results |
| auto | Automatically selects the best retrieval strategy based on your query |
| precise | Vector search only — targeted semantic matching for exact fact lookup |
| session | Full session history — expands matched chunks to complete session context |
| structured | DB-only fast lookup — zero vector search, pure structured data (<50ms) |
Progressive Disclosure
For broad queries, Awareness first returns summaries. If you need the full detail, it fetches it. This means your AI agent reads only what's necessary — saving tokens without losing depth.
Multi-Agent Collaboration
Awareness is built for teams of agents, not just one.
Each agent can have a role — a named persona like builder_agent, reviewer_agent, or devops_agent. Roles enable cross-agent recall: a reviewer can see what the builder learned. A new agent joining the project inherits the full team knowledge instantly.
Data Isolation
Multiple users (or agents) can work in the same memory with isolated views:
- Each user's private data is tagged to them
- Shared team knowledge is visible to all agents
- Fine-grained read/write permission control is available
How Knowledge Evolves Over Time
Awareness isn't a static archive — it's a living knowledge base. Here's how memory evolves:
- Record — Events arrive from conversations or tool calls
- Extract — Knowledge cards are created automatically
- Deduplicate — Near-identical cards are merged; stale cards are flagged
- Conflict check — Contradictions are detected and resolved
- Cluster — Related cards are grouped by topic for efficient broad recall
- Score — Cards are ranked by relevance, recency, and usage signals
- Recall — The right knowledge surfaces at the right moment
Integration: MCP or SDK
MCP (Model Context Protocol) — Best for IDE agents (Cursor, VS Code, Windsurf, Claude Code). Zero configuration. Four unified tools: init, recall, lookup, record.
SDK (Python / TypeScript) — Best for custom agents and framework integrations (LangChain, CrewAI, AutoGen). Full programmatic access, batch operations, file uploads.
Both methods access the same underlying knowledge base.
Next Steps
- Quick Start — Set up in 5 minutes
- SDK Usage Guide — Python and TypeScript SDK reference
- MCP Tools Reference — All MCP tools and parameters