apiary-memory 0.2.0__tar.gz → 0.2.1__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.1}/PKG-INFO +98 -22
  2. {apiary_memory-0.2.0 → apiary_memory-0.2.1}/README.md +96 -20
  3. {apiary_memory-0.2.0 → apiary_memory-0.2.1}/pyproject.toml +2 -2
  4. {apiary_memory-0.2.0 → apiary_memory-0.2.1/src/apiary_memory.egg-info}/PKG-INFO +98 -22
  5. {apiary_memory-0.2.0 → apiary_memory-0.2.1}/src/hive_mcp/__init__.py +1 -1
  6. {apiary_memory-0.2.0 → apiary_memory-0.2.1}/src/hive_mcp/stdio.py +1 -1
  7. {apiary_memory-0.2.0 → apiary_memory-0.2.1}/LICENSE +0 -0
  8. {apiary_memory-0.2.0 → apiary_memory-0.2.1}/setup.cfg +0 -0
  9. {apiary_memory-0.2.0 → apiary_memory-0.2.1}/src/apiary_memory.egg-info/SOURCES.txt +0 -0
  10. {apiary_memory-0.2.0 → apiary_memory-0.2.1}/src/apiary_memory.egg-info/dependency_links.txt +0 -0
  11. {apiary_memory-0.2.0 → apiary_memory-0.2.1}/src/apiary_memory.egg-info/entry_points.txt +0 -0
  12. {apiary_memory-0.2.0 → apiary_memory-0.2.1}/src/apiary_memory.egg-info/top_level.txt +0 -0
  13. {apiary_memory-0.2.0 → apiary_memory-0.2.1}/src/hive_mcp/cli.py +0 -0
  14. {apiary_memory-0.2.0 → apiary_memory-0.2.1}/src/hive_mcp/store.py +0 -0
  15. {apiary_memory-0.2.0 → apiary_memory-0.2.1}/src/hive_mcp/tools.json +0 -0
  16. {apiary_memory-0.2.0 → apiary_memory-0.2.1}/tests/test_bridge.py +0 -0
{apiary_memory-0.2.0/src/apiary_memory.egg-info → apiary_memory-0.2.1}/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.1
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,9 +26,11 @@ 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
+
29
31
  > **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
