Skip to main content
Glama

Apiary Memory MCP

Listed on mcpservers.org

The problem it solves

You explain your project to one AI today. Next week you explain it again to a different one, from scratch — because each tool keeps its own memory, and none of that memory is yours to move.

This is a memory box that sits on your own disk. Any MCP-capable AI can read it. An agent can propose what to remember, but nothing is written until you approve it. Switch to another AI next month and the memory stays where it was — it was never the AI's to begin with.

Related MCP server: Lumena MCP Server

At a glance

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.

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.

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.

What is open

Only this MCP integration layer is open source (MIT, ~2k lines, standard library only). The macOS and iOS apps are closed source, signed and shipped through the App Store. A licence badge on PyPI says nothing about the apps.

Full product

A GUI desktop app, free on the Mac App Store — installed in two clicks, no terminal needed. It adds a multi-AI workbench (who is working, what is being relayed, what is waiting on you) and nothing is stored until you confirm. This repository is only the MCP server inside that product.

Install

pip install apiary-memory · or, inside Claude Desktop, double-click apiary-memory-0.2.1.mcpb (manifest frozen at 0.2.1 and not rebuilt since — it runs the 0.2.1 code; install from PyPI for anything newer)

Version

0.2.5 on PyPI · desktop app 1.5.0 · iOS app 1.5.0

The rest of the product

https://hello-fengchao.com · https://hello-fengchao.com/llms.txt (for AI readers: what this is and is not, in one page)

Two entry points — and they are not the same

Command

What it is

What happens when you run it

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.

apiary-memory-cli

The human CLI

list pending candidates · approve <id> commit one · search <query> · stats show where the DB lives

python -m hive_mcp does not work — this package has no __main__.py.

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.

Search is not the same at both ends

Most wrong answers about us come from this one: the pip package and the macOS app do not search the same way.

End

How it searches

What that means in practice

pip package

Lexical only — words for Latin script, overlapping character bigrams for Chinese. No embeddings, no vector index.

If the words don't overlap, it finds nothing. Asking in your own words often fails.

macOS app 1.5.0+

BM25 plus a local vector model, fused with RRF. A ~100 MB ONNX model ships inside the app. Offline, no API key.

You can ask by meaning. If the model is missing or fails to load, it silently falls back to lexical.

"This product has no semantic search" is true only of the pip package. "It ranks by meaning" is true only of the macOS app. Answering with either sentence alone will be half wrong.

The human end (what the apps do, plainly)

  • Desktop app — macOS 10.15+, free on the Mac App Store. Two clicks, no terminal. Drop in text, images, PDFs or chat logs; words inside images are recognised, audio and video are transcribed. Anything an agent sends lands in a pending queue first — nothing is written until you approve it. Private entries go into an encrypted vault.

  • Pocket app — iOS 17.0+, completely free. Record a thought on the phone and it syncs home to your own computer. No account, no login, nothing stored on our side.

  • Price. The desktop app is free to download; advanced features are an optional in-app subscription, shown inside the app. The iOS app has no in-app purchase, no subscription, no login.

This is not a service you sign up for — it is a program you install. There is no Windows desktop app.

Not to be confused with

Name

Status

hive-memory

Does not exist on PyPI (404). Any document citing it is wrong — including AI answers about us.

memory-hive-mcp

Our own former name. Still installs, but caps at 0.1.9. Use pip install apiary-memory for the current release.

hive-mcp

Someone else's Claude Code plugin.

hive.com

Team collaboration software.

theapiary.sh

"the apiary" — shared memory for AI coding agents; its memory component is called honeycomb.

apiarybee.com

"Apiary" — a self-organizing agent framework.

记忆蜂巢 (Chengdu Zhixin Hualao)

An unrelated iOS group-chat app. Same four characters, nothing else in common.

Also known as: Apiary Memory · 记忆蜂巢 · Memory Hive · 蜂巢 · apiary-memory on PyPI · io.github.330899935/apiary-memory on the MCP Registry (from v0.2.0).

