apiary-memory 0.2.0__py3-none-any.whl

hive_mcp/tools.json

@@ -0,0 +1,211 @@
+{
+  "$comment": "OFFLINE FALLBACK SNAPSHOT of the tool surface - not a second source of truth. When the Hive is reachable, tools/list is relayed from the backend. This file mirrors the BACKEND, which is why it carries recall.query_vector and propose.vector although the local store has no embedder: stdio.py narrows the served list per engine at request time (LOCAL_UNSUPPORTED_ARGUMENTS for inputs, LOCAL_PROPERTY_TEXT for wording), so a machine the local engine serves is never told it can send an embedding, and never told its text query is ranked semantically. Defaults declared here are the defaults BOTH engines apply: store.py holds each one as a named constant and tests check the two against each other. Directory crawlers index the local path, so this file must stay both truthful and high-scoring (Glama TDQS). tests/test_bridge.py enforces agreement with tests/backend_tools_snapshot.json and enforces the runtime narrowing.",
+  "tools": [
+    {
+      "name": "recall",
+      "title": "Recall memory",
+      "description": "Search the human's confirmed memory by natural-language query and return the closest stored entries. Use this to find what was previously decided, recorded, or agreed. Do not use it at session start when you have no query yet - use get_context instead. Do not use it to review entries still awaiting approval - use manage with action list_pending. Annotations already declare this read-only, so this text covers what they cannot: results come from the confirmed store only, private vaults are omitted for agents not permitted to read them, and an empty list means no match rather than no memory.",
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "Natural-language search text, e.g. 'what did we decide about the pricing page'. Ranked by the Hive's index of words and character bigrams, with synonym expansion and a recency nudge; supply query_vector to rank by meaning instead."
+          },
+          "limit": {
+            "type": "integer",
+            "description": "Maximum number of memories to return. Omit for the server default.",
+            "default": 10
+          },
+          "compact": {
+            "type": "boolean",
+            "description": "Return trimmed records (id, title, snippet) instead of full bodies. Saves tokens when you only need to know whether something exists.",
+            "default": true
+          },
+          "vaults": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Narrow the search to these vault names. Omit to search every vault this agent may read. Naming a vault the agent may not read is not an error - it returns nothing from that vault."
+          },
+          "query_vector": {
+            "type": "array",
+            "items": { "type": "number" },
+            "description": "Precomputed embedding. When supplied, recall ranks by vector similarity and ignores 'query' text matching."
+          }
+        },
+        "required": ["query"]
+      }
+    },
+    {
+      "name": "propose",
+      "title": "Propose a memory",
+      "description": "Submit a memory for the human to approve. It lands in a pending queue and changes no confirmed memory. Use it when the human says to remember something, or when a decision is reached that will still matter later. Do not use it as a scratchpad for transient reasoning or for data you merely fetched. This tool cannot confirm its own writes: the entry stays pending until the human accepts it inside their own Hive, so a success response means queued, not stored. Supply client_id to make retries idempotent.",
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": false,
+        "openWorldHint": false
+      },
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "content": {
+            "type": "string",
+            "description": "The memory to store, written as a standalone fact that still makes sense without this conversation - include the who and the when."
+          },
+          "title": {
+            "type": "string",
+            "description": "Short label shown in the human's pending queue. Helps them decide quickly."
+          },
+          "vault": {
+            "type": "string",
+            "description": "Target vault name. Private vaults are rejected for cloud agents; local agents may target them."
+          },
+          "tags": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Free-form tags for later filtering."
+          },
+          "vector": {
+            "type": "array",
+            "items": { "type": "number" },
+            "description": "Optional precomputed embedding stored alongside the memory, so later recalls are faster and more precise."
+          },
+          "client_id": {
+            "type": "string",
+            "description": "Idempotency key. Submitting twice with the same key does not create a duplicate - use this when retrying after a timeout."
+          }
+        },
+        "required": ["content"]
+      }
+    },
+    {
+      "name": "manage",
+      "title": "Manage stored memories",
+      "description": "Inspect or change the lifecycle of a specific stored memory, addressed by id or by queue state. Use list_pending to review what is awaiting the human's approval, and get_by_id to read one entry in full. forget soft-deletes and is reversible with restore; discard_pending permanently drops an entry that was never confirmed. To search confirmed memory by topic instead of by address, use recall. Except for discard_pending, every action here is reversible, which is why this is not marked destructive.",
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": false,
+        "openWorldHint": false
+      },
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "action": {
+            "type": "string",
+            "enum": ["list_pending", "forget", "restore", "get_by_id", "discard_pending"],
+            "description": "Which lifecycle operation to run. list_pending takes no id; the other four require one."
+          },
+          "id": {
+            "type": "string",
+            "description": "Target memory id. Required for forget, restore, get_by_id and discard_pending; ignored by list_pending."
+          }
+        },
+        "required": ["action"]
+      }
+    },
+    {
+      "name": "get_context",
+      "title": "Get session context",
+      "description": "Pull a short digest of recent memory from the human's active threads and open tasks, to seed a conversation before they ask anything. Call this once at session start. For answering a specific question, use recall instead, since that searches all confirmed memory rather than only what is recent. For entries still awaiting approval, use manage with action list_pending. Annotations already declare this read-only; what they cannot say is that the digest reflects the most recent activity, so two calls minutes apart may differ.",
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "limit": {
+            "type": "integer",
+            "description": "Maximum number of context entries to return. Omit for the server default.",
+            "default": 8
+          }
+        }
+      }
+    },
+    {
+      "name": "say",
+      "title": "Post to the shared board",
+      "description": "Post a message to the shared board so the human and other agents see what was done or what is being handed over. Use it when finishing a unit of work, or to hand work to another agent. Do not use it to report routine steps the human did not ask about - the human reads this board. To read what others have posted, use board. Identity comes from your credential, so a caller cannot post as another agent.",
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": false,
+        "idempotentHint": false,
+        "openWorldHint": false
+      },
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "summary": {
+            "type": "string",
+            "description": "What happened, in one or two sentences. Write the outcome, not a log of steps."
+          },
+          "to": {
+            "type": "string",
+            "description": "Who should see it: 'master' for the human (default), or another agent's id."
+          },
+          "kind": {
+            "type": "string",
+            "enum": ["data", "handoff", "result"],
+            "description": "Card type. May be omitted when stage is given, in which case the kind is derived from the stage."
+          },
+          "stage": {
+            "type": "string",
+            "enum": ["start", "handoff", "done", "blocked"],
+            "description": "Work event: starting, handing off, finished, or blocked. Prefixes the body so the board can be filtered and de-duplicated."
+          },
+          "task_id": {
+            "type": "string",
+            "description": "Link this message to an existing task; the hand-off graph aggregates by it."
+          },
+          "refs": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "References the reader may want: file paths, commit shas, or memory ids."
+          },
+          "ttl": {
+            "type": "integer",
+            "description": "Seconds after which the message stops being returned by board. Defaults to 24 hours, and is clamped to between 60 seconds and 30 days so no card is immortal."
+          }
+        },
+        "required": ["summary"]
+      }
+    },
+    {
+      "name": "board",
+      "title": "Read the shared board",
+      "description": "Read the shared board, optionally only what arrived since your last read. Use it to poll for messages or hand-offs addressed to you. To post, use say. Pass the previous cursor as since so a poll returns only new messages instead of the whole board. Annotations declare this read-only; note that messages expire, so an empty result can mean nothing was posted or that earlier messages have aged out.",
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "limit": {
+            "type": "integer",
+            "description": "Maximum number of messages to return. Omit for the server default.",
+            "default": 20
+          },
+          "since": {
+            "type": "string",
+            "description": "Cursor from a previous call. Only messages newer than this cursor are returned; omit to read the current board."
+          },
+          "roster": {
+            "type": "boolean",
+            "description": "Also return which agents are currently on duty."
+          }
+        }
+      }
+    }
+  ]
+}