apiary-memory 0.2.0__tar.gz → 0.2.2__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.
Files changed (16) hide show
  1. {apiary_memory-0.2.0/src/apiary_memory.egg-info → apiary_memory-0.2.2}/PKG-INFO +132 -26
  2. {apiary_memory-0.2.0 → apiary_memory-0.2.2}/README.md +130 -24
  3. {apiary_memory-0.2.0 → apiary_memory-0.2.2}/pyproject.toml +2 -2
  4. {apiary_memory-0.2.0 → apiary_memory-0.2.2/src/apiary_memory.egg-info}/PKG-INFO +132 -26
  5. {apiary_memory-0.2.0 → apiary_memory-0.2.2}/src/hive_mcp/__init__.py +1 -1
  6. {apiary_memory-0.2.0 → apiary_memory-0.2.2}/src/hive_mcp/stdio.py +1 -1
  7. {apiary_memory-0.2.0 → apiary_memory-0.2.2}/LICENSE +0 -0
  8. {apiary_memory-0.2.0 → apiary_memory-0.2.2}/setup.cfg +0 -0
  9. {apiary_memory-0.2.0 → apiary_memory-0.2.2}/src/apiary_memory.egg-info/SOURCES.txt +0 -0
  10. {apiary_memory-0.2.0 → apiary_memory-0.2.2}/src/apiary_memory.egg-info/dependency_links.txt +0 -0
  11. {apiary_memory-0.2.0 → apiary_memory-0.2.2}/src/apiary_memory.egg-info/entry_points.txt +0 -0
  12. {apiary_memory-0.2.0 → apiary_memory-0.2.2}/src/apiary_memory.egg-info/top_level.txt +0 -0
  13. {apiary_memory-0.2.0 → apiary_memory-0.2.2}/src/hive_mcp/cli.py +0 -0
  14. {apiary_memory-0.2.0 → apiary_memory-0.2.2}/src/hive_mcp/store.py +0 -0
  15. {apiary_memory-0.2.0 → apiary_memory-0.2.2}/src/hive_mcp/tools.json +0 -0
  16. {apiary_memory-0.2.0 → apiary_memory-0.2.2}/tests/test_bridge.py +0 -0
{apiary_memory-0.2.0/src/apiary_memory.egg-info → apiary_memory-0.2.2}/PKG-INFO RENAMED
@@ -1,7 +1,7 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: apiary-memory
3
- Version: 0.2.0
4
- Summary: Local-first memory your AI agents share over MCP. Ships a working SQLite memory store; agents propose, only you confirm.
3
+ Version: 0.2.2
4
+ Summary: Local-first memory your AI agents share — over MCP on your machine, or over HTTP from AIs on the web. Ships a working SQLite memory store; agents propose, only you confirm.
5
5
  Author: Apiary
6
6
  License-Expression: MIT
7
7
  Project-URL: Homepage, https://hello-fengchao.com
@@ -26,23 +26,55 @@ Dynamic: license-file
26
26
 
27
27
  <!-- mcp-name: io.github.330899935/apiary-memory -->
28
28
 
