unibaseio-membase 0.3.0__tar.gz

unibaseio_membase-0.3.0/.gitignore

@@ -0,0 +1,54 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+venv/
+ENV/
+env/
+.env/
+.venv/
+.env
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Logs
+*.log
+logs/
+log/
+
+# OS specific
+.DS_Store
+Thumbs.db
+
+chroma_db/
+
+out/.pytest_cache/
+.ruff_cache/
+*.db
+
+typescript/dist/
+node_modules/
+cli/dist/

unibaseio_membase-0.3.0/LICENSE

@@ -0,0 +1,33 @@
+Membase SDK — Proprietary License
+
+Copyright (c) 2026 Unibase. All rights reserved.
+
+This software, including its source code, packages, documentation and assets (the "Software"),
+is proprietary to Unibase and is licensed, not sold.
+
+1. Use. Unibase grants you a non-exclusive, non-transferable, revocable license to install and
+   use the Software as published by Unibase (the `unibaseio-membase` package on PyPI and the
+   `@unibaseio/membase` and `@unibaseio/membase-cli` packages on npm), and to
+   include it as a dependency of your own applications, to access Membase services and the
+   Membase engine.
+
+2. Restrictions. Except as expressly permitted by this license or required by applicable law,
+   you may not: (a) redistribute, sublicense, sell, rent, lease, or otherwise make the Software
+   available to third parties on its own; (b) modify or create derivative works of the Software
+   other than for your own internal use; or (c) remove or alter any proprietary notices.
+
+3. Third-party components. Third-party components included with the Software are licensed
+   under their own terms, which govern those components.
+
+4. No warranty. 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.
+
+5. Limitation of liability. IN NO EVENT SHALL UNIBASE 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.
+
+6. Termination. This license terminates automatically if you breach it. On termination you
+   must stop using and delete all copies of the Software.
+
+For other licensing, contact Unibase.

