Docs

Tools

Every client connected to khive, with OAuth or an API key, is offered the same tools. You don't call them yourself: you ask your agent in plain language and it picks the tool. This page lists them, so you can tell what a call did.

Everything a tool stores stays in your own workspace. Read-only tools are marked as such to clients that show it; save_knowledge_atoms, save_knowledge_domains and delete_record are marked as destructive, because they can replace or remove what is already stored. A refused call comes back with a message that says why, for example atom content must be at least 20 words (got 19).

Memory

Tool	What it does
`remember`	Stores a memory and returns its id. Takes `content`, and optionally `memory_type` (`episodic` or `semantic`), `salience` and `tags`.
`recall_memories`	Finds memories by meaning and returns the closest ones with their scores and ids. Takes a `query`.

A memory is a record. To correct one, pass its id to update_record; to forget one, pass its id to delete_record, and recall_memories stops returning it. To find memories with search_records, search kind memory.

Records and the knowledge graph

Records are entities, such as a service, a person or a document, and notes, such as a decision or an observation. Edges link them with a typed relation.

Tool	What it does
`create_record`	Creates an entity (`kind: "entity"` with an `entity_kind` and a `name`) or a note (`kind: "note"` with a `note_kind` and `content`). Returns the whole record, its id included.
`get_record`	Fetches one record by id.
`update_record`	Changes the name, description, content, tags or properties of a record by id. Fields you leave out stay as they are.
`delete_record`	Deletes a record by id. Afterwards `get_record` answers that it is not found.
`list_records`	Lists records of one kind, with paging. Use it to browse.
`search_records`	Searches records of one `kind` by a `query` and returns ids, snippets and scores. `kind` is required: `entity`, `note`, `memory`, `task`, or a specific kind such as `service` or `decision`.
`link_records`	Links two records with a `relation`, such as `depends_on` between two services. The relation has to fit the two kinds; a pair that does not fit is refused. Takes one link, or a list of links that are written all together or not at all.
`graph_neighbors`	Returns the records linked to one record, given its id or name, with each edge's relation and weight.
`graph_context`	Returns the neighbourhood around one or more entities (ids or names) or around a query, for grounding an answer.

Entity kinds: concept, document, dataset, project, person, org, artifact, service, resource. Note kinds: observation, insight, question, decision, reference. For example, asking your agent to record that an API depends on a database ends in calls like these:

create_record   { "kind": "entity", "entity_kind": "service", "name": "orders-api" }
create_record   { "kind": "entity", "entity_kind": "service", "name": "orders-db" }
link_records    { "source_id": "<orders-api id>", "target_id": "<orders-db id>", "relation": "depends_on" }
graph_neighbors { "node_id": "orders-api" }

Tasks

Tool	What it does
`add_task`	Creates a task and returns its id. Takes a `title`, and optionally a `priority` (`p0` to `p3`, default `p2`), a `due` date, `tags`, an `assignee` and the tasks it `depends_on`. A new task starts in `inbox`.
`list_tasks`	Lists tasks, filtered by status, priority or assignee. Done and cancelled tasks are left out unless you ask for `status: "done"` or `"cancelled"`.
`move_task`	Changes a task's status, for example to `next`, `active` or `waiting`, with an optional note. Moving a task to `cancelled` keeps it and its history.
`complete_task`	Marks a task done, with an optional result note.

Knowledge

Knowledge is reference material you want kept and retrieved as written: atoms, each a piece of text with a slug, grouped into domains. A memory is for a single recollection; an atom is for a document.

Tool	What it does
`save_knowledge_atoms`	Stores atoms, each with a `slug`, a `name` and `content` of at least 20 words. Saving to a slug that already exists replaces that atom. An atom is saved as a draft unless it carries `finalized: true`.
`index_knowledge`	Prepares saved atoms for search. Pass the slugs you just saved.
`search_knowledge`	Searches atoms by a query and returns ranked matches. It returns finalized atoms only.
`get_knowledge_atom`	Fetches one atom or domain by id or slug.
`save_knowledge_domains`	Groups atoms into a domain, with a `slug`, a `name`, a `description` of at least 20 words, and the slugs of its `members`. Saving to a slug that already exists replaces the domain, members included.
`suggest_knowledge_domains`	Returns the domains that fit a question of at least five words, with ids to pass on.
`compose_knowledge`	Builds a briefing from atoms for a question. Given `domain_ids` or `atom_ids`, it draws on those atoms. Without ids, the question must be at least ten words, and it picks from finalized atoms only.

So that an atom can be found by search_knowledge, save it with finalized: true and then index it:

save_knowledge_atoms   { "atoms": [ { "slug": "backups", "name": "Backups", "finalized": true,
                          "content": "The staging database is backed up every night at 02:00 UTC. Each backup is kept for fourteen days, and a restore from the latest backup is tested once a month." } ] }
index_knowledge        { "ids": [ "backups" ] }
search_knowledge       { "query": "how long are backups kept" }

To connect a client, see Quickstart. Questions: contact@khive.ai.