29
+ [![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/330899935/apiary-memory)
30
+
31
+ ## At a glance
32
+
33
+ | | |
34
+ | --- | --- |
35
+ | **What it is** | Local-first personal memory for AI agents, over MCP. Agents can search what you have confirmed and *propose* what to keep — only you can confirm it. Everything lives in one SQLite file on your own disk. |
36
+ | **What it is not** | Not a hosted service. No account, no cloud, no telemetry, no daemon. The server runs on *your* machine (`127.0.0.1`), not ours. |
37
+ | **Platforms** | Desktop app: **macOS 10.15+**. Companion app: **iOS 17.0+**. Pip package: any OS with **Python 3.8+**. **There is no Windows desktop app.** |
38
+ | **Install** | `pip install apiary-memory` · or double-click [`apiary-memory-0.2.1.mcpb`](https://github.com/330899935/apiary-memory/releases/download/v0.2.1/apiary-memory-0.2.1.mcpb) |
39
+ | **Version** | `0.2.1` on PyPI · desktop app `1.4.8` |
40
+
41
+ ### Two entry points — and they are not the same
42
+
43
+ | Command | What it is | What happens when you run it |
44
+ | --- | --- | --- |
45
+ | `apiary-memory` | The MCP **server** (stdio) | Meant to be spawned *by* your MCP client. Run it in a terminal and it just waits on stdin — that is correct behaviour, not a hang. |
46
+ | `apiary-memory-cli` | The **human** CLI | `list` pending candidates · `approve <id>` commit one · `search <query>` · `stats` show where the DB lives |
47
+
48
+ `python -m hive_mcp` **does not work** — this package has no `__main__.py`.
49
+
50
+ **The pip package has no GUI and never pops a dialog.** When an agent calls `propose`, the entry goes into a local candidate queue and stays there. Nothing enters the hive until a human runs `apiary-memory-cli list` and then `approve <id>`. If you want a window, use the macOS or iOS app.
51
+
52
+ ### Not to be confused with
53
+
54
+ | Name | Status |
55
+ | --- | --- |
56
+ | `hive-memory` | **Does not exist on PyPI (404).** Any document citing it is wrong — including AI answers about us. |
57
+ | `memory-hive-mcp` | Our own former name. Still installs, but caps at **0.1.9**. Use `pip install apiary-memory` for the current release. |
58
+ | `hive-mcp` | Someone else's Claude Code plugin. |
59
+ | [hive.com](https://hive.com) | Team collaboration software. |
60
+ | [theapiary.sh](https://theapiary.sh) | "the apiary" — shared memory for AI coding agents; its memory component is called `honeycomb`. |
61
+ | [apiarybee.com](https://apiarybee.com) | "Apiary" — a self-organizing agent framework. |
62
+ | 记忆蜂巢 (Chengdu Zhixin Hualao) | An unrelated iOS group-chat app. Same four characters, nothing else in common. |
63
+
29
64
  > **Also known as:** Apiary Memory · 记忆蜂巢 · Memory Hive · 蜂巢 ·
30
- > `io.github.330899935/apiary-memory` (MCP Registry name, from v0.2.0) ·
31
- > `hive-memory` (Registry name up to v0.1.9) · `memory-hive-mcp` (PyPI package until the rename ships).
32
- > Not affiliated with [hive.com](https://hive.com) (team collaboration) or the `hive-mcp` Claude Code plugin.
65
+ > `apiary-memory` on PyPI · `io.github.330899935/apiary-memory` on the MCP Registry (from v0.2.0).
33
66
 
34
- **Local-first personal memory for AI agents, over MCP.** Your agents can search what you have
35
- confirmed and propose what they think you should keep; **only you can confirm it.** Everything
36
- lives in one file on your own disk, and nothing is sent anywhere.
67
+ Your agents can search what you have confirmed and propose what they think you should keep;
68
+ **only you can confirm it.** Everything lives in one file on your own disk, and nothing is sent anywhere.
37
69
 
38
70
  It runs on its own. A working SQLite memory store ships inside this package — no account, no
39
71
  cloud, no daemon, no dependencies.
40
72
 
41
73
  ```bash
42
- pip install memory-hive-mcp
74
+ pip install apiary-memory
43
75
  ```
44
76
 
45
- **Desktop app, no terminal:** download [`memory-hive-mcp-0.1.9.mcpb`](https://github.com/330899935/apiary-memory/releases/download/v0.1.9/memory-hive-mcp-0.1.9.mcpb) and double-click it.
77
+ **Desktop app, no terminal:** download [`apiary-memory-0.2.1.mcpb`](https://github.com/330899935/apiary-memory/releases/download/v0.2.1/apiary-memory-0.2.1.mcpb) and double-click it.
46
78
 
47
79
  Measured on 2026-10-27, on one MacBook with the Hive running locally — script and raw output in [`bench/`](bench/):
48
80
 
@@ -100,11 +132,33 @@ while your client believed it had reached the app. Silent data forking is worse
100
132
  message, so a reply from the app is final. The fallback fires on a connection failure, and on
101
133
  nothing else.
102
134
 
135
+ ## Measured on the app
136
+
137
+ The numbers below come from the macOS app's local HTTP service on one MacBook — **not** from
138
+ this package's SQLite store, which is a different engine over a different dataset. Mixing the
139
+ two would be the usual benchmark trick, so they are kept apart.
140
+
141
+ | | |
142
+ | --- | --- |
143
+ | Store size (four plaintext vaults) | **1,356 entries**, 2.52M chars, 47 distinct days |
144
+ | Retrieval hit rate | Top-5 **92.5%**, Top-20 **95.0%** (n=40) |
145
+ | Latency (local HTTP, incl. round trip) | p50 **90 ms**, p95 **127 ms** |
146
+
147
+ Measured 2026-10-29 against the live service. The hit-rate queries were each entry's own
148
+ title — the easy case. It shows the index is complete; it does not show that free-form
149
+ questions land. A separate pilot using plainly-phrased questions found the right entry in the
150
+ top 5 only twice out of roughly a dozen, which is the biggest known weakness of this version.
151
+
152
+ The four encrypted vaults are excluded from the count because they are unreadable by design.
153
+ A load test at 1,000,000 synthetic entries gave 0.6 s warm search, 5.3 GB RSS and a 1.0 GB
154
+ index — see [`bench/`](https://github.com/330899935/apiary-memory/tree/main/bench) for the
155
+ script and raw output.
156
+
103
157
  ## Install
104
158
 
105
159
  ```bash
106
- pip install memory-hive-mcp # the server: memory-hive-mcp
107
- # the human's CLI: memory-hive-mcp-cli
160
+ pip install apiary-memory # the server: apiary-memory (was memory-hive-mcp)
161
+ # the human's CLI: apiary-memory-cli (was memory-hive-mcp-cli)
108
162
  ```
109
163
 
110
164
  Python 3.8 or newer. There is nothing else to install — the package uses only the standard
@@ -128,8 +182,8 @@ is optional.
128
182
  ```json
129
183
  {
130
184
  "mcpServers": {
131
- "memory-hive": {
132
- "command": "memory-hive-mcp",
185
+ "apiary-memory": {
186
+ "command": "apiary-memory",
133
187
  "env": { "HIVE_MODE": "local" }
134
188
  }
135
189
  }
@@ -142,6 +196,58 @@ is optional.
142
196
  with the headers `X-Hive-Agent` and `X-Hive-Token`. This package is the stdio path; the HTTP
143
197
  endpoint belongs to the app.
144
198
 
199
+ ## Two ways to connect
200
+
201
+ There are two doors onto the same memory. Which one you use depends on **where your AI runs**,
202
+ not on what it can do.
203
+
204
+ | | Local (MCP) | Web (HTTP) |
205
+ | --- | --- | --- |
206
+ | Built for | AIs installed on your Mac | AIs running on someone else's servers |
207
+ | How you connect | a stdio command in a config file | paste one address |
208
+ | Network | none — never leaves the machine | public, relayed by Cloudflare |
209
+ | Available since | this package, 0.1.0 | Desktop app **1.4.8** |
210
+
211
+ Behind both doors is the same home: what a local AI stores today, a web AI can read tomorrow —
212
+ and the other way round. **Swap in a hundred AIs; there is still one memory, and it is on your
213
+ disk.**
214
+
215
+ ### The web (HTTP) door
216
+
217
+ An AI running on the web cannot reach your Mac. So the Desktop app opens a channel outwards.
218
+ In the app, open **AI Connect · Web (HTTP)**, pick one of three levels, and copy the address:
219
+
220
+ | Level | Public? | Address stable? | Use when |
221
+ | --- | --- | --- | --- |
222
+ | **Local web** | no | — | the AI runs on the same machine |
223
+ | **Quick tunnel** | yes | no | you want a web AI in without owning a domain |
224
+ | **Fixed address** | yes | yes | long-term use; needs your own Cloudflare account |
225
+
226
+ **If local works, do not open a tunnel.** That is what the app tells you, and it is our advice
227
+ here too: if local is enough, do not open the door onto the street.
228
+
229
+ Three things to know before you connect:
230
+
231
+ 1. **Once connected, the AI can read your memory.** It gets what it asks for, within what it is
232
+ allowed to see.
233
+ 2. **Over the public internet your data is relayed by Cloudflare — it is not end-to-end
234
+ encrypted to the app.** What is stored and what is computed stay on your Mac, but the traffic
235
+ passes through Cloudflare.
236
+ 3. **The four privacy vaults and the cognition layer are never opened to outside AIs — that is
237
+ a wall, not a switch.** No matter which level you open, they are not part of it.
238
+
239
+ **Which AIs?** Any client that supports remote MCP works — read-only, public vaults only. One
240
+ caveat: ChatGPT uses Custom GPT Actions (OpenAPI), a different mechanism from MCP. An address
241
+ alone will not work there, and that step is not built yet.
242
+
243
+ ### Why `transport` still says `stdio`
244
+
245
+ The package and the MCP Registry entry both declare `"transport": {"type": "stdio"}`. That is
246
+ accurate and stays that way: **this package _is_ the stdio bridge.** The web (HTTP) door is a
247
+ capability of the Desktop app, not of this package. Declaring `http` here would make clients
248
+ dial an endpoint the package does not serve, and the connection would simply fail — so the door
249
+ is documented above rather than declared as a package transport.
250
+
145
251
  ## Prerequisite
146
252
 
147
253
  **None, for the local store** — install the package and it works. A running app is a prerequisite
@@ -222,16 +328,16 @@ Agents propose. You confirm. The confirmation lives in a terminal, in a command
222
328
  type — deliberately not a tool an agent can call.
223
329
 
224
330
  ```bash
225
- memory-hive-mcp-cli list # what is waiting
226
- memory-hive-mcp-cli show <id> # read one in full
227
- memory-hive-mcp-cli approve <id> # confirm it, or --all
228
- memory-hive-mcp-cli reject <id> # drop it for good
229
- memory-hive-mcp-cli search "deploy key" # search confirmed memory
230
- memory-hive-mcp-cli forget <id> # soft delete, reversible
231
- memory-hive-mcp-cli restore <id> # undo forget
232
- memory-hive-mcp-cli stats # counts and the database path
233
- memory-hive-mcp-cli export --out dump.json
234
- memory-hive-mcp-cli path
331
+ apiary-memory-cli list # what is waiting
332
+ apiary-memory-cli show <id> # read one in full
333
+ apiary-memory-cli approve <id> # confirm it, or --all
334
+ apiary-memory-cli reject <id> # drop it for good
335
+ apiary-memory-cli search "deploy key" # search confirmed memory
336
+ apiary-memory-cli forget <id> # soft delete, reversible
337
+ apiary-memory-cli restore <id> # undo forget
338
+ apiary-memory-cli stats # counts and the database path
339
+ apiary-memory-cli export --out dump.json
340
+ apiary-memory-cli path
235
341
  ```
236
342
 
237
343
  `--db <path>` on any command points at a different database. `HIVE_DB` does the same from the
@@ -296,7 +402,7 @@ Written down because a memory tool that oversells itself is worse than one that
296
402
  ## Troubleshooting
297
403
 
298
404
  **"no confirmed memory matched this query" with entries pending.** Correct behaviour. Confirm
299
- them: `memory-hive-mcp-cli list`, then `approve`.
405
+ them: `apiary-memory-cli list`, then `approve`.
300
406
 
301
407
  **A call fails with a message about `HIVE_AGENT_ID`.** The app answered and refused the
302
408
  credential. The call did **not** fall back to the local store, on purpose. Register an agent in
@@ -305,7 +411,7 @@ the app and set both variables, or set `HIVE_MODE=local` if you meant to use the
305
411
  **"Hive app not reachable ... and HIVE_MODE=remote forbids the local fallback".** You asked for
306
412
  the app only and it is not running. Start it, or drop `HIVE_MODE=remote`.
307
413
 
308
- **Where did my memory go?** `memory-hive-mcp-cli stats` prints the database path. If `HIVE_MODE`
414
+ **Where did my memory go?** `apiary-memory-cli stats` prints the database path. If `HIVE_MODE`
309
415
  is `auto` and the app is running, the app has been answering — the local file is untouched by
310
416
  design.
311
417
 
{apiary_memory-0.2.0 → apiary_memory-0.2.2}/README.md RENAMED
@@ -2,23 +2,55 @@
2
2
 
3
3
  <!-- mcp-name: io.github.330899935/apiary-memory -->
4
4
 
5
+ [![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/330899935/apiary-memory)
6
+
7
+ ## At a glance
8
+
9
+ | | |
10
+ | --- | --- |
11
+ | **What it is** | Local-first personal memory for AI agents, over MCP. Agents can search what you have confirmed and *propose* what to keep — only you can confirm it. Everything lives in one SQLite file on your own disk. |
12
+ | **What it is not** | Not a hosted service. No account, no cloud, no telemetry, no daemon. The server runs on *your* machine (`127.0.0.1`), not ours. |
13
+ | **Platforms** | Desktop app: **macOS 10.15+**. Companion app: **iOS 17.0+**. Pip package: any OS with **Python 3.8+**. **There is no Windows desktop app.** |
14
+ | **Install** | `pip install apiary-memory` · or double-click [`apiary-memory-0.2.1.mcpb`](https://github.com/330899935/apiary-memory/releases/download/v0.2.1/apiary-memory-0.2.1.mcpb) |
15
+ | **Version** | `0.2.1` on PyPI · desktop app `1.4.8` |
16
+
17
+ ### Two entry points — and they are not the same
18
+
19
+ | Command | What it is | What happens when you run it |
20
+ | --- | --- | --- |
21
+ | `apiary-memory` | The MCP **server** (stdio) | Meant to be spawned *by* your MCP client. Run it in a terminal and it just waits on stdin — that is correct behaviour, not a hang. |
22
+ | `apiary-memory-cli` | The **human** CLI | `list` pending candidates · `approve <id>` commit one · `search <query>` · `stats` show where the DB lives |
23
+
24
+ `python -m hive_mcp` **does not work** — this package has no `__main__.py`.
25
+
26
+ **The pip package has no GUI and never pops a dialog.** When an agent calls `propose`, the entry goes into a local candidate queue and stays there. Nothing enters the hive until a human runs `apiary-memory-cli list` and then `approve <id>`. If you want a window, use the macOS or iOS app.
27
+
28
+ ### Not to be confused with
29
+
30
+ | Name | Status |
31
+ | --- | --- |
32
+ | `hive-memory` | **Does not exist on PyPI (404).** Any document citing it is wrong — including AI answers about us. |
33
+ | `memory-hive-mcp` | Our own former name. Still installs, but caps at **0.1.9**. Use `pip install apiary-memory` for the current release. |
34
+ | `hive-mcp` | Someone else's Claude Code plugin. |
35
+ | [hive.com](https://hive.com) | Team collaboration software. |
36
+ | [theapiary.sh](https://theapiary.sh) | "the apiary" — shared memory for AI coding agents; its memory component is called `honeycomb`. |
37
+ | [apiarybee.com](https://apiarybee.com) | "Apiary" — a self-organizing agent framework. |
38
+ | 记忆蜂巢 (Chengdu Zhixin Hualao) | An unrelated iOS group-chat app. Same four characters, nothing else in common. |
39
+
5
40
  > **Also known as:** Apiary Memory · 记忆蜂巢 · Memory Hive · 蜂巢 ·
6
- > `io.github.330899935/apiary-memory` (MCP Registry name, from v0.2.0) ·
7
- > `hive-memory` (Registry name up to v0.1.9) · `memory-hive-mcp` (PyPI package until the rename ships).
8
- > Not affiliated with [hive.com](https://hive.com) (team collaboration) or the `hive-mcp` Claude Code plugin.
41
+ > `apiary-memory` on PyPI · `io.github.330899935/apiary-memory` on the MCP Registry (from v0.2.0).
9
42
 
10
- **Local-first personal memory for AI agents, over MCP.** Your agents can search what you have
11
- confirmed and propose what they think you should keep; **only you can confirm it.** Everything
12
- lives in one file on your own disk, and nothing is sent anywhere.
43
+ Your agents can search what you have confirmed and propose what they think you should keep;
44
+ **only you can confirm it.** Everything lives in one file on your own disk, and nothing is sent anywhere.
13
45
 
14
46
  It runs on its own. A working SQLite memory store ships inside this package — no account, no
15
47
  cloud, no daemon, no dependencies.
16
48
 
17
49
  ```bash
18
- pip install memory-hive-mcp
50
+ pip install apiary-memory
19
51
  ```
20
52
 
21
- **Desktop app, no terminal:** download [`memory-hive-mcp-0.1.9.mcpb`](https://github.com/330899935/apiary-memory/releases/download/v0.1.9/memory-hive-mcp-0.1.9.mcpb) and double-click it.
53
+ **Desktop app, no terminal:** download [`apiary-memory-0.2.1.mcpb`](https://github.com/330899935/apiary-memory/releases/download/v0.2.1/apiary-memory-0.2.1.mcpb) and double-click it.
22
54
 
23
55
  Measured on 2026-10-27, on one MacBook with the Hive running locally — script and raw output in [`bench/`](bench/):
24
56
 
@@ -76,11 +108,33 @@ while your client believed it had reached the app. Silent data forking is worse
76
108
  message, so a reply from the app is final. The fallback fires on a connection failure, and on
77
109
  nothing else.
78
110
 
111
+ ## Measured on the app
112
+
113
+ The numbers below come from the macOS app's local HTTP service on one MacBook — **not** from
114
+ this package's SQLite store, which is a different engine over a different dataset. Mixing the
115
+ two would be the usual benchmark trick, so they are kept apart.
116
+
117
+ | | |
118
+ | --- | --- |
119
+ | Store size (four plaintext vaults) | **1,356 entries**, 2.52M chars, 47 distinct days |
120
+ | Retrieval hit rate | Top-5 **92.5%**, Top-20 **95.0%** (n=40) |
121
+ | Latency (local HTTP, incl. round trip) | p50 **90 ms**, p95 **127 ms** |
122
+
123
+ Measured 2026-10-29 against the live service. The hit-rate queries were each entry's own
124
+ title — the easy case. It shows the index is complete; it does not show that free-form
125
+ questions land. A separate pilot using plainly-phrased questions found the right entry in the
126
+ top 5 only twice out of roughly a dozen, which is the biggest known weakness of this version.
127
+
128
+ The four encrypted vaults are excluded from the count because they are unreadable by design.
129
+ A load test at 1,000,000 synthetic entries gave 0.6 s warm search, 5.3 GB RSS and a 1.0 GB
130
+ index — see [`bench/`](https://github.com/330899935/apiary-memory/tree/main/bench) for the
131
+ script and raw output.
132
+
79
133
  ## Install
80
134
 
81
135
  ```bash
82
- pip install memory-hive-mcp # the server: memory-hive-mcp
83
- # the human's CLI: memory-hive-mcp-cli
136
+ pip install apiary-memory # the server: apiary-memory (was memory-hive-mcp)
137
+ # the human's CLI: apiary-memory-cli (was memory-hive-mcp-cli)
84
138
  ```
85
139
 
86
140
  Python 3.8 or newer. There is nothing else to install — the package uses only the standard
@@ -104,8 +158,8 @@ is optional.
104
158
  ```json
105
159
  {
106
160
  "mcpServers": {
107
- "memory-hive": {
108
- "command": "memory-hive-mcp",
161
+ "apiary-memory": {
162
+ "command": "apiary-memory",
109
163
  "env": { "HIVE_MODE": "local" }
110
164
  }
111
165
  }
@@ -118,6 +172,58 @@ is optional.
118
172
  with the headers `X-Hive-Agent` and `X-Hive-Token`. This package is the stdio path; the HTTP
119
173
  endpoint belongs to the app.
120
174
 
175
+ ## Two ways to connect
176
+
177
+ There are two doors onto the same memory. Which one you use depends on **where your AI runs**,
178
+ not on what it can do.
179
+
180
+ | | Local (MCP) | Web (HTTP) |
181
+ | --- | --- | --- |
182
+ | Built for | AIs installed on your Mac | AIs running on someone else's servers |
183
+ | How you connect | a stdio command in a config file | paste one address |
184
+ | Network | none — never leaves the machine | public, relayed by Cloudflare |
185
+ | Available since | this package, 0.1.0 | Desktop app **1.4.8** |
186
+
187
+ Behind both doors is the same home: what a local AI stores today, a web AI can read tomorrow —
188
+ and the other way round. **Swap in a hundred AIs; there is still one memory, and it is on your
189
+ disk.**
190
+
191
+ ### The web (HTTP) door
192
+
193
+ An AI running on the web cannot reach your Mac. So the Desktop app opens a channel outwards.
194
+ In the app, open **AI Connect · Web (HTTP)**, pick one of three levels, and copy the address:
195
+
196
+ | Level | Public? | Address stable? | Use when |
197
+ | --- | --- | --- | --- |
198
+ | **Local web** | no | — | the AI runs on the same machine |
199
+ | **Quick tunnel** | yes | no | you want a web AI in without owning a domain |
200
+ | **Fixed address** | yes | yes | long-term use; needs your own Cloudflare account |
201
+
202
+ **If local works, do not open a tunnel.** That is what the app tells you, and it is our advice
203
+ here too: if local is enough, do not open the door onto the street.
204
+
205
+ Three things to know before you connect:
206
+
207
+ 1. **Once connected, the AI can read your memory.** It gets what it asks for, within what it is
208
+ allowed to see.
209
+ 2. **Over the public internet your data is relayed by Cloudflare — it is not end-to-end
210
+ encrypted to the app.** What is stored and what is computed stay on your Mac, but the traffic
211
+ passes through Cloudflare.
212
+ 3. **The four privacy vaults and the cognition layer are never opened to outside AIs — that is
213
+ a wall, not a switch.** No matter which level you open, they are not part of it.
214
+
215
+ **Which AIs?** Any client that supports remote MCP works — read-only, public vaults only. One
216
+ caveat: ChatGPT uses Custom GPT Actions (OpenAPI), a different mechanism from MCP. An address
217
+ alone will not work there, and that step is not built yet.
218
+
219
+ ### Why `transport` still says `stdio`
220
+
221
+ The package and the MCP Registry entry both declare `"transport": {"type": "stdio"}`. That is
222
+ accurate and stays that way: **this package _is_ the stdio bridge.** The web (HTTP) door is a
223
+ capability of the Desktop app, not of this package. Declaring `http` here would make clients
224
+ dial an endpoint the package does not serve, and the connection would simply fail — so the door
225
+ is documented above rather than declared as a package transport.
226
+
121
227
  ## Prerequisite
122
228
 
123
229
  **None, for the local store** — install the package and it works. A running app is a prerequisite
@@ -198,16 +304,16 @@ Agents propose. You confirm. The confirmation lives in a terminal, in a command
198
304
  type — deliberately not a tool an agent can call.
199
305
 
200
306
  ```bash
201
- memory-hive-mcp-cli list # what is waiting
202
- memory-hive-mcp-cli show <id> # read one in full
203
- memory-hive-mcp-cli approve <id> # confirm it, or --all
204
- memory-hive-mcp-cli reject <id> # drop it for good
205
- memory-hive-mcp-cli search "deploy key" # search confirmed memory
206
- memory-hive-mcp-cli forget <id> # soft delete, reversible
207
- memory-hive-mcp-cli restore <id> # undo forget
208
- memory-hive-mcp-cli stats # counts and the database path
209
- memory-hive-mcp-cli export --out dump.json
210
- memory-hive-mcp-cli path
307
+ apiary-memory-cli list # what is waiting
308
+ apiary-memory-cli show <id> # read one in full
309
+ apiary-memory-cli approve <id> # confirm it, or --all
310
+ apiary-memory-cli reject <id> # drop it for good
311
+ apiary-memory-cli search "deploy key" # search confirmed memory
312
+ apiary-memory-cli forget <id> # soft delete, reversible
313
+ apiary-memory-cli restore <id> # undo forget
314
+ apiary-memory-cli stats # counts and the database path
315
+ apiary-memory-cli export --out dump.json
316
+ apiary-memory-cli path
211
317
  ```
212
318
 
213
319
  `--db <path>` on any command points at a different database. `HIVE_DB` does the same from the
@@ -272,7 +378,7 @@ Written down because a memory tool that oversells itself is worse than one that
272
378
  ## Troubleshooting
273
379
 
274
380
  **"no confirmed memory matched this query" with entries pending.** Correct behaviour. Confirm
275
- them: `memory-hive-mcp-cli list`, then `approve`.
381
+ them: `apiary-memory-cli list`, then `approve`.
276
382
 
277
383
  **A call fails with a message about `HIVE_AGENT_ID`.** The app answered and refused the
278
384
  credential. The call did **not** fall back to the local store, on purpose. Register an agent in
@@ -281,7 +387,7 @@ the app and set both variables, or set `HIVE_MODE=local` if you meant to use the
281
387
  **"Hive app not reachable ... and HIVE_MODE=remote forbids the local fallback".** You asked for
282
388
  the app only and it is not running. Start it, or drop `HIVE_MODE=remote`.
283
389
 
284
- **Where did my memory go?** `memory-hive-mcp-cli stats` prints the database path. If `HIVE_MODE`
390
+ **Where did my memory go?** `apiary-memory-cli stats` prints the database path. If `HIVE_MODE`
285
391
  is `auto` and the app is running, the app has been answering — the local file is untouched by
286
392
  design.
287
393
 
{apiary_memory-0.2.0 → apiary_memory-0.2.2}/pyproject.toml RENAMED
@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "apiary-memory"
7
- version = "0.2.0"
8
- description = "Local-first memory your AI agents share over MCP. Ships a working SQLite memory store; agents propose, only you confirm."
7
+ version = "0.2.2"
8
+ description = "Local-first memory your AI agents share — over MCP on your machine, or over HTTP from AIs on the web. Ships a working SQLite memory store; agents propose, only you confirm."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.8"
11
11
  license = "MIT"
{apiary_memory-0.2.0 → apiary_memory-0.2.2/src/apiary_memory.egg-info}/PKG-INFO RENAMED
@@ -1,7 +1,7 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: apiary-memory
3
- Version: 0.2.0
4
- Summary: Local-first memory your AI agents share over MCP. Ships a working SQLite memory store; agents propose, only you confirm.
3
+ Version: 0.2.2
4
+ Summary: Local-first memory your AI agents share — over MCP on your machine, or over HTTP from AIs on the web. Ships a working SQLite memory store; agents propose, only you confirm.
5
5
  Author: Apiary
6
6
  License-Expression: MIT
7
7
  Project-URL: Homepage, https://hello-fengchao.com
@@ -26,23 +26,55 @@ Dynamic: license-file
26
26
 
27
27
  <!-- mcp-name: io.github.330899935/apiary-memory -->
28
28
 
29
+ [![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/330899935/apiary-memory)
30
+
31
+ ## At a glance
32
+
33
+ | | |
34
+ | --- | --- |
35
+ | **What it is** | Local-first personal memory for AI agents, over MCP. Agents can search what you have confirmed and *propose* what to keep — only you can confirm it. Everything lives in one SQLite file on your own disk. |
36
+ | **What it is not** | Not a hosted service. No account, no cloud, no telemetry, no daemon. The server runs on *your* machine (`127.0.0.1`), not ours. |
37
+ | **Platforms** | Desktop app: **macOS 10.15+**. Companion app: **iOS 17.0+**. Pip package: any OS with **Python 3.8+**. **There is no Windows desktop app.** |
38
+ | **Install** | `pip install apiary-memory` · or double-click [`apiary-memory-0.2.1.mcpb`](https://github.com/330899935/apiary-memory/releases/download/v0.2.1/apiary-memory-0.2.1.mcpb) |
39
+ | **Version** | `0.2.1` on PyPI · desktop app `1.4.8` |
40
+
41
+ ### Two entry points — and they are not the same
42
+
43
+ | Command | What it is | What happens when you run it |
44
+ | --- | --- | --- |
45
+ | `apiary-memory` | The MCP **server** (stdio) | Meant to be spawned *by* your MCP client. Run it in a terminal and it just waits on stdin — that is correct behaviour, not a hang. |
46
+ | `apiary-memory-cli` | The **human** CLI | `list` pending candidates · `approve <id>` commit one · `search <query>` · `stats` show where the DB lives |
47
+
48
+ `python -m hive_mcp` **does not work** — this package has no `__main__.py`.
49
+
50
+ **The pip package has no GUI and never pops a dialog.** When an agent calls `propose`, the entry goes into a local candidate queue and stays there. Nothing enters the hive until a human runs `apiary-memory-cli list` and then `approve <id>`. If you want a window, use the macOS or iOS app.
51
+
52
+ ### Not to be confused with
53
+
54
+ | Name | Status |
55
+ | --- | --- |
56
+ | `hive-memory` | **Does not exist on PyPI (404).** Any document citing it is wrong — including AI answers about us. |
57
+ | `memory-hive-mcp` | Our own former name. Still installs, but caps at **0.1.9**. Use `pip install apiary-memory` for the current release. |
58
+ | `hive-mcp` | Someone else's Claude Code plugin. |
59
+ | [hive.com](https://hive.com) | Team collaboration software. |
60
+ | [theapiary.sh](https://theapiary.sh) | "the apiary" — shared memory for AI coding agents; its memory component is called `honeycomb`. |
61
+ | [apiarybee.com](https://apiarybee.com) | "Apiary" — a self-organizing agent framework. |
62
+ | 记忆蜂巢 (Chengdu Zhixin Hualao) | An unrelated iOS group-chat app. Same four characters, nothing else in common. |
63
+
29
64
  > **Also known as:** Apiary Memory · 记忆蜂巢 · Memory Hive · 蜂巢 ·
30
- > `io.github.330899935/apiary-memory` (MCP Registry name, from v0.2.0) ·
31
- > `hive-memory` (Registry name up to v0.1.9) · `memory-hive-mcp` (PyPI package until the rename ships).
32
- > Not affiliated with [hive.com](https://hive.com) (team collaboration) or the `hive-mcp` Claude Code plugin.
65
+ > `apiary-memory` on PyPI · `io.github.330899935/apiary-memory` on the MCP Registry (from v0.2.0).
33
66
 
34
- **Local-first personal memory for AI agents, over MCP.** Your agents can search what you have
35
- confirmed and propose what they think you should keep; **only you can confirm it.** Everything
36
- lives in one file on your own disk, and nothing is sent anywhere.
67
+ Your agents can search what you have confirmed and propose what they think you should keep;
68
+ **only you can confirm it.** Everything lives in one file on your own disk, and nothing is sent anywhere.
37
69
 
38
70
  It runs on its own. A working SQLite memory store ships inside this package — no account, no
39
71
  cloud, no daemon, no dependencies.
40
72
 
41
73
  ```bash
42
- pip install memory-hive-mcp
74
+ pip install apiary-memory
43
75
  ```
44
76
 
45
- **Desktop app, no terminal:** download [`memory-hive-mcp-0.1.9.mcpb`](https://github.com/330899935/apiary-memory/releases/download/v0.1.9/memory-hive-mcp-0.1.9.mcpb) and double-click it.
77
+ **Desktop app, no terminal:** download [`apiary-memory-0.2.1.mcpb`](https://github.com/330899935/apiary-memory/releases/download/v0.2.1/apiary-memory-0.2.1.mcpb) and double-click it.
46
78
 
47
79
  Measured on 2026-10-27, on one MacBook with the Hive running locally — script and raw output in [`bench/`](bench/):
48
80
 
@@ -100,11 +132,33 @@ while your client believed it had reached the app. Silent data forking is worse
100
132
  message, so a reply from the app is final. The fallback fires on a connection failure, and on
101
133
  nothing else.
102
134
 
135
+ ## Measured on the app
136
+
137
+ The numbers below come from the macOS app's local HTTP service on one MacBook — **not** from
138
+ this package's SQLite store, which is a different engine over a different dataset. Mixing the
139
+ two would be the usual benchmark trick, so they are kept apart.
140
+
141
+ | | |
142
+ | --- | --- |
143
+ | Store size (four plaintext vaults) | **1,356 entries**, 2.52M chars, 47 distinct days |
144
+ | Retrieval hit rate | Top-5 **92.5%**, Top-20 **95.0%** (n=40) |
145
+ | Latency (local HTTP, incl. round trip) | p50 **90 ms**, p95 **127 ms** |
146
+
147
+ Measured 2026-10-29 against the live service. The hit-rate queries were each entry's own
148
+ title — the easy case. It shows the index is complete; it does not show that free-form
149
+ questions land. A separate pilot using plainly-phrased questions found the right entry in the
150
+ top 5 only twice out of roughly a dozen, which is the biggest known weakness of this version.
151
+
152
+ The four encrypted vaults are excluded from the count because they are unreadable by design.
153
+ A load test at 1,000,000 synthetic entries gave 0.6 s warm search, 5.3 GB RSS and a 1.0 GB
154
+ index — see [`bench/`](https://github.com/330899935/apiary-memory/tree/main/bench) for the
155
+ script and raw output.
156
+
103
157
  ## Install
104
158
 
105
159
  ```bash
106
- pip install memory-hive-mcp # the server: memory-hive-mcp
107
- # the human's CLI: memory-hive-mcp-cli
160
+ pip install apiary-memory # the server: apiary-memory (was memory-hive-mcp)
161
+ # the human's CLI: apiary-memory-cli (was memory-hive-mcp-cli)
108
162
  ```
109
163
 
110
164
  Python 3.8 or newer. There is nothing else to install — the package uses only the standard
@@ -128,8 +182,8 @@ is optional.
128
182
  ```json
129
183
  {
130
184
  "mcpServers": {
131
- "memory-hive": {
132
- "command": "memory-hive-mcp",
185
+ "apiary-memory": {
186
+ "command": "apiary-memory",
133
187
  "env": { "HIVE_MODE": "local" }
134
188
  }
135
189
  }
@@ -142,6 +196,58 @@ is optional.
142
196
  with the headers `X-Hive-Agent` and `X-Hive-Token`. This package is the stdio path; the HTTP
143
197
  endpoint belongs to the app.
144
198
 
199
+ ## Two ways to connect
200
+
201
+ There are two doors onto the same memory. Which one you use depends on **where your AI runs**,
202
+ not on what it can do.
203
+
204
+ | | Local (MCP) | Web (HTTP) |
205
+ | --- | --- | --- |
206
+ | Built for | AIs installed on your Mac | AIs running on someone else's servers |
207
+ | How you connect | a stdio command in a config file | paste one address |
208
+ | Network | none — never leaves the machine | public, relayed by Cloudflare |
209
+ | Available since | this package, 0.1.0 | Desktop app **1.4.8** |
210
+
211
+ Behind both doors is the same home: what a local AI stores today, a web AI can read tomorrow —
212
+ and the other way round. **Swap in a hundred AIs; there is still one memory, and it is on your
213
+ disk.**
214
+
215
+ ### The web (HTTP) door
216
+
217
+ An AI running on the web cannot reach your Mac. So the Desktop app opens a channel outwards.
218
+ In the app, open **AI Connect · Web (HTTP)**, pick one of three levels, and copy the address:
219
+
220
+ | Level | Public? | Address stable? | Use when |
221
+ | --- | --- | --- | --- |
222
+ | **Local web** | no | — | the AI runs on the same machine |
223
+ | **Quick tunnel** | yes | no | you want a web AI in without owning a domain |
224
+ | **Fixed address** | yes | yes | long-term use; needs your own Cloudflare account |
225
+
226
+ **If local works, do not open a tunnel.** That is what the app tells you, and it is our advice
227
+ here too: if local is enough, do not open the door onto the street.
228
+
229
+ Three things to know before you connect:
230
+
231
+ 1. **Once connected, the AI can read your memory.** It gets what it asks for, within what it is
232
+ allowed to see.
233
+ 2. **Over the public internet your data is relayed by Cloudflare — it is not end-to-end
234
+ encrypted to the app.** What is stored and what is computed stay on your Mac, but the traffic
235
+ passes through Cloudflare.
236
+ 3. **The four privacy vaults and the cognition layer are never opened to outside AIs — that is
237
+ a wall, not a switch.** No matter which level you open, they are not part of it.
238
+
239
+ **Which AIs?** Any client that supports remote MCP works — read-only, public vaults only. One
240
+ caveat: ChatGPT uses Custom GPT Actions (OpenAPI), a different mechanism from MCP. An address
241
+ alone will not work there, and that step is not built yet.
242
+
243
+ ### Why `transport` still says `stdio`
244
+
245
+ The package and the MCP Registry entry both declare `"transport": {"type": "stdio"}`. That is
246
+ accurate and stays that way: **this package _is_ the stdio bridge.** The web (HTTP) door is a
247
+ capability of the Desktop app, not of this package. Declaring `http` here would make clients
248
+ dial an endpoint the package does not serve, and the connection would simply fail — so the door
249
+ is documented above rather than declared as a package transport.
250
+
145
251
  ## Prerequisite
146
252
 
147
253
  **None, for the local store** — install the package and it works. A running app is a prerequisite
@@ -222,16 +328,16 @@ Agents propose. You confirm. The confirmation lives in a terminal, in a command
222
328
  type — deliberately not a tool an agent can call.
223
329
 
224
330
  ```bash
225
- memory-hive-mcp-cli list # what is waiting
226
- memory-hive-mcp-cli show <id> # read one in full
227
- memory-hive-mcp-cli approve <id> # confirm it, or --all
228
- memory-hive-mcp-cli reject <id> # drop it for good
229
- memory-hive-mcp-cli search "deploy key" # search confirmed memory
230
- memory-hive-mcp-cli forget <id> # soft delete, reversible
231
- memory-hive-mcp-cli restore <id> # undo forget
232
- memory-hive-mcp-cli stats # counts and the database path
233
- memory-hive-mcp-cli export --out dump.json
234
- memory-hive-mcp-cli path
331
+ apiary-memory-cli list # what is waiting
332
+ apiary-memory-cli show <id> # read one in full
333
+ apiary-memory-cli approve <id> # confirm it, or --all
334
+ apiary-memory-cli reject <id> # drop it for good
335
+ apiary-memory-cli search "deploy key" # search confirmed memory
336
+ apiary-memory-cli forget <id> # soft delete, reversible
337
+ apiary-memory-cli restore <id> # undo forget
338
+ apiary-memory-cli stats # counts and the database path
339
+ apiary-memory-cli export --out dump.json
340
+ apiary-memory-cli path
235
341
  ```
236
342
 
237
343
  `--db <path>` on any command points at a different database. `HIVE_DB` does the same from the
@@ -296,7 +402,7 @@ Written down because a memory tool that oversells itself is worse than one that
296
402
  ## Troubleshooting
297
403
 
298
404
  **"no confirmed memory matched this query" with entries pending.** Correct behaviour. Confirm
299
- them: `memory-hive-mcp-cli list`, then `approve`.
405
+ them: `apiary-memory-cli list`, then `approve`.
300
406
 
301
407
  **A call fails with a message about `HIVE_AGENT_ID`.** The app answered and refused the
302
408
  credential. The call did **not** fall back to the local store, on purpose. Register an agent in
@@ -305,7 +411,7 @@ the app and set both variables, or set `HIVE_MODE=local` if you meant to use the
305
411
  **"Hive app not reachable ... and HIVE_MODE=remote forbids the local fallback".** You asked for
306
412
  the app only and it is not running. Start it, or drop `HIVE_MODE=remote`.
307
413
 
308
- **Where did my memory go?** `memory-hive-mcp-cli stats` prints the database path. If `HIVE_MODE`
414
+ **Where did my memory go?** `apiary-memory-cli stats` prints the database path. If `HIVE_MODE`
309
415
  is `auto` and the app is running, the app has been answering — the local file is untouched by
310
416
  design.
311
417
 
{apiary_memory-0.2.0 → apiary_memory-0.2.2}/src/hive_mcp/__init__.py RENAMED
@@ -22,6 +22,6 @@ Use ``memory-hive-mcp`` and ``memory-hive-mcp-cli``, or
22
22
  ``from hive_mcp.stdio import main``.
23
23
  """
24
24
 
25
- __version__ = "0.2.0"
25
+ __version__ = "0.2.2"
26
26
 
27
27
  __all__ = ["__version__"]
{apiary_memory-0.2.0 → apiary_memory-0.2.2}/src/hive_mcp/stdio.py RENAMED
@@ -145,7 +145,7 @@ from pathlib import Path
145
145
  # Bumped with pyproject.toml. Only used when neither a source checkout nor
146
146
  # installed metadata can answer; tests assert it matches to keep the two from
147
147
  # drifting the way 0.1.0 did.
148
- _FALLBACK_VERSION = "0.2.0"
148
+ _FALLBACK_VERSION = "0.2.1"
149
149
 
150
150
 
151
151
  def _resolve_version():
{apiary_memory-0.2.0 → apiary_memory-0.2.2}/LICENSE RENAMED
File without changes
{apiary_memory-0.2.0 → apiary_memory-0.2.2}/setup.cfg RENAMED
File without changes