The one worth a second look is theapiary.sh — it is also memory for AI agents, so answers tend to merge the two. The difference in one line: theirs is shared across agents; this one is local to one person, in one SQLite file on that person's own disk, and every write waits for that person to confirm.

Your agents can search what you have confirmed and propose what they think you should keep; only you can confirm it. Everything lives in one file on your own disk, and nothing is sent anywhere.

It runs on its own. A working SQLite memory store ships inside this package — no account, no cloud, no daemon, no dependencies.

pip install apiary-memory

No terminal, inside Claude Desktop: double-click apiary-memory-0.2.1.mcpb. Its manifest is frozen at 0.2.1 and the bundle has not been rebuilt since — it runs the 0.2.1 code. For anything newer, use pip install apiary-memory.

Not the app. A .mcpb file is a Claude Desktop extension bundle, not the macOS app. The app is a separate download from the Mac App Store.

Measured on 2026-10-27, on one MacBook with the Hive running locally — script and raw output in bench/:

Measure

Result

Search latency

p95 111 ms, p50 76 ms (warm, includes HTTP)

Retrieval

correct entry in top-5 for 97.5% of 40 trials

Corpus

1,303 entries · 2.39 M chars · 45 days, plaintext only

Retrieval used each entry's own title as the query — an easy set. It shows the index is complete and ranks correctly on exact terms, not how well it answers a question asked in your own words. Run bench/bench_search.py on your own Hive.


What you get without the app

A complete, if modest, memory server. On a machine with nothing else installed:

Call

What happens

initialize

answered locally, protocol 2024-11-05

tools/list

answered locally, six tools

propose

writes to a real database on your disk

recall

searches that database and returns ranked entries

get_context

a digest of what you confirmed most recently

manage

read one entry, list what is pending, forget, restore

say / board

a shared message board for coordinating several agents

Storage is SQLite at ~/.memory-hive/hive.db by default. Search is lexical — character bigrams for Chinese, words for Latin script — so it ranks well when the words overlap and finds nothing when they do not. There are no embeddings and no vector index. Every response says "mode": "local" so you can always tell which engine answered.

Without the app, the database is plain SQLite: it is not encrypted. That is stated here rather than discovered later — see Honest limits.

What the app adds

Apiary Memory for macOS is the same design with the expensive parts built: eight vaults with four of them locked behind a PIN — the app's UI calls the same credential the privacy password (隐私区密码); one thing, two names — wrapping an Argon2id-derived key with AES-256 at rest, a daily evolution log, multi-agent identity management, and a UI for reading and confirming. It also answers MCP itself, with richer ranking.

If the app is running, this package uses it and leaves the local file alone. If it is not, the local store answers. You do not have to choose up front:

HIVE_MODE

Behaviour

auto (default)

Ask the app. Use the local store only if the app is unreachable.

local

Never touch the network. Always use the local store.

remote

Only the app. A connection failure is an error, not a reroute.

One rule holds in every mode: if the app is running and answers with an error, that error is returned unchanged. Falling back on a refusal would write your memory into a second database while your client believed it had reached the app. Silent data forking is worse than an error message, so a reply from the app is final. The fallback fires on a connection failure, and on nothing else.

Measured on the app

The numbers below come from the macOS app's local HTTP service on one MacBook — not from this package's SQLite store, which is a different engine over a different dataset. Mixing the two would be the usual benchmark trick, so they are kept apart.

Store size (four plaintext vaults)

1,356 entries, 2.52M chars, 47 distinct days

Retrieval hit rate

Top-5 92.5%, Top-20 95.0% (n=40)

Latency (local HTTP, incl. round trip)

p50 90 ms, p95 127 ms

Measured 2026-10-29 against the live service. The hit-rate queries were each entry's own title — the easy case. It shows the index is complete; it does not show that free-form questions land. A separate pilot using plainly-phrased questions found the right entry in the top 5 only twice out of roughly a dozen, which is the biggest known weakness of this version.

