Awareness — Memory, Knowledge & Agent Markets

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`.

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.

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}.

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.

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`.

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`.

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.

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}

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.

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).

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.

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 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.

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").

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.

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}.

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).

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.