apiary-memory 0.2.0__py3-none-any.whl

apiary_memory-0.2.0.dist-info/METADATA

@@ -0,0 +1,333 @@
+Metadata-Version: 2.4
+Name: apiary-memory
+Version: 0.2.0
+Summary: Local-first memory your AI agents share over MCP. Ships a working SQLite memory store; agents propose, only you confirm.
+Author: Apiary
+License-Expression: MIT
+Project-URL: Homepage, https://hello-fengchao.com
+Project-URL: Repository, https://github.com/330899935/apiary-memory
+Project-URL: App (macOS), https://apps.apple.com/app/id6806992983
+Project-URL: Source, https://github.com/330899935/apiary-memory
+Project-URL: Changelog, https://github.com/330899935/apiary-memory/blob/main/CHANGELOG.md
+Keywords: mcp,mcp-server,model-context-protocol,memory,ai-memory,local-first,privacy,ai-agents,claude,cursor
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Apiary Memory MCP
+
+<!-- mcp-name: io.github.330899935/apiary-memory -->
+
+> **Also known as:** Apiary Memory · 记忆蜂巢 · Memory Hive · 蜂巢 ·
+> `io.github.330899935/apiary-memory` (MCP Registry name, from v0.2.0) ·
+> `hive-memory` (Registry name up to v0.1.9) · `memory-hive-mcp` (PyPI package until the rename ships).
+> Not affiliated with [hive.com](https://hive.com) (team collaboration) or the `hive-mcp` Claude Code plugin.
+
+**Local-first personal memory for AI agents, over MCP.** 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.
+
+```bash
+pip install memory-hive-mcp
+```
+
+**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.
+
+Measured on 2026-10-27, on one MacBook with the Hive running locally — script and raw output in [`bench/`](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`](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](#honest-limits).
+
+## What the app adds
+
+[Apiary Memory for macOS](https://apps.apple.com/app/id6806992983) is the same design with the
+expensive parts built: eight vaults with four of them locked behind a PIN (Argon2id-wrapped key,
+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.
+
+## Install
+
+```bash
+pip install memory-hive-mcp      # the server: memory-hive-mcp
+                                 # the human's CLI: 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:
+
+```bash
+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`:
+
+```json
+{
+  "mcpServers": {
+    "memory-hive": {
+      "command": "memory-hive-mcp",
+      "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.
+
+## 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](https://apps.apple.com/app/id6806992983) (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.
+
+```bash
+memory-hive-mcp-cli list                  # what is waiting
+memory-hive-mcp-cli show <id>             # read one in full
+memory-hive-mcp-cli approve <id>          # confirm it, or --all
+memory-hive-mcp-cli reject <id>           # drop it for good
+memory-hive-mcp-cli search "deploy key"   # search confirmed memory
+memory-hive-mcp-cli forget <id>           # soft delete, reversible
+memory-hive-mcp-cli restore <id>          # undo forget
+memory-hive-mcp-cli stats                 # counts and the database path
+memory-hive-mcp-cli export --out dump.json
+memory-hive-mcp-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: `memory-hive-mcp-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?** `memory-hive-mcp-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
+
+```bash
+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.

apiary_memory-0.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+apiary_memory-0.2.0.dist-info/licenses/LICENSE,sha256=kwXchfjPJ2R49aF-zCdP12sI3OYdyDW_uthCJexjqXU,1063
+hive_mcp/__init__.py,sha256=LzQ0LqdfvE8bmGg11vQ80dmbrz5Ec3XyBQt6YBuEgsA,1226
+hive_mcp/cli.py,sha256=CWZPneoatJU3gX9dYaJ82B2kNqPD8wzYcbij3Phg7qs,8333
+hive_mcp/stdio.py,sha256=H857H_nEtPkbWAfZT3AjUogWNYXZAZ2Pf6cfjmjOgxQ,34610
+hive_mcp/store.py,sha256=MshvlDhbUe_cPf-yb3Q7SYIB0ncOc0MhQEvcplZ9oPk,34737
+hive_mcp/tools.json,sha256=m9JxRZYEPeLwSYAqQq0EpdsdMc-nog1MbZCN1UUZWFM,11282
+apiary_memory-0.2.0.dist-info/METADATA,sha256=emOIXQCMmfgyJMXhL7hod475DO4n9OgJwcN6hhWUqC8,16268
+apiary_memory-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+apiary_memory-0.2.0.dist-info/entry_points.txt,sha256=svhXTSVWA33LISqJN1kdjC4GMa0_LSohB23krU70XxI,170
+apiary_memory-0.2.0.dist-info/top_level.txt,sha256=8e2OeA9AuF6RCutfQuevEH-LxCEW6k0nGqteEkIheAk,9
+apiary_memory-0.2.0.dist-info/RECORD,,

apiary_memory-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

apiary_memory-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+apiary-memory = hive_mcp.stdio:main
+apiary-memory-cli = hive_mcp.cli:main
+memory-hive-mcp = hive_mcp.stdio:main
+memory-hive-mcp-cli = hive_mcp.cli:main

apiary_memory-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Apiary
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

apiary_memory-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+hive_mcp

hive_mcp/__init__.py

@@ -0,0 +1,27 @@
+"""hive_mcp — local-first personal memory for AI agents, served over MCP.
+
+Three modules, deliberately separate:
+
+* :mod:`hive_mcp.store` — the memory engine itself. A SQLite file on the user's
+  disk: ``propose`` queues, ``recall`` ranks, nothing is confirmed without the
+  human. Pure standard library.
+* :mod:`hive_mcp.stdio` — the MCP server. Serves :mod:`hive_mcp.store`, and
+  prefers the Hive app when it is running (see ``HIVE_MODE``).
+* :mod:`hive_mcp.cli` — the human's half. Reviewing proposals and confirming
+  them is deliberately *not* reachable over MCP.
+
+None of these is imported here. Importing ``hive_mcp.stdio`` at package level
+makes ``python -m hive_mcp.stdio`` emit ``RuntimeWarning: 'hive_mcp.stdio'
+found in sys.modules after import of package 'hive_mcp'`` on stderr, because
+the submodule is already loaded by the time runpy executes it. A stdio server
+must keep stderr free of noise: hosts and directory crawlers capture stderr to
+report "server errors", and a warning that appears on every run trains them to
+ignore the channel that matters.
+
+Use ``memory-hive-mcp`` and ``memory-hive-mcp-cli``, or
+``from hive_mcp.stdio import main``.
+"""
+
+__version__ = "0.2.0"
+
+__all__ = ["__version__"]

hive_mcp/cli.py

@@ -0,0 +1,261 @@
+"""hive_mcp.cli — the human's half of the loop.
+
+The MCP tool surface has no ``approve`` action, by design: an agent may propose
+but only a person may confirm. That gate is worthless if the person has no way
+to open it, so the gate lives here, in a terminal, run by whoever owns the
+machine. Nothing in this module is reachable over MCP.
+
+Typical use::
+
+    $ memory-hive-mcp-cli list
+      2 entries awaiting approval
+        mem_1791972802_qw4y  2 minutes ago  current
+          "The deploy key rotates on the first Monday of each month."
+
+    $ memory-hive-mcp-cli approve mem_1791972802_qw4y
+      approved 1 entry
+
+    $ memory-hive-mcp-cli search deploy
+      1 result
+        mem_1791972802_qw4y  0.87  current  "The deploy key rotates on the ..."
+
+Commands: list, show, approve, reject, search, forget, restore, stats, export,
+path. Exit code is 0 on success and 1 on a caller error, so it composes with
+``&&`` in a shell.
+"""
+
+import argparse
+import json
+import sys
+
+from hive_mcp import __version__
+from hive_mcp.store import (
+    PENDING,
+    Store,
+    StoreError,
+    default_db_path,
+)
+
+
+def _store(args):
+    return Store(getattr(args, "db", None))
+
+
+def _print(text=""):
+    sys.stdout.write(text + "\n")
+
+
+def cmd_list(args):
+    store = _store(args)
+    data = store.list_pending(limit=args.limit)
+    if not data["total"]:
+        _print("nothing awaiting approval")
+        return 0
+    _print("%d entr%s awaiting approval" % (data["total"], "y" if data["total"] == 1 else "ies"))
+    for entry in data["pending"]:
+        _print("  %s  %s  %s" % (entry["id"], entry["created"] or "", entry["vault"]))
+        _print('    "%s"' % entry["excerpt"])
+    if data["total"] > data["returned"]:
+        _print("  ... %d more (raise --limit)" % (data["total"] - data["returned"]))
+    _print("")
+    _print("approve: memory-hive-mcp-cli approve <id>   reject: memory-hive-mcp-cli reject <id>")
+    return 0
+
+
+def cmd_show(args):
+    store = _store(args)
+    data = store.get_by_id(args.id)
+    _print("id      %s" % data["id"])
+    _print("state   %s" % data["state"])
+    _print("vault   %s" % data["vault"])
+    _print("created %s" % (data["created"] or ""))
+    if data["confirmed_at"]:
+        _print("confirm %s" % data["confirmed_at"])
+    if data["tags"]:
+        _print("tags    %s" % " ".join(data["tags"]))
+    _print("title   %s" % data["title"])
+    _print("")
+    _print(data["content"])
+    return 0
+
+
+def cmd_approve(args):
+    store = _store(args)
+    ids = store.approve(ids=None if args.all else args.ids, all_pending=args.all)
+    if not ids:
+        _print("nothing to approve")
+        return 0
+    _print("approved %d entr%s" % (len(ids), "y" if len(ids) == 1 else "ies"))
+    for mem_id in ids:
+        _print("  %s" % mem_id)
+    _print("")
+    _print("these are now searchable by recall")
+    return 0
+
+
+def cmd_reject(args):
+    store = _store(args)
+    for mem_id in args.ids:
+        store.drop_pending(mem_id)
+        _print("dropped %s" % mem_id)
+    return 0
+
+
+def cmd_search(args):
+    store = _store(args)
+    # Full bodies on purpose: this is the surface where a human reads the entry,
+    # and the store's default is now the MCP default (compact), which is the
+    # right answer for a model's context window and the wrong one here.
+    data = store.recall(
+        args.query, limit=args.limit, vaults=args.vault or None, compact=False
+    )
+    if not data["results"]:
+        _print("no confirmed memory matched %r" % args.query)
+        if data.get("note"):
+            _print(data["note"])
+        return 0
+    _print("%d result%s" % (data["total"], "" if data["total"] == 1 else "s"))
+    for entry in data["results"]:
+        _print("  %s  %.2f  %s" % (entry["id"], entry["score"], entry["vault"]))
+        _print('    "%s"' % entry["content"][:120].replace("\n", " "))
+    return 0
+
+
+def cmd_forget(args):
+    store = _store(args)
+    for mem_id in args.ids:
+        data = store.forget(mem_id)
+        _print("forgot %s (reversible with: memory-hive-mcp-cli restore %s)" % (mem_id, mem_id))
+    return 0
+
+
+def cmd_restore(args):
+    store = _store(args)
+    for mem_id in args.ids:
+        store.restore(mem_id)
+        _print("restored %s" % mem_id)
+    return 0
+
+
+def cmd_stats(args):
+    store = _store(args)
+    data = store.stats()
+    _print("database  %s" % data["database"])
+    _print("exists    %s" % ("yes" if data["exists"] else "no"))
+    _print("encrypted no (the local store is plain SQLite; the Hive app adds encryption)")
+    _print("confirmed %d" % data["memories"]["confirmed"])
+    _print("pending   %d" % data["memories"]["pending"])
+    _print("forgotten %d" % data["memories"]["discarded"])
+    _print("board     %d" % data["board_messages"])
+    return 0
+
+
+def cmd_export(args):
+    store = _store(args)
+    rows = store.conn.execute(
+        "SELECT id, state, title, content, vault, tags, created, confirmed_at"
+        " FROM memories ORDER BY created ASC"
+    ).fetchall()
+    payload = {
+        "exported_by": "memory-hive-mcp-cli %s" % __version__,
+        "mode": "local",
+        "memories": [
+            {
+                "id": r["id"],
+                "state": r["state"],
+                "title": r["title"],
+                "content": r["content"],
+                "vault": r["vault"],
+                "tags": (r["tags"] or "").split(),
+                "created": r["created"],
+                "confirmed_at": r["confirmed_at"],
+            }
+            for r in rows
+        ],
+    }
+    if args.out:
+        with open(args.out, "w", encoding="utf-8") as fh:
+            json.dump(payload, fh, ensure_ascii=False, indent=2)
+        _print("wrote %d memories to %s" % (len(payload["memories"]), args.out))
+    else:
+        _print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return 0
+
+
+def cmd_path(args):
+    _print(str(default_db_path()))
+    return 0
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="memory-hive-mcp-cli",
+        description=(
+            "Review and confirm what your agents proposed. The MCP surface can "
+            "only propose; confirming is a human action and lives here."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    parser.add_argument("--db", help="path to the memory database (default: %s)" % default_db_path())
+    sub = parser.add_subparsers(dest="command")
+
+    p = sub.add_parser("list", help="show entries awaiting approval")
+    p.add_argument("--limit", type=int, default=20)
+    p.set_defaults(func=cmd_list)
+
+    p = sub.add_parser("show", help="print one entry in full")
+    p.add_argument("id")
+    p.set_defaults(func=cmd_show)
+
+    p = sub.add_parser("approve", help="confirm entries so recall can find them")
+    p.add_argument("ids", nargs="*")
+    p.add_argument("--all", action="store_true", help="approve everything pending")
+    p.set_defaults(func=cmd_approve)
+
+    p = sub.add_parser("reject", help="permanently drop entries that were never confirmed")
+    p.add_argument("ids", nargs="+")
+    p.set_defaults(func=cmd_reject)
+
+    p = sub.add_parser("search", help="search confirmed memory")
+    p.add_argument("query")
+    p.add_argument("--limit", type=int, default=8)
+    p.add_argument("--vault", action="append")
+    p.set_defaults(func=cmd_search)
+
+    p = sub.add_parser("forget", help="soft-delete a confirmed entry (reversible)")
+    p.add_argument("ids", nargs="+")
+    p.set_defaults(func=cmd_forget)
+
+    p = sub.add_parser("restore", help="undo forget")
+    p.add_argument("ids", nargs="+")
+    p.set_defaults(func=cmd_restore)
+
+    p = sub.add_parser("stats", help="counts and database location")
+    p.set_defaults(func=cmd_stats)
+
+    p = sub.add_parser("export", help="dump every entry as JSON")
+    p.add_argument("--out")
+    p.set_defaults(func=cmd_export)
+
+    p = sub.add_parser("path", help="print the database path")
+    p.set_defaults(func=cmd_path)
+    return parser
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "func", None):
+        parser.print_help()
+        return 0
+    try:
+        return args.func(args)
+    except StoreError as exc:
+        sys.stderr.write("error: %s\n" % exc)
+        return 1
+    except BrokenPipeError:
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())