The four encrypted vaults are excluded from the count because they are unreadable by design. A load test at 1,000,000 synthetic entries gave 0.6 s warm search, 5.3 GB RSS and a 1.0 GB index — see bench/ for the script and raw output.

Install

pip install apiary-memory        # the server: apiary-memory (was memory-hive-mcp)
                                 # the human's CLI: apiary-memory-cli (was memory-hive-mcp-cli)

Python 3.8 or newer. There is nothing else to install — the package uses only the standard library, and sqlite3 is part of it.

From a checkout:

git clone https://github.com/330899935/apiary-memory
cd apiary-memory
PYTHONPATH=src python -m hive_mcp.stdio

Connect a client

Any MCP host that can run a stdio command will work. The minimum is the command; everything else is optional.

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "apiary-memory": {
      "command": "apiary-memory",
      "env": { "HIVE_MODE": "local" }
    }
  }
}

Cursor — ~/.cursor/mcp.json, same mcpServers shape.

Any host that only speaks HTTP — start the app and point it at http://127.0.0.1:8768/mcp with the headers X-Hive-Agent and X-Hive-Token. This package is the stdio path; the HTTP endpoint belongs to the app.

Two ways to connect

There are two doors onto the same memory. Which one you use depends on where your AI runs, not on what it can do.

Local (MCP)

Web (HTTP)

Built for

AIs installed on your Mac

AIs running on someone else's servers

How you connect

a stdio command in a config file

paste one address

Network

none — never leaves the machine

public, relayed by Cloudflare

Available since

this package, 0.1.0

Desktop app 1.5.0

Behind both doors is the same home: what a local AI stores today, a web AI can read tomorrow — and the other way round. Swap in a hundred AIs; there is still one memory, and it is on your disk.

The web (HTTP) door

An AI running on the web cannot reach your Mac. So the Desktop app opens a channel outwards. In the app, open AI Connect · Web (HTTP), pick one of three levels, and copy the address:

Level

Public?

Address stable?

Use when

Local web

no

—

the AI runs on the same machine

Quick tunnel

yes

no

you want a web AI in without owning a domain

Fixed address

yes

yes

long-term use; needs your own Cloudflare account

If local works, do not open a tunnel. That is what the app tells you, and it is our advice here too: if local is enough, do not open the door onto the street.

Three things to know before you connect:

  1. Once connected, the AI can read your memory. It gets what it asks for, within what it is allowed to see.

  2. Over the public internet your data is relayed by Cloudflare — it is not end-to-end encrypted to the app. What is stored and what is computed stay on your Mac, but the traffic passes through Cloudflare.

  3. The four privacy vaults and the cognition layer are never opened to outside AIs — that is a wall, not a switch. No matter which level you open, they are not part of it.

Which AIs? Any client that supports remote MCP works — read-only, public vaults only. One caveat: ChatGPT uses Custom GPT Actions (OpenAPI), a different mechanism from MCP. An address alone will not work there, and that step is not built yet.

Why transport still says stdio

The package and the MCP Registry entry both declare "transport": {"type": "stdio"}. That is accurate and stays that way: this package is the stdio bridge. The web (HTTP) door is a capability of the Desktop app, not of this package. Declaring http here would make clients dial an endpoint the package does not serve, and the connection would simply fail — so the door is documented above rather than declared as a package transport.

Prerequisite

None, for the local store — install the package and it works. A running app is a prerequisite only for the app's own features: encrypted vaults, the evolution log, and multi-agent identity. If you want those, install the Hive app (macOS, version 1.4.5 or newer) and leave HIVE_MODE at auto.

The six tools

The six tools are the whole surface. They are the same six whether the app or the local store answers; only the ranking behind them differs — and, for two inputs, whether they exist at all. The app accepts precomputed embeddings (recall.query_vector, propose.vector); the local store has no embedder, so tools/list omits those two wherever the local store can answer, including under auto where the app might stop answering mid-session. A field that would be accepted and silently ignored is not advertised at all.

