Awareness — Memory, Knowledge & Agent Markets

Publish a listing to the PUBLIC Open Deal Board (anonymous, no API key). Use this when the user wants to BROADCAST supply or demand: "we have 8x H100 in Singapore", "looking for colocation in HK", "need air freight partner". Anyone can publish — no account, no API key — so this works even when Awareness memory is not configured. Publishing rules: * direction must be "supply" (offering) or "demand" (seeking). * category: short slug, e.g. "compute", "colocation", "logistics". * title: short headline (max 200 chars). body: the full description. * region: region code as published, e.g. "SG", "CN-SZ", "HK". * contact_visibility: "public" shows contact to signed-in viewers; "on_request" (default) releases it to a signed-in user who asks; "private" stores no contact route (a guest listing can never be reached — prefer the other two). * Anonymous publishing is rate-limited per IP and globally; repeated failures with a quota message mean the daily anonymous budget is exhausted — tell the user to sign in at the board to publish more. Args: direction: "supply" or "demand". category: Category slug (compute/colocation/logistics...). title: Listing headline. body: Full description. region: Region code (optional). contact_visibility: "public" | "on_request" | "private". Returns: {"ok": true, "deal": {...}, "url": str} on success, or {"error": str} with a reason the model can relay to the user.

Call this when you're unsure what to do next with Awareness memory tools. Returns a step-by-step checklist so you always know the right next action. Low-cost call — use it anytime you need a reminder of the workflow.

Apply a learned skill — returns structured step-by-step execution plan. Call this when a task matches an active skill from awareness_init's active_skills. Returns the skill's methods, summary, and context-adapted guidance. Automatically marks the skill as used (resets decay timer). Args: skill_id: ID of the skill to apply (from active_skills). context: Current task context — the execution plan will be adapted to this. memory_id: Target memory id (auto-resolved if omitted). api_key: Bearer token for authentication.

Chat with a marketplace agent — works WITHOUT login (anonymous trial). Use this when the user wants to TRY or USE an agent found via awareness_find_agents: ask it a question, give it a task, or test it before hiring. The chat is powered by the agent's persona + soul + docs. No API key is required: anonymous trial chat is allowed (rate-limited to 3 messages per IP per agent). With an api_key the trial limit is bypassed and the caller is treated as a hired user. Args: slug: Agent slug from the marketplace listing. message: The user's message to the agent. api_key: Optional Bearer token — bypasses the anonymous trial limit. Returns: {"reply": str, "trial_remaining": int} or {"error": str}.

Hire a marketplace agent (requires login). Use this after the user has tried an agent and wants to keep using it. Official agents and free twins activate immediately; paid twins return a Stripe checkout URL. Args: slug: Agent slug from the marketplace listing. api_key: Bearer token for authentication (required). Returns: {"status": "active"|"pending", "agent_slug": str, "checkout_url"?: str}

Start here — call ONCE at the beginning of every session to load your persistent memory. WHY: Without this call, you have no memory of past sessions. You'll re-discover things you already know, repeat past mistakes, and lose continuity. This is not optional. RETURNS: - session_id: pass this to all awareness_record calls. - context.recent_days: daily summaries (what happened recently). - context.open_tasks: pending work items. - context.knowledge_cards: key decisions and facts you've learned. - active_skills: reusable skill prompts extracted from memory (if any). Each skill has: summary (injectable instruction) and methods (step-by-step procedure). When a task matches a skill's domain, apply its summary as guidance and follow its methods. - agent_profiles: configured agent roles (if any). Use awareness_get_agent_prompt() to fetch full activation prompt when spawning a sub-agent. - _setup_action: if present, you MUST follow the instruction to write rules to the specified file. This enables persistent memory for all future sessions. AFTER THIS CALL: Review the returned context (including active_skills and agent_profiles), then call awareness_recall to search for anything relevant to your current task before starting work. Args: memory_id: Target memory id (auto-resolved from header if omitted). source: Your tool name (e.g. "claude-code", "cursor"). days: Days of history to load (1-90, default 7). max_cards: Max knowledge cards (default 20). max_tasks: Max open tasks (0 = all, default 0). user_id: User identifier for multi-user memories. agent_role: Agent role for role-filtered recall. client_capabilities: Comma-separated (e.g. "file_write,local_dir"). rules_version: Version of rules file you already have (e.g. "1"). If current, _setup_action is skipped. Omit if you don't have rules yet. api_key: Bearer token for authentication.