unibaseio_membase-0.3.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: unibaseio-membase
+Version: 0.3.0
+Summary: Membase SDK: drop-in memory infrastructure for AI agents and apps, hosted or on your machine. Python client, CLI and MCP server.
+Project-URL: Homepage, https://www.unibase.com/memory
+Project-URL: Documentation, https://docs.membase.ai
+Project-URL: Repository, https://github.com/unibaseio/membase-ai
+Author: Unibase
+License: Proprietary
+License-File: LICENSE
+Keywords: agent-memory,agents,ai,llm,llm-memory,long-term-memory,mcp,membase,memory
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.25
+Provides-Extra: local
+Requires-Dist: mcp<2,>=1.0; extra == 'local'
+Requires-Dist: unibaseio-membase-core[all]>=0.3.0; (python_version >= '3.12') and extra == 'local'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/unibaseio/membase-ai/main/assets/membase-logo.png" width="72" alt="Membase">
+</p>
+
+<h1 align="center">Membase</h1>
+
+<p align="center">
+  <b>One memory. Every AI.</b><br>
+  Teach it once. Every AI remembers.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/unibaseio-membase/"><img src="https://img.shields.io/pypi/v/unibaseio-membase?label=pypi" alt="PyPI"></a>
+  <a href="https://www.npmjs.com/package/@unibaseio/membase"><img src="https://img.shields.io/npm/v/@unibaseio/membase?label=npm" alt="npm"></a>
+  <a href="https://github.com/unibaseio/membase-ai/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-proprietary-blue" alt="Proprietary"></a>
+</p>
+
+<p align="center">
+  <a href="https://www.unibase.com/memory">Website</a> ·
+  <a href="https://docs.membase.ai">Docs</a> ·
+  <a href="https://www.app.membase.ai">Web app</a> ·
+  <a href="https://discord.gg/nB9EfPGsSf">Discord</a> ·
+  <a href="https://x.com/Unibase_AI">X</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/unibaseio/membase-ai/main/assets/hero.svg" width="840" alt="Add sources, manage one memory, use it from every AI and app">
+</p>
+
+Membase keeps one memory for everything you and your agents know, and every AI you use reads it.
+You stop re-explaining yourself each time you switch models or tools.
+
+- **Add.** Facts, documents, web pages and chat exports from Claude or ChatGPT go into one memory.
+- **Manage.** Containers keep projects apart; search it, ask it questions, forget what should go.
+- **Use.** Your code, Claude Code, Cursor, Codex and ChatGPT read the same memory through the SDK or MCP.
+
+This repository is the developer side: Python and TypeScript clients, the `membase` command line
+and an MCP server. The memory lives in your Membase account, which the
+[web app](https://www.app.membase.ai) and browser extension also fill, or on your machine with
+`unibaseio-membase[local]`.
+
+## Write once, read from any AI
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/unibaseio/membase-ai/main/assets/in-action.svg" width="840" alt="Your app writes a memory; any AI reads it, here Claude Code">
+</p>
+
+Recordings: [Python SDK](https://github.com/unibaseio/membase-ai/blob/main/assets/videos/sdk.mp4) (57 s) ·
+[Claude Code](https://github.com/unibaseio/membase-ai/blob/main/assets/videos/switch-ai.mp4) (1 min 33 s). The answer above is illustrative.
+
+## Accuracy
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/unibaseio/membase-ai/main/assets/results.svg" width="840" alt="LoCoMo 93.1%, LongMemEval_S 92.6%, DMR 92.2%">
+</p>
+
+On three public long-term memory benchmarks, with a few thousand tokens of context per question.
+
+## Quickstart
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/unibaseio/membase-ai/main/assets/architecture.svg" width="840" alt="Hosted, local in process, or local over HTTP">
+</p>
+
+```bash
+pip install unibaseio-membase              # hosted · Python 3.10+ · needs MEMBASE_API_KEY
+pip install 'unibaseio-membase[local]'     # local  · Python 3.12 or 3.13 · needs OPENAI_API_KEY
+npm install @unibaseio/membase              # TypeScript · Node 18+
+npm install -g @unibaseio/membase-cli       # the `membase` command (hosted) without Python
+```
+
+```python
+from membase import Membase
+
+m = Membase()                    # hosted
+# m = Membase(local=True)        # local, in ~/.membase
+
+m.memories.add("We picked Postgres for the ledger service.", container="Engineering")
+m.search("what database is the ledger on?")
+m.add("Design notes …", container="Engineering", custom_id="design-1")   # a document
+m.ask("Which database did we choose for the ledger?")
+```
+
+Every method, its REST route and MCP tool, and the access it needs: [SDK reference](https://docs.membase.ai/build/reference/sdk-quickstart/).
+The Python package is `unibaseio-membase` (import `membase`); `membase` on PyPI is unrelated.
+
+## Command line
+
+```bash
+membase --local add "We picked Postgres for the ledger" --container Engineering
+membase --local search "what did we pick for the ledger?"
+membase --local ask "Which database is the ledger on?"
+membase --local import ~/Downloads/claude-export.json     # Claude, ChatGPT, markdown or JSON chats
+membase --local agent ingest trace.json --agent coder
+membase --local agent search "fix flaky deploy" --agent coder
+```
+
+Without `--local` (or `--store DIR`, both before the command) commands use the hosted API; `agent`,
+`import` and `serve` need `unibaseio-membase[local]`.
+
+## MCP
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/unibaseio/membase-ai/main/assets/mcp.svg" width="840" alt="MCP clients, hosted or local server, same tools">
+</p>
+
+```bash
+claude mcp add membase -- membase --local mcp                                   # local
+claude mcp add --transport http membase https://api.app.membase.io/mcp-http \
+  --header "Authorization: Bearer $MEMBASE_API_KEY"                             # hosted
+```
+
+Hosted without the header, the connection signs you in and is read-only. Setup for Claude, ChatGPT,
+Cursor, Codex and other clients: [Connect your AI](https://docs.membase.ai/connect/).
+
+## Docs
+
+- [SDK reference](https://docs.membase.ai/build/reference/sdk-quickstart/): methods, REST routes, MCP tools, access levels
+- [Memory operations](https://docs.membase.ai/build/guides/memory-operations/): containers, documents, memories, profile, ask
+- [Authentication](https://docs.membase.ai/build/reference/authentication/): keys and what each one can reach
+- [Connect your AI](https://docs.membase.ai/connect/): per-client MCP setup
+- [Local engine](https://github.com/unibaseio/membase-ai/blob/main/docs/reference.md): what it stores, `membase serve`, settings
+
+## License
+
+Copyright © 2026 Unibase. All rights reserved. Proprietary; see
+[LICENSE](https://github.com/unibaseio/membase-ai/blob/main/LICENSE). `unibaseio-membase[local]` also
+installs unibaseio-membase-core, the compiled engine, under its own Unibase license.

unibaseio_membase-0.3.0/README.md

@@ -0,0 +1,128 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/unibaseio/membase-ai/main/assets/membase-logo.png" width="72" alt="Membase">
+</p>
+
+<h1 align="center">Membase</h1>
+
+<p align="center">
+  <b>One memory. Every AI.</b><br>
+  Teach it once. Every AI remembers.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/unibaseio-membase/"><img src="https://img.shields.io/pypi/v/unibaseio-membase?label=pypi" alt="PyPI"></a>
+  <a href="https://www.npmjs.com/package/@unibaseio/membase"><img src="https://img.shields.io/npm/v/@unibaseio/membase?label=npm" alt="npm"></a>
+  <a href="https://github.com/unibaseio/membase-ai/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-proprietary-blue" alt="Proprietary"></a>
+</p>
+
+<p align="center">
+  <a href="https://www.unibase.com/memory">Website</a> ·
+  <a href="https://docs.membase.ai">Docs</a> ·
+  <a href="https://www.app.membase.ai">Web app</a> ·
+  <a href="https://discord.gg/nB9EfPGsSf">Discord</a> ·
+  <a href="https://x.com/Unibase_AI">X</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/unibaseio/membase-ai/main/assets/hero.svg" width="840" alt="Add sources, manage one memory, use it from every AI and app">
+</p>
+
+Membase keeps one memory for everything you and your agents know, and every AI you use reads it.
+You stop re-explaining yourself each time you switch models or tools.
+
+- **Add.** Facts, documents, web pages and chat exports from Claude or ChatGPT go into one memory.
+- **Manage.** Containers keep projects apart; search it, ask it questions, forget what should go.
+- **Use.** Your code, Claude Code, Cursor, Codex and ChatGPT read the same memory through the SDK or MCP.
+
+This repository is the developer side: Python and TypeScript clients, the `membase` command line
+and an MCP server. The memory lives in your Membase account, which the
+[web app](https://www.app.membase.ai) and browser extension also fill, or on your machine with
+`unibaseio-membase[local]`.
+
+## Write once, read from any AI
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/unibaseio/membase-ai/main/assets/in-action.svg" width="840" alt="Your app writes a memory; any AI reads it, here Claude Code">
+</p>
+
+Recordings: [Python SDK](https://github.com/unibaseio/membase-ai/blob/main/assets/videos/sdk.mp4) (57 s) ·
+[Claude Code](https://github.com/unibaseio/membase-ai/blob/main/assets/videos/switch-ai.mp4) (1 min 33 s). The answer above is illustrative.
+
+## Accuracy
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/unibaseio/membase-ai/main/assets/results.svg" width="840" alt="LoCoMo 93.1%, LongMemEval_S 92.6%, DMR 92.2%">
+</p>
+
+On three public long-term memory benchmarks, with a few thousand tokens of context per question.
+
+## Quickstart
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/unibaseio/membase-ai/main/assets/architecture.svg" width="840" alt="Hosted, local in process, or local over HTTP">
+</p>
+
+```bash
+pip install unibaseio-membase              # hosted · Python 3.10+ · needs MEMBASE_API_KEY
+pip install 'unibaseio-membase[local]'     # local  · Python 3.12 or 3.13 · needs OPENAI_API_KEY
+npm install @unibaseio/membase              # TypeScript · Node 18+
+npm install -g @unibaseio/membase-cli       # the `membase` command (hosted) without Python
+```
+
+```python
+from membase import Membase
+
+m = Membase()                    # hosted
+# m = Membase(local=True)        # local, in ~/.membase
+
+m.memories.add("We picked Postgres for the ledger service.", container="Engineering")
+m.search("what database is the ledger on?")
+m.add("Design notes …", container="Engineering", custom_id="design-1")   # a document
+m.ask("Which database did we choose for the ledger?")
+```
+
+Every method, its REST route and MCP tool, and the access it needs: [SDK reference](https://docs.membase.ai/build/reference/sdk-quickstart/).
+The Python package is `unibaseio-membase` (import `membase`); `membase` on PyPI is unrelated.
+
+## Command line
+
+```bash
+membase --local add "We picked Postgres for the ledger" --container Engineering
+membase --local search "what did we pick for the ledger?"
+membase --local ask "Which database is the ledger on?"
+membase --local import ~/Downloads/claude-export.json     # Claude, ChatGPT, markdown or JSON chats
+membase --local agent ingest trace.json --agent coder
+membase --local agent search "fix flaky deploy" --agent coder
+```
+
+Without `--local` (or `--store DIR`, both before the command) commands use the hosted API; `agent`,
+`import` and `serve` need `unibaseio-membase[local]`.
+
+## MCP
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/unibaseio/membase-ai/main/assets/mcp.svg" width="840" alt="MCP clients, hosted or local server, same tools">
+</p>
+
+```bash
+claude mcp add membase -- membase --local mcp                                   # local
+claude mcp add --transport http membase https://api.app.membase.io/mcp-http \
+  --header "Authorization: Bearer $MEMBASE_API_KEY"                             # hosted
+```
+
+Hosted without the header, the connection signs you in and is read-only. Setup for Claude, ChatGPT,
+Cursor, Codex and other clients: [Connect your AI](https://docs.membase.ai/connect/).
+
+## Docs
+
+- [SDK reference](https://docs.membase.ai/build/reference/sdk-quickstart/): methods, REST routes, MCP tools, access levels
+- [Memory operations](https://docs.membase.ai/build/guides/memory-operations/): containers, documents, memories, profile, ask
+- [Authentication](https://docs.membase.ai/build/reference/authentication/): keys and what each one can reach
+- [Connect your AI](https://docs.membase.ai/connect/): per-client MCP setup
+- [Local engine](https://github.com/unibaseio/membase-ai/blob/main/docs/reference.md): what it stores, `membase serve`, settings
+
+## License
+
+Copyright © 2026 Unibase. All rights reserved. Proprietary; see
+[LICENSE](https://github.com/unibaseio/membase-ai/blob/main/LICENSE). `unibaseio-membase[local]` also
+installs unibaseio-membase-core, the compiled engine, under its own Unibase license.

unibaseio_membase-0.3.0/membase/__init__.py

@@ -0,0 +1,38 @@
+"""Membase — long-term memory for AI."""
+
+from ._version import __version__
+from .client import DEFAULT_BASE_URL, Membase
+from .requirements import MissingDependencyError
+from .errors import (
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    InternalServerError,
+    MembaseError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    UnprocessableEntityError,
+)
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "Membase",
+    "MembaseError",
+    "MissingDependencyError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIStatusError",
+    "BadRequestError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "UnprocessableEntityError",
+    "RateLimitError",
+    "InternalServerError",
+    "__version__",
+]

unibaseio_membase-0.3.0/membase/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

unibaseio_membase-0.3.0/membase/_version.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

unibaseio_membase-0.3.0/membase/cli.py

@@ -0,0 +1,246 @@
+"""``membase``: the Membase command line, hosted or local."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from ._version import __version__
+from .client import Membase
+from .errors import MembaseError
+
+
+def _client(args: argparse.Namespace) -> Membase:
+    if args.local or args.store:
+        return Membase(local=args.store or True)
+    try:
+        return Membase(api_key=args.api_key, base_url=args.base_url)
+    except ValueError:
+        raise SystemExit("no API key: pass --api-key or set MEMBASE_API_KEY (Connect › Developer keys), "
+                         "or use --local") from None
+
+
+def _print(obj: Any) -> None:
+    print(json.dumps(obj, ensure_ascii=False, indent=2, default=str))
+
+
+_IMPORTABLE = {".json", ".md", ".markdown", ".txt"}
+
+
+def _import_files(paths: list[str]) -> list[Path]:
+    out: list[Path] = []
+    for raw in paths:
+        p = Path(raw).expanduser()
+        if p.is_dir():
+            out += sorted(f for f in p.rglob("*") if f.is_file() and f.suffix.lower() in _IMPORTABLE)
+        elif p.is_file():
+            out.append(p)
+        else:
+            raise SystemExit(f"no such file or directory: {raw}")
+    return out
+
+
+def _cmd_import(args: argparse.Namespace, m: Membase) -> Any:
+    try:
+        from membase_core.sources import detect_format, load_sessions
+    except ImportError:
+        raise SystemExit("membase import reads chat exports with the local engine: pip install 'unibaseio-membase[local]'")
+    sessions: list[dict] = []
+    found: list[dict] = []
+    for f in _import_files(args.files):
+        got = load_sessions(f)
+        sessions += got
+        found.append({"file": str(f), "format": detect_format(f), "sessions": len(got)})
+    if not sessions:
+        raise SystemExit("no sessions found")
+    if args.dry_run:
+        return {"would_import": len(sessions), "files": found}
+    transport = m._http._transport  # noqa: SLF001 - the local transport, when local
+    backend = getattr(transport, "backend", None)
+    if backend is not None:
+        return backend.import_sessions(sessions, args.container)
+    out = []
+    for s in sessions:
+        text = "\n".join(f"{t['role']}: {t['content']}" for t in s["turns"])
+        out.append(m.add(text, container=args.container, title=s["session_id"],
+                         custom_id=f"session:{s['session_id']}"))
+    return {"sessions": len(out), "documents": out}
+
+
+def _load_trace(path: str) -> tuple[list[dict], dict]:
+    raw = sys.stdin.read() if path == "-" else Path(path).expanduser().read_text(encoding="utf-8")
+    data = json.loads(raw)
+    if isinstance(data, list):
+        return data, {}
+    if isinstance(data, dict) and isinstance(data.get("messages"), list):
+        return data["messages"], {k: data[k] for k in ("agent_id", "session_id") if data.get(k)}
+    raise SystemExit("a trace is a JSON list of messages or an object with a 'messages' list")
+
+
+def _cmd_agent(args: argparse.Namespace, m: Membase) -> Any:
+    backend = getattr(m._http._transport, "backend", None)  # noqa: SLF001
+    if backend is None:
+        raise SystemExit("agent memory is local: use membase --local agent ...")
+    if args.agent_cmd == "ingest":
+        messages, meta = _load_trace(args.trace)
+        session = args.session or meta.get("session_id") or (Path(args.trace).stem if args.trace != "-" else None)
+        return backend.agent_ingest(messages, agent_id=args.agent, session_id=session, container=args.container)
+    if args.agent_cmd == "search":
+        return backend.agent_search(args.q, agent_id=args.agent, kind=args.kind, limit=args.limit,
+                                    container=args.container)
+    return backend.agent_skills(args.agent, container=args.container)
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="membase", description="Membase — long-term memory for AI.")
+    p.add_argument("--version", action="version", version=__version__)
+    p.add_argument("--local", action="store_true",
+                   help="use local memory (store ~/.membase) instead of the hosted API")
+    p.add_argument("--store", default=None, metavar="DIR",
+                   help="local store directory (default ~/.membase); implies --local")
+    p.add_argument("--api-key", default=None, help="hosted API key (default MEMBASE_API_KEY)")
+    p.add_argument("--base-url", default=None, help="hosted API base URL (default MEMBASE_BASE_URL)")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("containers", help="list the containers in reach")
+
+    s = sub.add_parser("search", help="search memory")
+    s.add_argument("q")
+    s.add_argument("--container", help="one container id (default: every container in reach)")
+    s.add_argument("--limit", type=int, help="passages in all, 1-50")
+
+    a = sub.add_parser("add", help="remember one fact or a short exchange")
+    a.add_argument("content")
+    a.add_argument("--container", help="container id (may be omitted when one is in reach)")
+    a.add_argument("--static", action="store_true", help="a standing fact about the user (profile)")
+    a.add_argument("--title", default="")
+
+    d = sub.add_parser("documents", help="documents: add / list / get / delete")
+    dsub = d.add_subparsers(dest="doc_cmd", required=True)
+    da = dsub.add_parser("add", help="give a container raw material: a file, --url or --text")
+    da.add_argument("path", nargs="?")
+    da.add_argument("--url", help="a public web address to fetch")
+    da.add_argument("--text", help="the document's text")
+    da.add_argument("--container", default=None, help="container id (default: default)")
+    da.add_argument("--title", default="")
+    da.add_argument("--custom-id", default="", help="your own id; the same id again is a no-op")
+    dl = dsub.add_parser("list", help="documents, newest first")
+    dl.add_argument("--container")
+    dg = dsub.add_parser("get", help="one document, with whether it is learned")
+    dg.add_argument("document_id")
+    dd = dsub.add_parser("delete", help="remove a document")
+    dd.add_argument("document_id")
+    dd.add_argument("--confirm", action="store_true", help="remove it; without this, only show what would go")
+
+    f = sub.add_parser("forget", help="forget one memory by id")
+    f.add_argument("memory_id")
+    f.add_argument("--container")
+    f.add_argument("--confirm", action="store_true", help="forget it; without this, only show what would go")
+
+    pr = sub.add_parser("profile", help="who the user is")
+    pr.add_argument("q", nargs="?")
+
+    k = sub.add_parser("ask", help="an answer composed from memory")
+    k.add_argument("message")
+
+    i = sub.add_parser("import", help="import chat exports (Claude, ChatGPT, markdown, JSON); directories are scanned")
+    i.add_argument("files", nargs="+")
+    i.add_argument("--container")
+    i.add_argument("--dry-run", action="store_true", help="only report what would be imported")
+
+    g = sub.add_parser("agent", help="agent memory (local): traces to cases and skills")
+    gsub = g.add_subparsers(dest="agent_cmd", required=True)
+    gi = gsub.add_parser("ingest", help="learn from an agent trace (chat-completions JSON, or '-' for stdin)")
+    gi.add_argument("trace")
+    gi.add_argument("--agent", required=True, help="the agent's id (owner of its cases and skills)")
+    gi.add_argument("--session", default=None)
+    gi.add_argument("--container")
+    gs = gsub.add_parser("search", help="search an agent's cases and skills")
+    gs.add_argument("q")
+    gs.add_argument("--agent", required=True)
+    gs.add_argument("--kind", choices=("cases", "skills", "both"), default="both")
+    gs.add_argument("--limit", type=int, default=10)
+    gs.add_argument("--container")
+    gk = gsub.add_parser("skills", help="list an agent's skills")
+    gk.add_argument("--agent", required=True)
+    gk.add_argument("--container")
+
+    sv = sub.add_parser("serve", help="serve local memory over HTTP on the /v1 routes (always local; "
+                                      "MEMBASE_LOCAL_TOKEN requires a bearer)")
+    sv.add_argument("--host", default="127.0.0.1", help="default 127.0.0.1")
+    sv.add_argument("--port", type=int, default=8787, help="default 8787")
+
+    mc = sub.add_parser("mcp", help="run the MCP server (hosted, or local with --local)")
+    mc.add_argument("--transport", choices=("stdio", "sse", "streamable-http"), default="stdio")
+    mc.add_argument("--host", default="127.0.0.1", help="default 127.0.0.1 (sse / streamable-http)")
+    mc.add_argument("--port", type=int, default=8765, help="default 8765 (sse / streamable-http)")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        if args.cmd == "serve":
+            from .local.server import serve
+
+            serve(args.host, args.port, root=args.store)
+            return 0
+        if args.cmd == "mcp":
+            from .requirements import require_mcp
+
+            require_mcp()
+        m = _client(args)
+        if args.cmd == "mcp":
+            from .mcp import run
+
+            run(m, transport=args.transport, host=args.host, port=args.port)
+            return 0
+        if args.cmd == "containers":
+            out = m.containers.list()
+        elif args.cmd == "search":
+            out = m.search(args.q, container=args.container, limit=args.limit)
+        elif args.cmd == "add":
+            out = m.memories.add(args.content, container=args.container, static=args.static, title=args.title)
+        elif args.cmd == "documents":
+            if args.doc_cmd == "add":
+                if args.path:
+                    content = Path(args.path).read_text()
+                    title = args.title or Path(args.path).stem
+                else:
+                    content, title = args.text, args.title
+                if (content is None) == (args.url is None):
+                    raise SystemExit("documents add needs exactly one of PATH, --text or --url")
+                out = m.add(content, container=args.container or "default", url=args.url,
+                            title=title, custom_id=args.custom_id)
+            elif args.doc_cmd == "list":
+                out = m.documents.list(container=args.container)
+            elif args.doc_cmd == "get":
+                out = m.documents.get(args.document_id)
+            else:
+                out = m.documents.delete(args.document_id, confirm=args.confirm)
+        elif args.cmd == "forget":
+            out = m.memories.forget(args.memory_id, container=args.container, confirm=args.confirm)
+        elif args.cmd == "profile":
+            out = m.profile(args.q)
+        elif args.cmd == "ask":
+            out = m.ask(args.message)
+        elif args.cmd == "agent":
+            out = _cmd_agent(args, m)
+        else:
+            out = _cmd_import(args, m)
+        _print(out)
+        m.close()
+        return 0
+    except MembaseError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    except ValueError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())