Core Concepts

Understand how Awareness organizes and retrieves knowledge for AI agents.

Memory

A Memory is a project-level container that holds all events, knowledge, and insights for a single workspace or application. Each memory has:

• A unique ID
• A name and optional description
• Agent profiles (roles that interact with it)
• Vector storage configuration

You can create multiple memories — one per project, team, or use case.

Events

Events are the raw input to Awareness. They represent any interaction worth remembering:

• Chat messages between user and assistant
• Tool calls and their results
• Code changes and decisions
• Session summaries

Events are written via the REST API (POST /mcp/events) or MCP tools (awareness_record). Each event is:

1. Stored as a vector embedding for semantic search
2. Optionally processed by client-side LLM for insight extraction

Knowledge Cards

Knowledge Cards are structured insights extracted from events. They capture the meaning behind raw interactions:

Knowledge cards are created through:

• Client-side extraction — Your IDE agent's LLM extracts insights and submits them
• Server-side fallback — When client-side extraction is unavailable

Conflict Detection

When a new card contradicts an existing one, the system automatically detects the conflict, marks outdated cards as superseded, and links new cards to their predecessors for full evolution tracking.

Intelligent Recall

Awareness uses hybrid search to retrieve the most relevant knowledge, combining semantic understanding with keyword precision. When you call retrieve() or use the awareness_recall MCP tool, results are automatically ranked by relevance and freshness.

For best results, provide both a natural-language question and key terms when searching.

Advanced Retrieval Modes

Two optional parameters enable deeper recall for broad or conceptual queries:

• Multi-Level Retrieval (multi_level=True) — Searches both individual chunks and session and time-range context. Useful for "big picture" questions like "What is the overall architecture?" that benefit from aggregated context across sessions.

• Cluster Expansion (cluster_expand=True) — Uses topic-based grouping to find thematically related content. When a topic cluster matches your query, representative chunks from that cluster are included. Best for exploratory or cross-topic queries.

Both are False by default, preserving existing behavior. For precise, targeted queries, the standard retrieval mode is sufficient.

Knowledge Card Dedup & Similarity

Cards are automatically deduplicated using smart semantic deduplication (in addition to text matching). Near-identical cards are skipped, while cards with updated information supersede older versions. Related cards are linked via a similarity network, enabling expansion during retrieval — when you find a relevant card, closely related cards are surfaced alongside it.

Integration Methods

Awareness provides two integration methods: MCP and SDK.

MCP (Model Context Protocol)

Best for: IDE agents (Cursor, Claude Code, Windsurf, Cline, VS Code GitHub Copilot)

• 4 unified tools: awareness_init, awareness_recall, awareness_lookup, awareness_record
• Session-aware with automatic context loading
• Designed for LLM tool-calling workflows
• Zero configuration — just add the MCP server config to your IDE

SDK (Python & TypeScript)

Best for: Custom AI agents, framework integrations (LangChain, CrewAI, AutoGen)

• Full read/write access to memories, content, and insights
• Built-in integrations for popular AI frameworks
• Batch operations and file uploads

Both methods access the same underlying data. Use MCP for IDE-based development and SDK for programmatic integrations.

Multi-User Mode

Awareness supports multiple users per memory. Each user's data is isolated:

• Events are tagged with user_id
• Knowledge cards belong to the user who triggered the extraction
• Public data (no user_id) is visible to all users

Agent Roles & Sub-Agent Support

An agent role identifies what an agent does within a memory. Examples:

• builder_agent — Code development and architecture
• reviewer_agent — Code review and quality checks
• devops_agent — Infrastructure and deployment

Roles enable cross-agent recall: a reviewer can access what the builder learned, and vice versa. Configure roles in the memory's agent profiles.

Agent Profiles with Activation Prompts

Each agent profile can include a custom system_prompt (editable in the frontend Settings tab). When retrieved via list_agents(), profiles are enriched with an activation_prompt — a complete prompt suitable for spawning sub-agents:

# Python SDK
agents = client.list_agents(memory_id="mem-xxx")
for agent in agents["agents"]:
    print(agent["agent_role"], agent["activation_prompt"])

# Get a specific agent's prompt
prompt = client.get_agent_prompt(memory_id="mem-xxx", agent_role="backend_engineer")

// TypeScript SDK
const agents = await client.listAgents({ memoryId: "mem-xxx" });
const prompt = await client.getAgentPrompt({ memoryId: "mem-xxx", agentRole: "backend_engineer" });

MCP clients receive agent profiles automatically via awareness_init or awareness_lookup(type="agents").

Memory Lifecycle

1. Write — Events enter the system via API or MCP
2. Store — Each event is embedded and indexed for fast retrieval
3. Extract — Structured knowledge cards are created from events
4. Dedup — New cards are checked against existing ones via vector similarity
5. Cluster — Content is periodically organized into topic-based groups for broader retrieval
6. Rank — Cards are scored by relevance, freshness, and importance
7. Recall — Search retrieves the most relevant, up-to-date knowledge (with optional multi-level and cluster expansion)

Next Steps

• Quick Start — Set up in 5 minutes
• SDK Usage Guide — Python and TypeScript SDK reference
• MCP Tools Reference — All MCP tools