The same rule covers wording. recall.query is described as the lexical ranker it is wherever the local store can answer — words and character bigrams, no embeddings — and as the app's index-based ranking with query_vector for meaning wherever only the app can answer. A description is a claim about what will happen to the input, so it is narrowed with the inputs.

Defaults are not narrowed, they are shared. Omit limit and you get 10 from recall and 8 from get_context; omit compact and bodies come back trimmed; omit ttl on say and the card lives 24 hours. Both engines answer those numbers identically, because a default is a number in the schema rather than a capability one engine lacks. store.py holds each one as a named constant, and the tests compare the answer against the advertised number instead of a second hand-written copy of it.

Tool

Kind

What it is for

recall

read

Search confirmed memory by topic. {"query": "..."} plus optional limit, vaults, compact.

propose

write

Submit a memory for the human to approve. Lands in a queue; changes no confirmed memory.

manage

read/write

Address one entry: list_pending, get_by_id, forget, restore, discard_pending.

get_context

read

A short digest of recent confirmed memory, to seed a conversation.

say

write

Post to the shared board so other agents see what was done or handed over.

board

read

Read the board, optionally only what arrived since your last cursor.

Two properties are worth stating plainly, because they are the product:

  • propose succeeding means "queued", not "stored". recall will not return it until a human confirms it.

  • manage has no approve action. There is no path from an agent to a confirmed memory. That is not an omission; it is the design.

Response shapes

tools/list is one surface for both engines, and an answer should be too: a model that has to branch on which engine replied will eventually branch wrong. board therefore answers the app's shape, field for field — items, unread, count, cursor, reader — and cursor is the id of the newest card, the same kind of value the app returns.

The cursor is what a poll carries across an engine switch, which is why it gets the space. Under auto one call can be answered by the app and the next by the local store. Before 0.1.9 the local engine answered a float epoch timestamp and read the app's card id with float(), so a cursor fetched from the app came back as a full re-read of the board and nothing said so; a float sent the other way matched no card id, and the app answered with its newest limit, equally quietly.

A cursor can still fail to resolve: its card expired (cards live 24 hours by default), or it was issued by the other engine, whose ids are CB… in the app and msg_… here. Neither engine can resume from that, so both return the newest window — but this one also sets since_unknown and a note saying which of those happened. unread counts every live card after the cursor and count counts what the answer carries, so unread > count means the page did not cover everything waiting, and the note says so in words.

Three shapes are not unified, because the engines really do hold different data:

  • a recall entry names its vault vault from the local store and wh from the app;

  • get_context returns one flat digest locally and one bucket per warehouse (context, keyed by warehouse name) from the app;

  • roster entries share agent_id; locally they also carry messages and last_seen, while the app adds its registry card — display name, seat, leases, current task — which a SQLite file has no way to know.

Confirming what agents propose

Agents propose. You confirm. The confirmation lives in a terminal, in a command you have to type — deliberately not a tool an agent can call.

apiary-memory-cli list                 # what is waiting
apiary-memory-cli show <id>            # read one in full
apiary-memory-cli approve <id>         # confirm it, or --all
apiary-memory-cli reject <id>          # drop it for good
apiary-memory-cli search "deploy key"  # search confirmed memory
apiary-memory-cli forget <id>          # soft delete, reversible
apiary-memory-cli restore <id>         # undo forget
apiary-memory-cli stats                # counts and the database path
apiary-memory-cli export --out dump.json
apiary-memory-cli path

--db <path> on any command points at a different database. HIVE_DB does the same from the environment.

Where your memory lives

~/.memory-hive/hive.db, unless HIVE_DB says otherwise. One SQLite file; copy it to back it up, delete it to start over.

The board keeps its messages in the same file, so there is only ever one thing to back up. Cards expire: 24 hours unless ttl says otherwise, clamped to between 60 seconds and 30 days, which is what the app does too — a board that grows forever stops being a board.

How search works, and what it does not do

