Declared fields, filtering, and why metadata is not access control.
Metadata is not access control. Metadata fields (including fields like company_ids or privacy_level) are descriptive labels for filtering and display only. They do not hide neurons from anyone: every user with read access to the brain can see all neurons regardless of metadata, and any caller can simply omit a filter. To restrict who can read a neuron, use NeuronType security (advanced security) — that is the enforced mechanism.
Neuron metadata is a small set of declared labels you can attach to a neuron — a product, a customer list, a privacy classification, a review flag. Its purpose is filtering: narrowing a search or a listing to the slice of the brain that matters, so an agent gets the ten right neurons instead of the two hundred plausible ones.
Metadata is never searched as text and never embedded. Editing it leaves the neuron's embedding, chunks and content hash untouched, so labelling a thousand neurons costs nothing in re-indexing.
Each brain has its own metadata field registry. A key that is not declared cannot be written and cannot be filtered on — that is deliberate. Free-form keys drift ("customer" on one neuron, "customer_id" on the next), and an AI agent has no way to discover what it is allowed to say. The registry is the contract.
Manage it on the brain page, under Metadata fields. Only the brain owner sees that tab. A brain with no declared fields simply has the feature dormant: nothing to write, nothing to filter.
| Property | What it means |
|---|---|
| Key | Lowercase, starts with a letter, letters/digits/_/-,
up to 64 characters — e.g. product_id. Keys starting
with _ are reserved. |
| Value type | string, number or boolean. Dates and
version numbers are declared as string; state the format in the
description (e.g. "ISO date, YYYY-MM-DD"). |
| Multi-valued | When on, the stored value is a list of that type — e.g.
company_ids: ["acme", "globex"]. Filtering a multi-valued
field means "the list contains this value". |
| Allowed values | Optional enum. Leave blank for free-valued. Writes are checked against it; filters are not, so narrowing an enum never makes existing rows unreachable. |
| Description | This is what the AI reads. It is returned by
aiqbee_list_metadata_fields and summarised in
aiqbee_get_brain_info, so it is how a model works out what a
field means and which values are sensible. Write it for the model, not for
yourself: "Which product this note is about; values are product slugs such
as hive-server" beats "product". |
On a neuron's page, the Metadata card gives you one box per declared
field. Leave a box empty to remove that value; Clear all metadata
empties the object entirely. Agents do the same thing through
aiqbee_create_neuron and aiqbee_update_neuron, where
metadata is a merge patch: keys you send are applied over what is stored,
a JSON null deletes a key, and the string clear empties
everything.
Limits: at most 20 keys per neuron and 8 KB of serialised JSON. Values are flat — scalars, or lists of scalars for a multi-valued field. No nested objects.
On the brain page, pick a field and a value under the neuron list to add a filter
chip. Chips are links, so you can bookmark or share a filtered view. Through MCP the
same thing is a metadata_filter argument on
aiqbee_search and aiqbee_list_neurons.
| You write | It means |
|---|---|
{"product_id": "hive-server"} |
Equality. A scalar matches that exact value. For a multi-valued field it means "the stored list contains this value". |
{"privacy_level": ["internal", "public"]} |
Any-of. A list matches if any one of the values matches. |
{"reviewed": {"exists": true}} |
Presence. Matches every neuron that carries the key at all, whatever its value. In the web UI, leave the value box blank. |
{"product_id": "phoenix", "privacy_level": "internal"} |
AND across keys. Every named key must match. Combined with
any-of within a key, that is the whole language: no ranges, no
or/not nesting. |
Filters combine with everything else — text search, neuron type, and access control. A neuron you are not allowed to see stays hidden whether or not a metadata filter is present.
Values are coerced to the declared type, so filtering a number field for
"5" finds 5. Filtering on a key the brain does not declare is
rejected with the list of keys that are declared — which is what lets an agent
correct itself in one round trip instead of silently getting no results.
Neuron metadata is a paid feature, alongside audit history and advanced security — see Licensing & tiers. The gate is deliberately asymmetric, and the asymmetry is what makes a downgrade survivable.
| Operation | Free tier / unentitled licence |
|---|---|
| Reading metadata on a neuron | Always allowed |
| Filtering search and listings by metadata | Always allowed |
| Listing the declared fields | Always allowed |
| Removing a value, clearing a neuron's metadata | Always allowed |
| Deleting a declared field | Always allowed |
| Adding or changing a value | Refused — paid licence required |
| Declaring or editing a field | Refused — paid licence required |
So if a licence lapses or is downgraded: nothing is deleted and nothing is hidden. Every value you wrote while licensed stays on its neuron, stays visible in the UI and in tool results, and stays filterable. Only writes are blocked. Removals stay open on purpose, so you are never trapped in a state you cannot leave. Re-licensing restores writing immediately — there is nothing to restore or re-import.
Greyed-out controls are a courtesy; the check is server-side and applies equally to the web UI and the MCP tools. An expired licence is a separate, broader case: the whole Hive goes read-only, metadata included.
It bears repeating, because the field names invite the mistake. A field called
company_ids or privacy_level looks like a permission. It is
not one, and Hive does not treat it as one.
To actually restrict who can read a neuron, use NeuronType security (advanced security): mark the neuron as type-secured and grant its NeuronType to the users, groups or service accounts who should see it. That is the enforced mechanism, applied on every read path. Metadata sits alongside it as description, never as defence.