Mark a skill as used and report the outcome. Call this AFTER applying a skill's instructions during a task. Outcome feedback closes the learning loop: - "success" (default): full decay reset, confidence boost - "partial": partial decay boost, no confidence change - "failed": decay & confidence decrease; 3+ consecutive failures → needs_review Args: skill_id: The skill ID to mark as used. outcome: "success" (default), "partial", or "failed". memory_id: Target memory id (auto-resolved if omitted). api_key: Bearer token for authentication.

Save memory — pass ONE content string, server handles the rest. Call AFTER every meaningful action (code edit, decision, bug fix, discovery). If you don't record it, it's lost forever in the next session. PRIMARY USAGE (single-parameter, F-053): awareness_record(content="Today I decided to switch from Pinecone to pgvector because...") Server defaults action="write" and triggers client-side salience-aware extraction asynchronously. You do NOT need to pass action, scope, or metadata. RECOMMENDED (one call, richer insights): awareness_record( content="WHAT: Refactored auth to JWT. WHY: Sessions didn't scale. OUTCOME: Tests pass.", insights={ "knowledge_cards": [{"category": "decision", "title": "JWT for auth", "summary": "Switched from session cookies to JWT...", "status": "resolved", "tags": ["auth","jwt"], "confidence": 0.9}], "action_items": [{"title": "Add refresh token rotation", "priority": "high", "status": "pending"}] }) Content auto-detection: str → single event (detailed natural language description) list[dict/str] → batch of events str + scope="knowledge" → document/knowledge import OTHER ACTIONS (explicit — server will NOT infer these): update_task — Mark a task done: awareness_record(action="update_task", task_id=..., status="completed") PERCEPTION (auto-returned, review carefully): The response may include a "perception" field with signals you didn't ask about: - contradiction: your new record conflicts with a prior belief - resonance: a similar past experience was found - pattern: a recurring theme detected (3+ occurrences) - staleness: related knowledge hasn't been updated in 60+ days - related_decision: a prior decision in the same domain exists These are push signals — the system noticed something important. YOU MUST ACT on these signals: - contradiction → Tell user about the conflict, ask if intentional - resonance → Mention the related experience to the user - pattern → Suggest a systematic fix for the recurring issue - staleness → Warn user the related knowledge may be outdated - related_decision → Mention the prior decision, ask if still valid Args: action: "write" (default) | "update_task". content: What happened. String, list of events, or document content. insights: Structured insights to create in ONE step. Include knowledge_cards, risks, action_items. scope: "timeline" (default) or "knowledge" for document import. session_id: From awareness_init (auto-resolved if omitted). task_id: Task identifier (for action="update_task"). status: "completed" | "in_progress" | "pending" (for action="update_task").

Run a task with a marketplace agent bound to a memory (requires login). Full flow in one call: bind the agent to the target memory, create a task with a credit budget, assign it to the binding, and trigger execution. The agent works against the memory and reports back. Args: agent_slug: Agent slug (or id) from the marketplace catalog. memory_id: Target memory the agent should work on (must be yours). title: Task title (max 200 chars). description: Task details. budget_credits: Credit budget held from your balance (default 50). api_key: Bearer token for authentication (required). Returns: {"task": {...}, "status": str} with task id, assigned agent, and run status, or {"error": str}.

Bi-temporal fact stream for one entity (active + superseded). Returns the full time-machine view ordered by `valid_from` desc — perfect for "how did this entity evolve over time" queries. Args: entity_id: Entity id to scope the timeline to. predicate: Optional predicate filter. limit: Max facts (1-500). offset: Pagination offset. memory_id: Target memory id (auto-resolved if omitted). api_key: Bearer token for authentication.