Chinese text is indexed as single characters plus overlapping character bigrams; Latin text as words. A query is scored by how much of it the entry covers, then nudged by recency — a 10% multiplier, enough to break ties and not enough to overturn relevance.

This is a ranker, not an understander.

  • Scores are relative. 0.8 means "closer than 0.4 for this query", not "80% confident". They are not comparable across queries.

  • No semantic recall. Ask about "money" and an entry that only says "invoice" will not be found. Related-word coverage needs an embedder; this package has no dependencies and does not pretend otherwise.

  • The ranking is the one the description states. tools/list says "words and character bigrams ... no embeddings" here, and that sentence is true of this engine. It is narrowed per engine like the embedding inputs are, because the app's answer to the same question differs.

  • A miss is reported as a miss. When nothing matches, recall says so and mentions how many entries are awaiting confirmation, rather than returning a plausible neighbour.

Configuration

Variable

Default

Purpose

HIVE_MODE

auto

auto, local, or remote — see the table above

HIVE_DB

~/.memory-hive/hive.db

Where the local database lives

HIVE_MCP_URL

http://127.0.0.1:8768/mcp

The app's endpoint

HIVE_AGENT_ID

—

Agent id from the app; only for calls the app serves

HIVE_AGENT_TOKEN

—

Access token from the app; only for calls the app serves

HIVE_AGENT_ID and HIVE_AGENT_TOKEN are not required to use the local store. They are read straight from the environment and never written to disk by this package.

Honest limits

Written down because a memory tool that oversells itself is worse than one that does less.

  1. The local store is not encrypted. Plain SQLite. Anyone who can read your home directory can read it. The app's vaults are the encrypted option, and stats reports "encrypted": false instead of leaving you to find out.

  2. No semantic search, as above.

  3. One writer at a time. WAL mode lets the CLI confirm while a server is connected, but this is a personal memory file, not a multi-host service. Do not point two machines at one database over a network share.

  4. The board is coordination, not memory. Messages are for hand-offs between agents; they are not searchable with recall.

  5. The app is macOS only. The local store is not — it is pure Python.

Troubleshooting

"no confirmed memory matched this query" with entries pending. Correct behaviour. Confirm them: apiary-memory-cli list, then approve.

A call fails with a message about HIVE_AGENT_ID. The app answered and refused the credential. The call did not fall back to the local store, on purpose. Register an agent in the app and set both variables, or set HIVE_MODE=local if you meant to use the local file.

"Hive app not reachable ... and HIVE_MODE=remote forbids the local fallback". You asked for the app only and it is not running. Start it, or drop HIVE_MODE=remote.

Where did my memory go? apiary-memory-cli stats prints the database path. If HIVE_MODE is auto and the app is running, the app has been answering — the local file is untouched by design.

Development

PYTHONPATH=src python -m unittest discover -s tests -v

The suite needs no running app and no network: it stands up its own fake backend where a real response is required, and points HIVE_DB at a temporary file so a test never touches a real memory database.

Layout:

src/hive_mcp/store.py   the memory engine (SQLite, stdlib only)
src/hive_mcp/stdio.py   the MCP server: routing, envelopes, the app bridge
src/hive_mcp/cli.py     the human's half: review and confirm
src/hive_mcp/tools.json the tool surface snapshot for the offline path

License

MIT. Your memory file is yours; nothing here phones home.

Available Tools

6 tools
boardRead the shared boardA
Read-onlyIdempotent

Read the shared board, optionally only what arrived since your last read. Use it to poll for messages or hand-offs addressed to you. To post, use say. Pass the previous cursor as since so a poll returns only new messages instead of the whole board. Annotations declare this read-only; note that messages expire, so an empty result can mean nothing was posted or that earlier messages have aged out.

Inputs: limit, since, roster.

get_contextGet session contextA
Read-onlyIdempotent