+ > `apiary-memory` on PyPI and `io.github.330899935/apiary-memory` on the MCP Registry (from v0.2.0) ·
33
+ > old names `memory-hive-mcp` / `hive-memory` (v0.1.9 and earlier) still install and still work.
32
34
  > Not affiliated with [hive.com](https://hive.com) (team collaboration) or the `hive-mcp` Claude Code plugin.
33
35
 
34
36
  **Local-first personal memory for AI agents, over MCP.** Your agents can search what you have
@@ -39,10 +41,10 @@ It runs on its own. A working SQLite memory store ships inside this package —
39
41
  cloud, no daemon, no dependencies.
40
42
 
41
43
  ```bash
42
- pip install memory-hive-mcp
44
+ pip install apiary-memory
43
45
  ```
44
46
 
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.
47
+ **Desktop app, no terminal:** download [`apiary-memory-0.2.0.mcpb`](https://github.com/330899935/apiary-memory/releases/download/v0.2.0/apiary-memory-0.2.0.mcpb) and double-click it.
46
48
 
47
49
  Measured on 2026-10-27, on one MacBook with the Hive running locally — script and raw output in [`bench/`](bench/):
48
50
 
@@ -100,11 +102,33 @@ while your client believed it had reached the app. Silent data forking is worse
100
102
  message, so a reply from the app is final. The fallback fires on a connection failure, and on
101
103
  nothing else.
102
104
 
105
+ ## Measured on the app
106
+
107
+ The numbers below come from the macOS app's local HTTP service on one MacBook — **not** from
108
+ this package's SQLite store, which is a different engine over a different dataset. Mixing the
109
+ two would be the usual benchmark trick, so they are kept apart.
110
+
111
+ | | |
112
+ | --- | --- |
113
+ | Store size (four plaintext vaults) | **1,356 entries**, 2.52M chars, 47 distinct days |
114
+ | Retrieval hit rate | Top-5 **92.5%**, Top-20 **95.0%** (n=40) |
115
+ | Latency (local HTTP, incl. round trip) | p50 **90 ms**, p95 **127 ms** |
116
+
117
+ Measured 2026-10-29 against the live service. The hit-rate queries were each entry's own
118
+ title — the easy case. It shows the index is complete; it does not show that free-form
119
+ questions land. A separate pilot using plainly-phrased questions found the right entry in the
120
+ top 5 only twice out of roughly a dozen, which is the biggest known weakness of this version.
121
+
122
+ The four encrypted vaults are excluded from the count because they are unreadable by design.
123
+ A load test at 1,000,000 synthetic entries gave 0.6 s warm search, 5.3 GB RSS and a 1.0 GB
124
+ index — see [`bench/`](https://github.com/330899935/apiary-memory/tree/main/bench) for the
125
+ script and raw output.
126
+
103
127
  ## Install
104
128
 
105
129
  ```bash
106
- pip install memory-hive-mcp # the server: memory-hive-mcp
107
- # the human's CLI: memory-hive-mcp-cli
130
+ pip install apiary-memory # the server: apiary-memory (was memory-hive-mcp)
131
+ # the human's CLI: apiary-memory-cli (was memory-hive-mcp-cli)
108
132
  ```
109
133
 
110
134
  Python 3.8 or newer. There is nothing else to install — the package uses only the standard
@@ -128,8 +152,8 @@ is optional.
128
152
  ```json
129
153
  {
130
154
  "mcpServers": {
131
- "memory-hive": {
132
- "command": "memory-hive-mcp",
155
+ "apiary-memory": {
156
+ "command": "apiary-memory",
133
157
  "env": { "HIVE_MODE": "local" }
134
158
  }
135
159
  }
@@ -142,6 +166,58 @@ is optional.
142
166
  with the headers `X-Hive-Agent` and `X-Hive-Token`. This package is the stdio path; the HTTP
143
167
  endpoint belongs to the app.
144
168
 
169
+ ## Two ways to connect
170
+
171
+ There are two doors onto the same memory. Which one you use depends on **where your AI runs**,
172
+ not on what it can do.
173
+
174
+ | | Local (MCP) | Web (HTTP) |
175
+ | --- | --- | --- |
176
+ | Built for | AIs installed on your Mac | AIs running on someone else's servers |
177
+ | How you connect | a stdio command in a config file | paste one address |
178
+ | Network | none — never leaves the machine | public, relayed by Cloudflare |
179
+ | Available since | this package, 0.1.0 | Desktop app **1.4.8** |
180
+
181
+ Behind both doors is the same home: what a local AI stores today, a web AI can read tomorrow —
182
+ and the other way round. **Swap in a hundred AIs; there is still one memory, and it is on your
183
+ disk.**
184
+
185
+ ### The web (HTTP) door
186
+
187
+ An AI running on the web cannot reach your Mac. So the Desktop app opens a channel outwards.
188
+ In the app, open **AI Connect · Web (HTTP)**, pick one of three levels, and copy the address:
189
+
190
+ | Level | Public? | Address stable? | Use when |
191
+ | --- | --- | --- | --- |
192
+ | **Local web** | no | — | the AI runs on the same machine |
193
+ | **Quick tunnel** | yes | no | you want a web AI in without owning a domain |
194
+ | **Fixed address** | yes | yes | long-term use; needs your own Cloudflare account |
195
+
196
+ **If local works, do not open a tunnel.** That is what the app tells you, and it is our advice
197
+ here too: if local is enough, do not open the door onto the street.
198
+
199
+ Three things to know before you connect:
200
+
201
+ 1. **Once connected, the AI can read your memory.** It gets what it asks for, within what it is
202
+ allowed to see.
203
+ 2. **Over the public internet your data is relayed by Cloudflare — it is not end-to-end
204
+ encrypted to the app.** What is stored and what is computed stay on your Mac, but the traffic
205
+ passes through Cloudflare.
206
+ 3. **The four privacy vaults and the cognition layer are never opened to outside AIs — that is
207
+ a wall, not a switch.** No matter which level you open, they are not part of it.
208
+
209
+ **Which AIs?** Any client that supports remote MCP works — read-only, public vaults only. One
210
+ caveat: ChatGPT uses Custom GPT Actions (OpenAPI), a different mechanism from MCP. An address
211
+ alone will not work there, and that step is not built yet.
212
+
213
+ ### Why `transport` still says `stdio`
214
+
215
+ The package and the MCP Registry entry both declare `"transport": {"type": "stdio"}`. That is
216
+ accurate and stays that way: **this package _is_ the stdio bridge.** The web (HTTP) door is a
217
+ capability of the Desktop app, not of this package. Declaring `http` here would make clients
218
+ dial an endpoint the package does not serve, and the connection would simply fail — so the door
219
+ is documented above rather than declared as a package transport.
220
+
145
221
  ## Prerequisite
146
222
 
147
223
  **None, for the local store** — install the package and it works. A running app is a prerequisite
@@ -222,16 +298,16 @@ Agents propose. You confirm. The confirmation lives in a terminal, in a command
222
298
  type — deliberately not a tool an agent can call.
223
299
 
224
300
  ```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
301
+ apiary-memory-cli list # what is waiting
302
+ apiary-memory-cli show <id> # read one in full
303
+ apiary-memory-cli approve <id> # confirm it, or --all
304
+ apiary-memory-cli reject <id> # drop it for good
305
+ apiary-memory-cli search "deploy key" # search confirmed memory
306
+ apiary-memory-cli forget <id> # soft delete, reversible
307
+ apiary-memory-cli restore <id> # undo forget
308
+ apiary-memory-cli stats # counts and the database path
309
+ apiary-memory-cli export --out dump.json
310
+ apiary-memory-cli path
235
311
  ```
236
312
 
237
313
  `--db <path>` on any command points at a different database. `HIVE_DB` does the same from the
@@ -296,7 +372,7 @@ Written down because a memory tool that oversells itself is worse than one that
296
372
  ## Troubleshooting
297
373
 
298
374
  **"no confirmed memory matched this query" with entries pending.** Correct behaviour. Confirm
299
- them: `memory-hive-mcp-cli list`, then `approve`.
375
+ them: `apiary-memory-cli list`, then `approve`.
300
376
 
301
377
  **A call fails with a message about `HIVE_AGENT_ID`.** The app answered and refused the
302
378
  credential. The call did **not** fall back to the local store, on purpose. Register an agent in
@@ -305,7 +381,7 @@ the app and set both variables, or set `HIVE_MODE=local` if you meant to use the
305
381
  **"Hive app not reachable ... and HIVE_MODE=remote forbids the local fallback".** You asked for
306
382
  the app only and it is not running. Start it, or drop `HIVE_MODE=remote`.
307
383
 
308
- **Where did my memory go?** `memory-hive-mcp-cli stats` prints the database path. If `HIVE_MODE`
384
+ **Where did my memory go?** `apiary-memory-cli stats` prints the database path. If `HIVE_MODE`
309
385
  is `auto` and the app is running, the app has been answering — the local file is untouched by
310
386
  design.
311
387
 
{apiary_memory-0.2.0 → apiary_memory-0.2.1}/README.md RENAMED
@@ -2,9 +2,11 @@
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
+
5
7
  > **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
+ > `apiary-memory` on PyPI and `io.github.330899935/apiary-memory` on the MCP Registry (from v0.2.0) ·
9
+ > old names `memory-hive-mcp` / `hive-memory` (v0.1.9 and earlier) still install and still work.
8
10
  > Not affiliated with [hive.com](https://hive.com) (team collaboration) or the `hive-mcp` Claude Code plugin.
9
11
 
10
12
  **Local-first personal memory for AI agents, over MCP.** Your agents can search what you have
@@ -15,10 +17,10 @@ It runs on its own. A working SQLite memory store ships inside this package —
15
17
  cloud, no daemon, no dependencies.
16
18
 
17
19
  ```bash
18
- pip install memory-hive-mcp
20
+ pip install apiary-memory
19
21
  ```
20
22
 
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.
23
+ **Desktop app, no terminal:** download [`apiary-memory-0.2.0.mcpb`](https://github.com/330899935/apiary-memory/releases/download/v0.2.0/apiary-memory-0.2.0.mcpb) and double-click it.
22
24
 
23
25
  Measured on 2026-10-27, on one MacBook with the Hive running locally — script and raw output in [`bench/`](bench/):
24
26
 
@@ -76,11 +78,33 @@ while your client believed it had reached the app. Silent data forking is worse
76
78
  message, so a reply from the app is final. The fallback fires on a connection failure, and on
77
79
  nothing else.
78
80
 
81
+ ## Measured on the app
82
+
83
+ The numbers below come from the macOS app's local HTTP service on one MacBook — **not** from
84
+ this package's SQLite store, which is a different engine over a different dataset. Mixing the
85
+ two would be the usual benchmark trick, so they are kept apart.
86
+
87
+ | | |
88
+ | --- | --- |
89
+ | Store size (four plaintext vaults) | **1,356 entries**, 2.52M chars, 47 distinct days |
90
+ | Retrieval hit rate | Top-5 **92.5%**, Top-20 **95.0%** (n=40) |
91
+ | Latency (local HTTP, incl. round trip) | p50 **90 ms**, p95 **127 ms** |
92
+
93
+ Measured 2026-10-29 against the live service. The hit-rate queries were each entry's own
94
+ title — the easy case. It shows the index is complete; it does not show that free-form
95
+ questions land. A separate pilot using plainly-phrased questions found the right entry in the
96
+ top 5 only twice out of roughly a dozen, which is the biggest known weakness of this version.
97
+
98
+ The four encrypted vaults are excluded from the count because they are unreadable by design.
99
+ A load test at 1,000,000 synthetic entries gave 0.6 s warm search, 5.3 GB RSS and a 1.0 GB
100
+ index — see [`bench/`](https://github.com/330899935/apiary-memory/tree/main/bench) for the
101
+ script and raw output.
102
+
79
103
  ## Install
80
104
 
81
105
  ```bash
82
- pip install memory-hive-mcp # the server: memory-hive-mcp
83
- # the human's CLI: memory-hive-mcp-cli
106
+ pip install apiary-memory # the server: apiary-memory (was memory-hive-mcp)
107
+ # the human's CLI: apiary-memory-cli (was memory-hive-mcp-cli)
84
108
  ```
85
109
 
86
110
  Python 3.8 or newer. There is nothing else to install — the package uses only the standard
@@ -104,8 +128,8 @@ is optional.
104
128
  ```json
105
129
  {
106
130
  "mcpServers": {
107
- "memory-hive": {
108
- "command": "memory-hive-mcp",
131
+ "apiary-memory": {
132
+ "command": "apiary-memory",
109
133
  "env": { "HIVE_MODE": "local" }
110
134
  }
111
135
  }
@@ -118,6 +142,58 @@ is optional.
118
142
  with the headers `X-Hive-Agent` and `X-Hive-Token`. This package is the stdio path; the HTTP
119
143
  endpoint belongs to the app.
120
144
 
145
+ ## Two ways to connect
146
+
147
+ There are two doors onto the same memory. Which one you use depends on **where your AI runs**,
148
+ not on what it can do.
149
+
150
+ | | Local (MCP) | Web (HTTP) |
151
+ | --- | --- | --- |
152
+ | Built for | AIs installed on your Mac | AIs running on someone else's servers |
153
+ | How you connect | a stdio command in a config file | paste one address |
154
+ | Network | none — never leaves the machine | public, relayed by Cloudflare |
155
+ | Available since | this package, 0.1.0 | Desktop app **1.4.8** |
156
+
157
+ Behind both doors is the same home: what a local AI stores today, a web AI can read tomorrow —
158
+ and the other way round. **Swap in a hundred AIs; there is still one memory, and it is on your
159
+ disk.**
160
+
161
+ ### The web (HTTP) door
162
+
163
+ An AI running on the web cannot reach your Mac. So the Desktop app opens a channel outwards.
164
+ In the app, open **AI Connect · Web (HTTP)**, pick one of three levels, and copy the address:
165
+
166
+ | Level | Public? | Address stable? | Use when |
167
+ | --- | --- | --- | --- |
168
+ | **Local web** | no | — | the AI runs on the same machine |
169
+ | **Quick tunnel** | yes | no | you want a web AI in without owning a domain |
170
+ | **Fixed address** | yes | yes | long-term use; needs your own Cloudflare account |
171
+
172
+ **If local works, do not open a tunnel.** That is what the app tells you, and it is our advice
173
+ here too: if local is enough, do not open the door onto the street.
174
+
175
+ Three things to know before you connect:
176
+
177
+ 1. **Once connected, the AI can read your memory.** It gets what it asks for, within what it is
178
+ allowed to see.
179
+ 2. **Over the public internet your data is relayed by Cloudflare — it is not end-to-end
180
+ encrypted to the app.** What is stored and what is computed stay on your Mac, but the traffic
181
+ passes through Cloudflare.
182
+ 3. **The four privacy vaults and the cognition layer are never opened to outside AIs — that is
183
+ a wall, not a switch.** No matter which level you open, they are not part of it.
184
+
185
+ **Which AIs?** Any client that supports remote MCP works — read-only, public vaults only. One
186
+ caveat: ChatGPT uses Custom GPT Actions (OpenAPI), a different mechanism from MCP. An address
187
+ alone will not work there, and that step is not built yet.
188
+
189
+ ### Why `transport` still says `stdio`
190
+
191
+ The package and the MCP Registry entry both declare `"transport": {"type": "stdio"}`. That is
192
+ accurate and stays that way: **this package _is_ the stdio bridge.** The web (HTTP) door is a
193
+ capability of the Desktop app, not of this package. Declaring `http` here would make clients
194
+ dial an endpoint the package does not serve, and the connection would simply fail — so the door
195
+ is documented above rather than declared as a package transport.
196
+
121
197
  ## Prerequisite
122
198
 
123
199
  **None, for the local store** — install the package and it works. A running app is a prerequisite
@@ -198,16 +274,16 @@ Agents propose. You confirm. The confirmation lives in a terminal, in a command
198
274
  type — deliberately not a tool an agent can call.
199
275
 
200
276
  ```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
277
+ apiary-memory-cli list # what is waiting
278
+ apiary-memory-cli show <id> # read one in full
279
+ apiary-memory-cli approve <id> # confirm it, or --all
280
+ apiary-memory-cli reject <id> # drop it for good
281
+ apiary-memory-cli search "deploy key" # search confirmed memory
282
+ apiary-memory-cli forget <id> # soft delete, reversible
283
+ apiary-memory-cli restore <id> # undo forget
284
+ apiary-memory-cli stats # counts and the database path
285
+ apiary-memory-cli export --out dump.json
286
+ apiary-memory-cli path
211
287
  ```
212
288
 
213
289
  `--db <path>` on any command points at a different database. `HIVE_DB` does the same from the
@@ -272,7 +348,7 @@ Written down because a memory tool that oversells itself is worse than one that
272
348
  ## Troubleshooting
273
349
 
274
350
  **"no confirmed memory matched this query" with entries pending.** Correct behaviour. Confirm
275
- them: `memory-hive-mcp-cli list`, then `approve`.
351
+ them: `apiary-memory-cli list`, then `approve`.
276
352
 
277
353
  **A call fails with a message about `HIVE_AGENT_ID`.** The app answered and refused the
278
354
  credential. The call did **not** fall back to the local store, on purpose. Register an agent in
@@ -281,7 +357,7 @@ the app and set both variables, or set `HIVE_MODE=local` if you meant to use the
281
357
  **"Hive app not reachable ... and HIVE_MODE=remote forbids the local fallback".** You asked for
282
358
  the app only and it is not running. Start it, or drop `HIVE_MODE=remote`.
283
359
 
284
- **Where did my memory go?** `memory-hive-mcp-cli stats` prints the database path. If `HIVE_MODE`
360
+ **Where did my memory go?** `apiary-memory-cli stats` prints the database path. If `HIVE_MODE`
285
361
  is `auto` and the app is running, the app has been answering — the local file is untouched by
286
362
  design.
287
363
 
{apiary_memory-0.2.0 → apiary_memory-0.2.1}/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.1"
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.1/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.1
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,9 +26,11 @@ 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
+
29
31
  > **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
+ > `apiary-memory` on PyPI and `io.github.330899935/apiary-memory` on the MCP Registry (from v0.2.0) ·
33
+ > old names `memory-hive-mcp` / `hive-memory` (v0.1.9 and earlier) still install and still work.
32
34
  > Not affiliated with [hive.com](https://hive.com) (team collaboration) or the `hive-mcp` Claude Code plugin.
33
35
 
34
36
  **Local-first personal memory for AI agents, over MCP.** Your agents can search what you have
@@ -39,10 +41,10 @@ It runs on its own. A working SQLite memory store ships inside this package —
39
41
  cloud, no daemon, no dependencies.
40
42
 
41
43
  ```bash
42
- pip install memory-hive-mcp
44
+ pip install apiary-memory
43
45
  ```
44
46
 
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.
47
+ **Desktop app, no terminal:** download [`apiary-memory-0.2.0.mcpb`](https://github.com/330899935/apiary-memory/releases/download/v0.2.0/apiary-memory-0.2.0.mcpb) and double-click it.
46
48
 
47
49
  Measured on 2026-10-27, on one MacBook with the Hive running locally — script and raw output in [`bench/`](bench/):
48
50
 
@@ -100,11 +102,33 @@ while your client believed it had reached the app. Silent data forking is worse
100
102
  message, so a reply from the app is final. The fallback fires on a connection failure, and on
101
103
  nothing else.
102
104
 
105
+ ## Measured on the app
106
+
107
+ The numbers below come from the macOS app's local HTTP service on one MacBook — **not** from
108
+ this package's SQLite store, which is a different engine over a different dataset. Mixing the
109
+ two would be the usual benchmark trick, so they are kept apart.
110
+
111
+ | | |
112
+ | --- | --- |
113
+ | Store size (four plaintext vaults) | **1,356 entries**, 2.52M chars, 47 distinct days |
114
+ | Retrieval hit rate | Top-5 **92.5%**, Top-20 **95.0%** (n=40) |
115
+ | Latency (local HTTP, incl. round trip) | p50 **90 ms**, p95 **127 ms** |
116
+
117
+ Measured 2026-10-29 against the live service. The hit-rate queries were each entry's own
118
+ title — the easy case. It shows the index is complete; it does not show that free-form
119
+ questions land. A separate pilot using plainly-phrased questions found the right entry in the
120
+ top 5 only twice out of roughly a dozen, which is the biggest known weakness of this version.
121
+
122
+ The four encrypted vaults are excluded from the count because they are unreadable by design.
123
+ A load test at 1,000,000 synthetic entries gave 0.6 s warm search, 5.3 GB RSS and a 1.0 GB
124
+ index — see [`bench/`](https://github.com/330899935/apiary-memory/tree/main/bench) for the
125
+ script and raw output.
126
+
103
127
  ## Install
104
128
 
105
129
  ```bash
106
- pip install memory-hive-mcp # the server: memory-hive-mcp
107
- # the human's CLI: memory-hive-mcp-cli
130
+ pip install apiary-memory # the server: apiary-memory (was memory-hive-mcp)
131
+ # the human's CLI: apiary-memory-cli (was memory-hive-mcp-cli)
108
132
  ```
109
133
 
110
134
  Python 3.8 or newer. There is nothing else to install — the package uses only the standard
@@ -128,8 +152,8 @@ is optional.
128
152
  ```json
129
153
  {
130
154
  "mcpServers": {
131
- "memory-hive": {
132
- "command": "memory-hive-mcp",
155
+ "apiary-memory": {
156
+ "command": "apiary-memory",
133
157
  "env": { "HIVE_MODE": "local" }
134
158
  }
135
159
  }
@@ -142,6 +166,58 @@ is optional.
142
166
  with the headers `X-Hive-Agent` and `X-Hive-Token`. This package is the stdio path; the HTTP
143
167
  endpoint belongs to the app.
144
168
 
169
+ ## Two ways to connect
170
+
171
+ There are two doors onto the same memory. Which one you use depends on **where your AI runs**,
172
+ not on what it can do.
173
+
174
+ | | Local (MCP) | Web (HTTP) |
175
+ | --- | --- | --- |
176
+ | Built for | AIs installed on your Mac | AIs running on someone else's servers |
177
+ | How you connect | a stdio command in a config file | paste one address |
178
+ | Network | none — never leaves the machine | public, relayed by Cloudflare |
179
+ | Available since | this package, 0.1.0 | Desktop app **1.4.8** |
180
+
181
+ Behind both doors is the same home: what a local AI stores today, a web AI can read tomorrow —
182
+ and the other way round. **Swap in a hundred AIs; there is still one memory, and it is on your
183
+ disk.**
184
+
185
+ ### The web (HTTP) door
186
+
187
+ An AI running on the web cannot reach your Mac. So the Desktop app opens a channel outwards.
188
+ In the app, open **AI Connect · Web (HTTP)**, pick one of three levels, and copy the address:
189
+
190
+ | Level | Public? | Address stable? | Use when |
191
+ | --- | --- | --- | --- |
192
+ | **Local web** | no | — | the AI runs on the same machine |
193
+ | **Quick tunnel** | yes | no | you want a web AI in without owning a domain |
194
+ | **Fixed address** | yes | yes | long-term use; needs your own Cloudflare account |
195
+
196
+ **If local works, do not open a tunnel.** That is what the app tells you, and it is our advice
197
+ here too: if local is enough, do not open the door onto the street.
198
+
199
+ Three things to know before you connect:
200
+
201
+ 1. **Once connected, the AI can read your memory.** It gets what it asks for, within what it is
202
+ allowed to see.
203
+ 2. **Over the public internet your data is relayed by Cloudflare — it is not end-to-end
204
+ encrypted to the app.** What is stored and what is computed stay on your Mac, but the traffic
205
+ passes through Cloudflare.
206
+ 3. **The four privacy vaults and the cognition layer are never opened to outside AIs — that is
207
+ a wall, not a switch.** No matter which level you open, they are not part of it.
208
+
209
+ **Which AIs?** Any client that supports remote MCP works — read-only, public vaults only. One
210
+ caveat: ChatGPT uses Custom GPT Actions (OpenAPI), a different mechanism from MCP. An address
211
+ alone will not work there, and that step is not built yet.
212
+
213
+ ### Why `transport` still says `stdio`
214
+
215
+ The package and the MCP Registry entry both declare `"transport": {"type": "stdio"}`. That is
216
+ accurate and stays that way: **this package _is_ the stdio bridge.** The web (HTTP) door is a
217
+ capability of the Desktop app, not of this package. Declaring `http` here would make clients
218
+ dial an endpoint the package does not serve, and the connection would simply fail — so the door
219
+ is documented above rather than declared as a package transport.
220
+
145
221
  ## Prerequisite
146
222
 
147
223
  **None, for the local store** — install the package and it works. A running app is a prerequisite
@@ -222,16 +298,16 @@ Agents propose. You confirm. The confirmation lives in a terminal, in a command
222
298
  type — deliberately not a tool an agent can call.
223
299
 
224
300
  ```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
301
+ apiary-memory-cli list # what is waiting
302
+ apiary-memory-cli show <id> # read one in full
303
+ apiary-memory-cli approve <id> # confirm it, or --all
304
+ apiary-memory-cli reject <id> # drop it for good
305
+ apiary-memory-cli search "deploy key" # search confirmed memory
306
+ apiary-memory-cli forget <id> # soft delete, reversible
307
+ apiary-memory-cli restore <id> # undo forget
308
+ apiary-memory-cli stats # counts and the database path
309
+ apiary-memory-cli export --out dump.json
310
+ apiary-memory-cli path
235
311
  ```
236
312
 
237
313
  `--db <path>` on any command points at a different database. `HIVE_DB` does the same from the
@@ -296,7 +372,7 @@ Written down because a memory tool that oversells itself is worse than one that
296
372
  ## Troubleshooting
297
373
 
298
374
  **"no confirmed memory matched this query" with entries pending.** Correct behaviour. Confirm
299
- them: `memory-hive-mcp-cli list`, then `approve`.
375
+ them: `apiary-memory-cli list`, then `approve`.
300
376
 
301
377
  **A call fails with a message about `HIVE_AGENT_ID`.** The app answered and refused the
302
378
  credential. The call did **not** fall back to the local store, on purpose. Register an agent in
@@ -305,7 +381,7 @@ the app and set both variables, or set `HIVE_MODE=local` if you meant to use the
305
381
  **"Hive app not reachable ... and HIVE_MODE=remote forbids the local fallback".** You asked for
306
382
  the app only and it is not running. Start it, or drop `HIVE_MODE=remote`.
307
383
 
308
- **Where did my memory go?** `memory-hive-mcp-cli stats` prints the database path. If `HIVE_MODE`
384
+ **Where did my memory go?** `apiary-memory-cli stats` prints the database path. If `HIVE_MODE`
309
385
  is `auto` and the app is running, the app has been answering — the local file is untouched by
310
386
  design.
311
387
 
{apiary_memory-0.2.0 → apiary_memory-0.2.1}/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.1"
26
26
 
27
27
  __all__ = ["__version__"]
{apiary_memory-0.2.0 → apiary_memory-0.2.1}/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.1}/LICENSE RENAMED
File without changes
{apiary_memory-0.2.0 → apiary_memory-0.2.1}/setup.cfg RENAMED
File without changes