> For the complete documentation index, see [llms.txt](https://docs.neohive.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neohive.ai/core-concepts/how-it-works.md).
# How NeoHive works
How your agent, the NeoHive plugin, and the NeoHive container fit together, and where each one runs.
NeoHive gives every coding agent on your team one shared memory. Your agent connects to NeoHive over [MCP](/reference/glossary.md#mcp), and the NeoHive plugin tells the agent when to use memory. The memory itself runs in a Docker container on your machine or a shared server. Knowing where each part runs helps you set NeoHive up and find the cause when an agent cannot reach NeoHive.
Every teammate's agent reads the same memory, whichever tool the teammate uses. When one person's agent saves a note, every other agent can recall that note. The following diagram shows three teammates' agents sharing one [Hive](/reference/glossary.md#hive):
Your agent does not read NeoHive's files. The agent asks through an MCP tool, such as `memory_recall` or `memory_store`, and gets matching code, docs, and [Memories](/reference/glossary.md#memory) back. For more information about each tool, see [MCP tools](/reference/mcp-tools.md).
## Your agents and the plugin
The plugin installs a [rules file](/reference/glossary.md#rules-file) that tells your agent when to use memory. To install the plugin, see [Connect your agent](/get-started/connect.md). What else the plugin runs depends on your tool:
{% tabs %}
{% tab title="Claude Code" %}
Two hooks do most of the work:
* When a session starts, a hook installs the plugin's rules file.
* When you send a prompt, a hook runs `memory_recall` on the prompt. The hook adds the results to the agent's context before the agent answers.
To save what your agent learned, run `/neohive:capture-session-learnings` before you close the session.
{% endtab %}
{% tab title="Cursor and Codex" %}
These plugins have no hooks. Their rules file tells the agent to load context at the start of a session and to recall before it searches files. To save what your agent learned, run the `capture-session-learnings` skill before you close the session.
{% endtab %}
{% tab title="Other MCP apps" %}
ChatGPT, Claude Desktop, and other MCP apps have no plugin. To tell the agent when to call NeoHive, add the rules from [Tell your agent to use NeoHive](/get-started/connect.md#tell-your-agent-to-use-neohive).
{% endtab %}
{% endtabs %}
For more information about each hook and how to turn the hook off, see [What the plugin does automatically](/get-better-results/plugin-automation.md).
## The NeoHive container
NeoHive is one Docker container named `neohive`. The container keeps your code, documents, and Memories on the machine it runs on.
The container holds your Hives and their [Indexes](/reference/glossary.md#index). For more information about Hives and Indexes, see [Hives, Indexes, and Memories](/core-concepts/hives-indexes-memories.md). The container also provides the following:
* **You manage your Hives in the dashboard.** The dashboard opens in your browser at the address the installer prints, `http://localhost:3577` by default.
* **Each Hive has its own MCP endpoint.** The endpoint path is `/hives//mcp`.
* **One Docker volume holds all your data.** Your data lives in the `neohive-data` volume.
## Your sources
NeoHive indexes two kinds of source: repositories that it syncs, and files that you upload.
When you add a repository, the container does the following:
1. Clones the repository, such as one on GitHub or GitLab, into the `neohive-data` volume.
2. Splits each file into [chunks](/reference/glossary.md#chunk).
3. Turns each chunk into an [embedding](/reference/glossary.md#embedding).
4. Stores the chunks and their embeddings in a [Code](/reference/glossary.md#code-index) or [Documentation Index](/reference/glossary.md#documentation-index).
Later syncs index only the files that changed. Syncs also run on a schedule, so a Code or Documentation Index stays up to date with its repository.
When you upload a file, such as a document, PDF, or image, NeoHive indexes the file the same way, in a [Files Index](/reference/glossary.md#files-index). An uploaded file does not sync, so upload the new version when the file changes. For more information, see [Add documents and images](/add-your-context/documents.md).
NeoHive embeds and searches your content on the machine it runs on. On a Mac with Apple Silicon, embedding runs in the [Metal worker](/reference/glossary.md#metal-worker), outside the container. For more information about each connection the container makes to outside services, see [What stays on your machine](/security-and-privacy/local-only.md).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.neohive.ai/core-concepts/how-it-works.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