Get the full detail page of one Agent Memory Market listing. Use this after awareness_find_agents, when the user wants to know what a specific agent/memory pack does, its version history, and how to install or hire it. Public endpoint — no API key required. Args: id_or_slug: The listing id or slug from a search result. Returns: The listing detail (title, description, category, pricing, versions, install instructions) plus its `url` and `market_url`.

Read bi-temporal facts from the knowledge graph. Default: active facts only (`valid_to IS NULL`). Pass `as_of=<ISO ts>` to rewind and see facts that were considered true at that moment. Args: subject_id: Filter by subject entity id. predicate: Filter by exact predicate string. active_only: Only active facts (ignored when `as_of` is set). as_of: ISO-8601 timestamptz — time-machine cutoff. limit: Max rows (1-200). memory_id: Target memory id (auto-resolved if omitted). api_key: Bearer token for authentication.

Search the Agent Memory Market — ready-made memory packs, skills and agents. Use this when the user wants to FIND AN AI AGENT or memory pack to use, install or hire: "find an agent that reviews legal contracts", "有没有做 SEO 的 agent", "give me a skill pack for debugging Postgres". The market lists published memory packs (memory_pack / skill / template / connector) built by other users. This is NOT a memory tool. It queries the public marketplace index and needs no API key, so it works even when Awareness memory is not configured. Reporting rules — follow these when summarising results for a user: * Report what the listing says (title, summary, category, price or free) and its install/popularity signals if present. Do not invent capabilities that the listing does not describe. * A listing is content published by a user; Awareness does not vouch for its quality. Say so when recommending. Args: query: Free text to match against listing title/summary. category: Optional filter: memory_pack | skill | template | connector. sort_by: "newest", "popular", "rating", "price_asc" or "price_desc" (default "popular"). price_filter: "free" or "paid" to only show that tier. limit: Max listings, 1-100 (default 20). Returns: {"listings": [...], "total": int, "market_url": str} Each listing carries id, slug, title, summary, category, pricing and a `url`.

Search the public Open Deal Board — live business supply and demand. Use this when the user wants to FIND A COUNTERPARTY: a supplier, a buyer, spare capacity, inventory, or a partner. Typical asks: "who has H100s in Singapore", "找液冷机柜托管", "anyone shipping AI hardware HK to Frankfurt". This is NOT a memory tool. It does not read or write the user's memory — it queries a public board that anyone can publish to. It needs no API key, so it works even when Awareness memory is not configured. Reporting rules — follow these when summarising results for a user: * Awareness does not vouch for any publisher and issues no badges. Report what `publisher.evidence` shows (days active, broadcasts published, deals confirmed by both parties, upheld reports) and let the user judge. * `provenance.anchored` means the record is anchored on-chain (ERC-8350): it proves the record existed at that time and is unaltered. It does NOT mean the contents are true. Never describe an anchored listing as "verified" or "guaranteed". * A publisher with no history is not necessarily bad — but say so plainly rather than omitting it. * Contact details are never returned here. Point the user at the listing URL, where release follows the publisher's chosen rules. Args: query: Free text. Matches title and body; works in Chinese and English. direction: "supply" (offering) or "demand" (seeking). Empty = both. category: Category slug, e.g. "compute", "colocation", "logistics". region: Region code as published, e.g. "SG", "CN-SZ", "HK". limit: Max listings, 1-50 (default 20). Returns: {"deals": [...], "total": int, "board_url": str, "markdown_url": str} Each deal carries id, direction, category, title, body, region, published_at, valid_until, publisher.evidence, provenance and a `url`.

Fetch the full activation prompt for a specific agent role (sub-agent spawning). Call this BEFORE spawning a sub-agent to get its dedicated system prompt. Use the returned activation_prompt as the sub-agent's system prompt so that the main agent context stays clean and each sub-agent has an isolated, focused prompt. Typical usage: 1. awareness_init returns agent_profiles with slim summaries (agent_role, title, when_to_use). 2. When a task matches a role, call awareness_get_agent_prompt(agent_role="<role>"). 3. Spawn a sub-agent with the returned activation_prompt as its system prompt. 4. The sub-agent passes agent_role="<role>" to all awareness_* calls for memory isolation. Args: agent_role: The agent role to fetch (e.g. "developer_agent", "reviewer_agent"). memory_id: Target memory id (auto-read from X-Awareness-Memory-Id header if omitted). api_key: Bearer token for authentication.

