hivemind-memory 2.31.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,7 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.egg-info/
4
+ dist/
5
+ .pytest_cache/
6
+ .mypy_cache/
7
+ .ruff_cache/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Monochrome Muncher
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,146 @@
1
+ Metadata-Version: 2.5
2
+ Name: hivemind-memory
3
+ Version: 2.31.0
4
+ Summary: Async client for Hivemind, the shared memory service for AI agents.
5
+ License-Expression: MIT
6
+ License-File: LICENSE
7
+ Keywords: agents,hivemind,mcp,memory
8
+ Classifier: Framework :: AsyncIO
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Programming Language :: Python :: 3.10
12
+ Classifier: Programming Language :: Python :: 3.11
13
+ Classifier: Programming Language :: Python :: 3.12
14
+ Classifier: Programming Language :: Python :: 3.13
15
+ Classifier: Programming Language :: Python :: 3.14
16
+ Classifier: Typing :: Typed
17
+ Requires-Python: >=3.10
18
+ Requires-Dist: exceptiongroup>=1.2; python_version < '3.11'
19
+ Requires-Dist: httpx2>=2.14
20
+ Requires-Dist: mcp<3,>=2.0.0
21
+ Provides-Extra: langchain
22
+ Requires-Dist: langchain-core<2,>=1.0; extra == 'langchain'
23
+ Description-Content-Type: text/markdown
24
+
25
+ # hivemind-memory
26
+
27
+ Python client for [Hivemind](https://github.com/monochrome-muncher/hivemind/blob/main/README.md), the shared memory service for AI agents. It is for agents and systems you build yourself, outside the harnesses the Hivemind plugin supports. It talks to the server's MCP endpoint (`/mcp`) and adds what a plain MCP connection lacks: the instructions an agent needs to use its memory well, the end-of-task reminder, tool definitions in the Anthropic and OpenAI formats, and a LangChain adapter. If you use Claude Code, Codex, Cursor or another supported harness, install the [plugin](https://github.com/monochrome-muncher/hivemind/blob/main/plugins/hivemind/README.md) instead.
28
+
29
+ Python 3.10 or later. Everything is async.
30
+
31
+ ## Install
32
+
33
+ ```
34
+ pip install hivemind-memory
35
+ pip install "hivemind-memory[langchain]" # with the LangChain adapter
36
+ ```
37
+
38
+ ## Connect
39
+
40
+ Set the endpoint and the agent's key:
41
+
42
+ ```
43
+ export HIVEMIND_MCP_URL=https://hivemind.example.com/mcp
44
+ export HIVEMIND_API_KEY=...
45
+ ```
46
+
47
+ ```python
48
+ from hivemind_memory import Hivemind
49
+
50
+ async with Hivemind.connect() as hive:
51
+ print(hive.whoami)
52
+ hits = await hive.search("how do we deploy the billing service")
53
+ entry = await hive.write("fact", "The billing service deploys from the release branch.")
54
+ ```
55
+
56
+ Arguments win over the variables: `Hivemind.connect(url, api_key)`. Connecting opens the session, lists the tools and calls `hive_whoami`; the answer is `hive.whoami`. If you cannot use `async with`, call `hive = await Hivemind.open()` and `await hive.close()` when you are done.
57
+
58
+ There is one method per tool: `whoami` (as `refresh_whoami`), `search`, `get`, `list`, `pinned`, `write`, `feedback`, `withdraw`, `pin` and `register`. `get` and `feedback` take an id or a list of ids first; the rest take the tool's arguments as keywords. They send only the ones you set, and return the reply as a dict. For the details of each tool, read `hive.tools` or the [spec](https://github.com/monochrome-muncher/hivemind/blob/main/SPEC.md).
59
+
60
+ ## A loop with the Anthropic Messages API
61
+
62
+ This is a sketch, not an app. `instructions()` is the system prompt, `anthropic_tools()` the tool list, and `run_tool()` runs what the model asked for.
63
+
64
+ ```python
65
+ import anthropic
66
+ from hivemind_memory import Hivemind
67
+
68
+
69
+ async def run(task: str) -> None:
70
+ model = anthropic.AsyncAnthropic()
71
+ async with Hivemind.connect() as hive:
72
+ messages = [{"role": "user", "content": task}]
73
+ while True:
74
+ reply = await model.messages.create(
75
+ model="claude-sonnet-5-5",
76
+ max_tokens=4096,
77
+ system=hive.instructions(),
78
+ tools=hive.anthropic_tools(),
79
+ messages=messages,
80
+ )
81
+ messages.append({"role": "assistant", "content": reply.content})
82
+ calls = [block for block in reply.content if block.type == "tool_use"]
83
+ if not calls:
84
+ break
85
+ results = [
86
+ {
87
+ "type": "tool_result",
88
+ "tool_use_id": call.id,
89
+ "content": await hive.run_tool(call.name, call.input),
90
+ }
91
+ for call in calls
92
+ ]
93
+ messages.append({"role": "user", "content": results})
94
+ ```
95
+
96
+ `run_tool()` takes the arguments as the model wrote them, a dict or a JSON string, and returns the reply as text. A refusal comes back as text too, for example `{"error": {"code": "not_found", ...}}`, so the model sees the code and can react. An unknown tool name or unparseable arguments come back as an `invalid_input` error the same way.
97
+
98
+ `openai_tools()` gives the same tools in the Chat Completions `{"type": "function", ...}` format.
99
+
100
+ ## The end-of-task reminder
101
+
102
+ When a task ends, send `hive.reminder()` to the model as one more user turn, once, and let it make its last tool calls. It asks the agent to write what another agent could reuse and to rate the entries its work tested. In the loop above, that means appending `{"role": "user", "content": hive.reminder()}` when the model stops calling tools for the first time, running the loop once more, and then finishing. `hivemind_memory.REMINDER` is the same text as a constant.
103
+
104
+ ## LangChain and LangGraph
105
+
106
+ ```python
107
+ from hivemind_memory import Hivemind
108
+ from hivemind_memory.langchain import langchain_tools, system_message
109
+
110
+ async with Hivemind.connect() as hive:
111
+ tools = langchain_tools(hive) # StructuredTools with the server's names and schemas
112
+ system = system_message(hive) # a SystemMessage with hive.instructions()
113
+ ```
114
+
115
+ The tools work in a LangChain agent and in LangGraph. Like `run_tool()`, they return refusals as text.
116
+
117
+ ## Other frameworks
118
+
119
+ Most agent frameworks can use an MCP server directly. Point the framework at `/mcp` as a streamable HTTP server and send the key in an `Authorization: Bearer <key>` header. Then put `hive.instructions()` in the system prompt. If the framework needs the text before it starts, connect once with this package, read `instructions()`, and give the framework its own MCP connection for the tools.
120
+
121
+ ## One key is one agent
122
+
123
+ A client acts as the agent its key belongs to, and the server records that agent as the author of what it writes. To act as another agent, make a new client with that agent's key and start a new conversation. Do not swap keys under a running conversation.
124
+
125
+ ## Errors
126
+
127
+ A tool that refuses a call raises `HivemindError`, with `.code` (such as `not_found`, `permission_denied`, `invalid_input`) and `.message`. A key that is unknown or locked raises `AuthenticationError`, a subclass, when connecting, and whenever the server answers HTTP 401 or `unauthenticated` or `key_locked` later. A missing URL or key raises `ValueError` and names the variable.
128
+
129
+ ```python
130
+ from hivemind_memory import HivemindError
131
+
132
+ try:
133
+ await hive.feedback(entry["id"], "helpful")
134
+ except HivemindError as error:
135
+ print(error.code, error.message)
136
+ ```
137
+
138
+ ## Development
139
+
140
+ ```
141
+ uv venv --python 3.10 .venv
142
+ uv pip install -e ".[langchain]" --group test
143
+ .venv/bin/python -m pytest
144
+ ```
145
+
146
+ `tests/test_live.py` runs against a real server when `HIVEMIND_LIVE=1`, `HIVEMIND_MCP_URL` and `HIVEMIND_API_KEY` are set. The skill and reminder under `src/hivemind_memory/text/` are copies of the plugin's files; do not edit them here.
@@ -0,0 +1,122 @@
1
+ # hivemind-memory
2
+
3
+ Python client for [Hivemind](https://github.com/monochrome-muncher/hivemind/blob/main/README.md), the shared memory service for AI agents. It is for agents and systems you build yourself, outside the harnesses the Hivemind plugin supports. It talks to the server's MCP endpoint (`/mcp`) and adds what a plain MCP connection lacks: the instructions an agent needs to use its memory well, the end-of-task reminder, tool definitions in the Anthropic and OpenAI formats, and a LangChain adapter. If you use Claude Code, Codex, Cursor or another supported harness, install the [plugin](https://github.com/monochrome-muncher/hivemind/blob/main/plugins/hivemind/README.md) instead.
4
+
5
+ Python 3.10 or later. Everything is async.
6
+
7
+ ## Install
8
+
9
+ ```
10
+ pip install hivemind-memory
11
+ pip install "hivemind-memory[langchain]" # with the LangChain adapter
12
+ ```
13
+
14
+ ## Connect
15
+
16
+ Set the endpoint and the agent's key:
17
+
18
+ ```
19
+ export HIVEMIND_MCP_URL=https://hivemind.example.com/mcp
20
+ export HIVEMIND_API_KEY=...
21
+ ```
22
+
23
+ ```python
24
+ from hivemind_memory import Hivemind
25
+
26
+ async with Hivemind.connect() as hive:
27
+ print(hive.whoami)
28
+ hits = await hive.search("how do we deploy the billing service")
29
+ entry = await hive.write("fact", "The billing service deploys from the release branch.")
30
+ ```
31
+
32
+ Arguments win over the variables: `Hivemind.connect(url, api_key)`. Connecting opens the session, lists the tools and calls `hive_whoami`; the answer is `hive.whoami`. If you cannot use `async with`, call `hive = await Hivemind.open()` and `await hive.close()` when you are done.
33
+
34
+ There is one method per tool: `whoami` (as `refresh_whoami`), `search`, `get`, `list`, `pinned`, `write`, `feedback`, `withdraw`, `pin` and `register`. `get` and `feedback` take an id or a list of ids first; the rest take the tool's arguments as keywords. They send only the ones you set, and return the reply as a dict. For the details of each tool, read `hive.tools` or the [spec](https://github.com/monochrome-muncher/hivemind/blob/main/SPEC.md).
35
+
36
+ ## A loop with the Anthropic Messages API
37
+
38
+ This is a sketch, not an app. `instructions()` is the system prompt, `anthropic_tools()` the tool list, and `run_tool()` runs what the model asked for.
39
+
40
+ ```python
41
+ import anthropic
42
+ from hivemind_memory import Hivemind
43
+
44
+
45
+ async def run(task: str) -> None:
46
+ model = anthropic.AsyncAnthropic()
47
+ async with Hivemind.connect() as hive:
48
+ messages = [{"role": "user", "content": task}]
49
+ while True:
50
+ reply = await model.messages.create(
51
+ model="claude-sonnet-5-5",
52
+ max_tokens=4096,
53
+ system=hive.instructions(),
54
+ tools=hive.anthropic_tools(),
55
+ messages=messages,
56
+ )
57
+ messages.append({"role": "assistant", "content": reply.content})
58
+ calls = [block for block in reply.content if block.type == "tool_use"]
59
+ if not calls:
60
+ break
61
+ results = [
62
+ {
63
+ "type": "tool_result",
64
+ "tool_use_id": call.id,
65
+ "content": await hive.run_tool(call.name, call.input),
66
+ }
67
+ for call in calls
68
+ ]
69
+ messages.append({"role": "user", "content": results})
70
+ ```
71
+
72
+ `run_tool()` takes the arguments as the model wrote them, a dict or a JSON string, and returns the reply as text. A refusal comes back as text too, for example `{"error": {"code": "not_found", ...}}`, so the model sees the code and can react. An unknown tool name or unparseable arguments come back as an `invalid_input` error the same way.
73
+
74
+ `openai_tools()` gives the same tools in the Chat Completions `{"type": "function", ...}` format.
75
+
76
+ ## The end-of-task reminder
77
+
78
+ When a task ends, send `hive.reminder()` to the model as one more user turn, once, and let it make its last tool calls. It asks the agent to write what another agent could reuse and to rate the entries its work tested. In the loop above, that means appending `{"role": "user", "content": hive.reminder()}` when the model stops calling tools for the first time, running the loop once more, and then finishing. `hivemind_memory.REMINDER` is the same text as a constant.
79
+
80
+ ## LangChain and LangGraph
81
+
82
+ ```python
83
+ from hivemind_memory import Hivemind
84
+ from hivemind_memory.langchain import langchain_tools, system_message
85
+
86
+ async with Hivemind.connect() as hive:
87
+ tools = langchain_tools(hive) # StructuredTools with the server's names and schemas
88
+ system = system_message(hive) # a SystemMessage with hive.instructions()
89
+ ```
90
+
91
+ The tools work in a LangChain agent and in LangGraph. Like `run_tool()`, they return refusals as text.
92
+
93
+ ## Other frameworks
94
+
95
+ Most agent frameworks can use an MCP server directly. Point the framework at `/mcp` as a streamable HTTP server and send the key in an `Authorization: Bearer <key>` header. Then put `hive.instructions()` in the system prompt. If the framework needs the text before it starts, connect once with this package, read `instructions()`, and give the framework its own MCP connection for the tools.
96
+
97
+ ## One key is one agent
98
+
99
+ A client acts as the agent its key belongs to, and the server records that agent as the author of what it writes. To act as another agent, make a new client with that agent's key and start a new conversation. Do not swap keys under a running conversation.
100
+
101
+ ## Errors
102
+
103
+ A tool that refuses a call raises `HivemindError`, with `.code` (such as `not_found`, `permission_denied`, `invalid_input`) and `.message`. A key that is unknown or locked raises `AuthenticationError`, a subclass, when connecting, and whenever the server answers HTTP 401 or `unauthenticated` or `key_locked` later. A missing URL or key raises `ValueError` and names the variable.
104
+
105
+ ```python
106
+ from hivemind_memory import HivemindError
107
+
108
+ try:
109
+ await hive.feedback(entry["id"], "helpful")
110
+ except HivemindError as error:
111
+ print(error.code, error.message)
112
+ ```
113
+
114
+ ## Development
115
+
116
+ ```
117
+ uv venv --python 3.10 .venv
118
+ uv pip install -e ".[langchain]" --group test
119
+ .venv/bin/python -m pytest
120
+ ```
121
+
122
+ `tests/test_live.py` runs against a real server when `HIVEMIND_LIVE=1`, `HIVEMIND_MCP_URL` and `HIVEMIND_API_KEY` are set. The skill and reminder under `src/hivemind_memory/text/` are copies of the plugin's files; do not edit them here.
@@ -0,0 +1,51 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "hivemind-memory"
7
+ version = "2.31.0"
8
+ description = "Async client for Hivemind, the shared memory service for AI agents."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ requires-python = ">=3.10"
12
+ keywords = ["agents", "memory", "mcp", "hivemind"]
13
+ classifiers = [
14
+ "Framework :: AsyncIO",
15
+ "Intended Audience :: Developers",
16
+ "Programming Language :: Python :: 3",
17
+ "Programming Language :: Python :: 3.10",
18
+ "Programming Language :: Python :: 3.11",
19
+ "Programming Language :: Python :: 3.12",
20
+ "Programming Language :: Python :: 3.13",
21
+ "Programming Language :: Python :: 3.14",
22
+ "Typing :: Typed",
23
+ ]
24
+ dependencies = [
25
+ "mcp>=2.0.0,<3",
26
+ "httpx2>=2.14",
27
+ "exceptiongroup>=1.2; python_version < '3.11'",
28
+ ]
29
+
30
+ [project.optional-dependencies]
31
+ langchain = ["langchain-core>=1.0,<2"]
32
+
33
+ [dependency-groups]
34
+ test = [
35
+ "pytest>=8",
36
+ "pytest-asyncio>=0.24",
37
+ "langchain-core>=1.0,<2",
38
+ ]
39
+
40
+ [tool.hatch.build.targets.wheel]
41
+ packages = ["src/hivemind_memory"]
42
+
43
+ [tool.pytest.ini_options]
44
+ asyncio_mode = "auto"
45
+ asyncio_default_fixture_loop_scope = "function"
46
+ testpaths = ["tests"]
47
+
48
+ [tool.mypy]
49
+ strict = true
50
+ python_version = "3.10"
51
+ mypy_path = "src"
@@ -0,0 +1,3 @@
1
+ extend = "../../pyproject.toml"
2
+ target-version = "py310"
3
+ src = ["src", "."]
@@ -0,0 +1,8 @@
1
+ """Async client for Hivemind, the shared memory service for AI agents."""
2
+
3
+ from hivemind_memory._version import __version__
4
+ from hivemind_memory.client import Hivemind
5
+ from hivemind_memory.errors import AuthenticationError, HivemindError
6
+ from hivemind_memory.text import REMINDER
7
+
8
+ __all__ = ["REMINDER", "AuthenticationError", "Hivemind", "HivemindError", "__version__"]
@@ -0,0 +1,6 @@
1
+ from importlib import metadata
2
+
3
+ try:
4
+ __version__ = metadata.version("hivemind-memory")
5
+ except metadata.PackageNotFoundError:
6
+ __version__ = "0+unknown"