Pull a short digest of recent memory from the human's active threads and open tasks, to seed a conversation before they ask anything. Call this once at session start. For answering a specific question, use recall instead, since that searches all confirmed memory rather than only what is recent. For entries still awaiting approval, use manage with action list_pending. Annotations already declare this read-only; what they cannot say is that the digest reflects the most recent activity, so two calls minutes apart may differ.

Inputs: limit.

manageManage stored memoriesA

Inspect or change the lifecycle of a specific stored memory, addressed by id or by queue state. Use list_pending to review what is awaiting the human's approval, and get_by_id to read one entry in full. forget soft-deletes and is reversible with restore; discard_pending permanently drops an entry that was never confirmed. To search confirmed memory by topic instead of by address, use recall. Except for discard_pending, every action here is reversible, which is why this is not marked destructive.

Inputs: action (required), id.

proposePropose a memoryA

Submit a memory for the human to approve. It lands in a pending queue and changes no confirmed memory. Use it when the human says to remember something, or when a decision is reached that will still matter later. Do not use it as a scratchpad for transient reasoning or for data you merely fetched. This tool cannot confirm its own writes: the entry stays pending until the human accepts it inside their own Hive, so a success response means queued, not stored. Supply client_id to make retries idempotent.

Inputs: content (required), tags, title, vault, +1 more.

recallRecall memoryA
Read-onlyIdempotent

Search the human's confirmed memory by natural-language query and return the closest stored entries. Use this to find what was previously decided, recorded, or agreed. Do not use it at session start when you have no query yet - use get_context instead. Do not use it to review entries still awaiting approval - use manage with action list_pending. Annotations already declare this read-only, so this text covers what they cannot: results come from the confirmed store only, private vaults are omitted for agents not permitted to read them, and an empty list means no match rather than no memory.

Inputs: query (required), limit, vaults, compact.

sayPost to the shared boardA

Post a message to the shared board so the human and other agents see what was done or what is being handed over. Use it when finishing a unit of work, or to hand work to another agent. Do not use it to report routine steps the human did not ask about - the human reads this board. To read what others have posted, use board. Identity comes from your credential, so a caller cannot post as another agent.

Inputs: summary (required), to, ttl, kind, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: recall searches confirmed memory, get_context seeds a session, propose queues new memory, manage handles lifecycle by id/queue state, and say/board write and read the shared board. Descriptions explicitly cross-reference each other to resolve the few tempting confusions (recall vs get_context vs manage list_pending), so an agent can select reliably.

    Naming Consistency3/5

    Names mix bare verbs (recall, propose, say, manage), a bare noun (board), and a verb_noun form (get_context), so there is no single predictable pattern. Every name is still readable and memorable, so the inconsistency is stylistic rather than harmful.

    Tool Count5/5

    Six tools is well matched to a memory server with a shared board: one each for search, session seeding, proposal, lifecycle management, board write, and board read. No tool looks redundant and none of the needed operations are crammed together beyond manage's clearly enumerated actions.

    Completeness4/5

    The memory lifecycle is well covered end to end: propose, discover via recall/get_context, review pending, read by id, soft-delete with restore, and discard. The main gaps are the absence of any way to edit a pending or confirmed entry's content and no richer board operations (e.g., replying to or addressing a specific message), which agents can mostly work around.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      A
      maintenance
      Provides AI agents with a human-inspired memory layer via MCP, enabling episodic and semantic memory recall, forgetting curves, consolidation, and contradiction detection. It integrates with MCP clients to offer local-first, dependency-free memory management.
      98
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to store, search, assemble, and manage local-first memories through seven MCP tools, including conversation turns, feedback, status, and dashboard access without cloud dependencies.
      AGPL 3.0
    • F
      license
      A
      quality
      B
      maintenance
      Shared fleet memory for AI agents — what one agent learns, the whole fleet knows. Nightly self-correction: stale facts rewritten in place, duplicates merged. Recall pushed into every prompt in supported coding agents. Self-hosted.
      11
      3
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides persistent memory for AI agents via MCP, enabling agents to store and access notes, files, and session context across sessions and clients while under user control.
      4
      MIT