Fast DB lookup — use this instead of awareness_recall when you know WHAT you want. awareness_recall = "search by meaning" (semantic, slower). awareness_lookup = "get by type" (exact DB query, <50ms). WHEN TO USE: - List all open tasks → type="tasks" - Get knowledge cards → type="knowledge", category="decision" - Check risks → type="risks", priority="high" - Get full context dump → type="context" - Session history → type="session_history", session_id=<id> - Handoff briefing → type="handoff" - List learned skills → type="skills" Args: type: "context" | "tasks" | "knowledge" | "risks" | "session_history" | "timeline" | "handoff" | "rules" | "graph" | "agents" | "skills". query: Keyword filter (for knowledge/handoff). category: Category filter (for knowledge cards). status: Status filter (for tasks/risks/knowledge). priority: "high" | "medium" | "low". session_id: Required for session_history. limit: Max items (default 50).

Search your persistent memory — pass ONE query string, server picks the rest. Call this BEFORE starting work to avoid re-solving solved problems. PRIMARY USAGE (single-parameter, F-053): awareness_recall(query="why did we pick pgvector over Pinecone?") The server auto-routes across raw memories + knowledge cards + workspace graph and picks the right detail level based on token budget. You do NOT need to choose scope, recall_mode, detail, or the vector/bm25 weight manually. LEGACY (still works, logs deprecation): awareness_recall(semantic_query="...", keyword_query="...", detail="summary") awareness_recall(detail="full", ids=["id1", "id2"]) Args: query: Natural-language query (single-parameter API — preferred). limit: Max results (1-30, default 6). hyde_hint: F-060 optional HyDE boost. A short (100-200 char) hypothetical answer to the query. When provided and >= 20 chars, the server embeds it instead of the raw query to bridge the query-vs-document gap. Client-generated (no LLM call in the backend); empty/absent disables. [DEPRECATED] legacy args (accepted for backwards compat): semantic_query / keyword_query: Use `query` instead. scope / recall_mode / detail / ids / multi_level / cluster_expand / include_installed / source_exclude / token_budget: Server now picks these.

Find related entities via n-hop graph traversal. Args: entity_id: Source entity id. max_hops: Traversal depth 1-4 (default 2). limit: Max neighbors (1-200). memory_id: Target memory id (auto-resolved if omitted). api_key: Bearer token for authentication.

Search the PUBLIC Awareness knowledge graph — 1,000+ sourced scientific papers. Use this when the user (especially a researcher or a research agent) asks for peer-reviewed findings: "latest evidence on X", "highly-cited papers about Y", "what does the literature say about Z". This is NOT a memory tool — it does not read the user's private memory, and it needs no per-user API key, so it works even when Awareness memory is not configured (the MCP connection itself still needs its own token). Coverage: condensed-matter, quantum-information, materials, machine-learning, renewable-energy, chemistry, biology, medicine, neuroscience, computer-science (2022-2026, cited >= 50), plus a business supply/demand domain. What comes back (anonymous preview mode): title, snippet (preview), confidence, source_ref (DOI), citation_count, domain/topic, and a detail page URL. Full content is NOT in the preview — tell the user it is paid retrieval via POST /api/v1/public/retrieve with an API key (see https://awareness.market/en/knowledge for the KaaS product). Args: query: Natural-language research question or keywords (2-1000 chars). domain: "science" (default) or "business". topic: Optional sub-topic slug, e.g. "medicine", "condensed-matter", "supply-chain". Empty = search all topics in the domain. top_k: Max results, 1-20 (default 5; anonymous callers are capped at 3). include_graph: When true, also return same-topic related items. Returns: {"results": [{id, title, snippet, confidence, source_ref, citation_count, domain, topic, url}], "related": [...], "total": int, "mode": str} `mode` is "preview" (anonymous) or "full" (authenticated).