@hasna/mementos 0.14.68 → 0.14.70

package/README.md

@@ -1,126 +1,208 @@
 # @hasna/mementos
 
-Universal memory system for AI agents - CLI + MCP server + library API
+Persistent memory for AI agents, available as a CLI, MCP server, REST service,
+and TypeScript library. Mementos stores memories in local SQLite by default and
+can route clients to a self-hosted PostgreSQL-backed service over an authenticated
+HTTP API.
 
 [![npm](https://img.shields.io/npm/v/@hasna/mementos)](https://www.npmjs.com/package/@hasna/mementos)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
 
 ## Install
 
+Mementos requires [Bun](https://bun.sh/) 1.0 or newer at runtime.
+
 ```bash
 npm install -g @hasna/mementos
+# or
+bun add -g @hasna/mementos
 ```
 
-## CLI Usage
+The package installs three binaries:
+
+| Binary | Purpose |
+| --- | --- |
+| `mementos` | Memory, agent, project, graph, session, and maintenance CLI |
+| `mementos-mcp` | MCP server; Streamable HTTP by default, stdio on request |
+| `mementos-serve` | REST API and dashboard server |
+
+## Quick start
+
+Local mode needs no service or database configuration. The first command creates
+and migrates `~/.hasna/mementos/mementos.db`.
 
 ```bash
-mementos --help
+mementos save project-stack "Bun, TypeScript, SQLite" \
+  --scope shared --category fact
+mementos recall project-stack
+mementos search "TypeScript"
+mementos list --scope shared
 ```
 
-CLI output is compact by default so agent terminals do not fill with full
-records. List/search/history commands show capped rows, truncated values, and a
-hint for the next page or detail path.
+Register an agent and project when memories need explicit ownership:
 
 ```bash
-mementos list                         # compact page, default 20 rows
-mementos list --cursor 20 --limit 20  # next page
-mementos search "deploy"              # compact results, no highlights
-mementos search "deploy" --verbose    # include match highlights
-mementos show <id>                    # full memory detail
-mementos --json list                  # stable machine-readable objects
+mementos projects --add --name my-project --path "$PWD"
+mementos register-agent marcus --role coding-agent
+mementos inject --project "$PWD" --agent marcus --format compact
 ```
 
-## Shared Event Webhooks
+Memory scopes are `global`, `shared`, `private`, and `working`. `working` is
+transient session scratch space and defaults to a one-hour lifetime. Categories
+are `preference`, `fact`, `knowledge`, `history`, `procedural`, and `resource`.
+
+## CLI
+
+```bash
+mementos --help
+mementos <command> --help
+```
 
-`mementos` exposes the shared `@hasna/events` commands so memory events can
-trigger deterministic or agentic automation without custom glue scripts. To
-route mementos events into an OpenLoops worker/verifier template, register a
-command webhook:
+Human-readable list and search commands are compact and paginated by default.
+Use `--limit` with `--cursor` or `--offset`, `--verbose` for wider snippets, and
+`mementos show <id>` for a full record. Use global `--json` or a supported
+`--format json|csv|yaml` option for structured output.
 
 ```bash
-mementos webhooks add loops \
-  --id openloops-mementos-events \
-  --transport command \
-  --source mementos \
-  --type "*" \
-  --arg=events \
-  --arg=handle \
-  --arg=generic \
-  --arg=--provider \
-  --arg=codewith \
-  --arg=--auth-profile \
-  --arg=account005 \
-  --arg=--permission-mode \
-  --arg=bypass \
-  --arg=--sandbox \
-  --arg=danger-full-access \
-  --timeout-ms 900000 \
-  --json
+mementos list --limit 20 --cursor 20
+mementos search "deploy" --verbose
+mementos --json list
+mementos storage mode --json
 ```
 
-`@hasna/events` sends the event envelope on stdin and in `HASNA_EVENT_JSON`.
-OpenLoops can then create a deduped one-shot workflow for the event. Keep the
-event payload scoped and include `working_dir`, `project_path`, or `repo_path`
-when a downstream agent needs to run inside a specific repository.
+The complete command tree and option conventions are in the
+[CLI reference](docs/CLI.md).
+
+## MCP
 
-## MCP Server
+`mementos-mcp` defaults to a shared, stateless Streamable HTTP server bound to
+`127.0.0.1:8867`:
 
 ```bash
 mementos-mcp
+# explicit equivalent
+mementos-mcp --http --port 8867
 ```
 
-116 tools available.
+Endpoints are `GET /health` and `POST /mcp`. Set `MCP_HTTP_PORT` to change the
+port. For an MCP host that launches a child process over stdio, opt in explicitly:
 
-MCP list/status tools also default to compact text. Use tool-specific
-`limit`/`offset` arguments for paging and `full=true` or `format="json"` on tools
-that expose it when a complete object dump is required.
+```bash
+mementos-mcp --stdio
+# or: MCP_STDIO=1 mementos-mcp
+```
 
-## HTTP mode
+Cursor, Codex, Claude, and other command-based MCP host entries should use
+`command = "mementos-mcp"` with `args = ["--stdio"]`.
 
-Run a shared Streamable HTTP MCP server (stateless, `127.0.0.1` only):
+The server exposes its live tools plus `mementos://memories`,
+`mementos://agents`, and `mementos://projects`. MCP `tools/list` is the complete
+schema source; the convenience `search_tools` and `describe_tools` calls cover
+the smaller registered utility discovery catalog. See the [MCP
+reference](docs/MCP.md) for installation examples and the full tool inventory.
+
+## REST API
 
 ```bash
-mementos-mcp --http
-# or: MCP_HTTP=1 mementos-mcp
-# default port: 8824 (override with --port or MCP_HTTP_PORT)
+mementos-serve --port 19428
 ```
 
-Endpoints: `GET /health`, `POST /mcp` (Streamable HTTP).
+The server binds to `127.0.0.1` unless `MEMENTOS_HOST` is set. `/v1` is the
+canonical API prefix and `/api` is a backward-compatible alias. Operational
+probes and the generated contract are available without authentication:
 
-## REST API
+```text
+GET /health
+GET /ready
+GET /version
+GET /openapi.json
+```
+
+API routes use bearer/API-key authentication when configured. See the
+[REST API reference](docs/REST-API.md).
+
+## Storage modes
+
+### Local clients
+
+SQLite is authoritative by default. Database selection order is:
+
+1. `HASNA_MEMENTOS_DB_PATH` or `MEMENTOS_DB_PATH`.
+2. The nearest existing `.mementos/mementos.db` walking up from the current directory.
+3. Git-root `.mementos/mementos.db` when `MEMENTOS_DB_SCOPE=project`.
+4. `~/.hasna/mementos/mementos.db`.
+
+Legacy `~/.mementos` data is copied to `~/.hasna/mementos` when the new directory
+does not yet exist.
+
+### Self-hosted cloud
+
+Raw PostgreSQL credentials are server-only. Configure `mementos-serve` with
+`HASNA_MEMENTOS_STORAGE_MODE=cloud` and `HASNA_MEMENTOS_DATABASE_URL`. Configure
+CLI and MCP clients with the HTTPS API endpoint and API key instead:
 
 ```bash
-mementos-serve
+# mementos-serve environment
+HASNA_MEMENTOS_STORAGE_MODE=cloud
+HASNA_MEMENTOS_DATABASE_URL=postgres://...
+
+# client environment; do not distribute the database URL to clients
+HASNA_MEMENTOS_API_URL=https://mementos.example.com
+HASNA_MEMENTOS_API_KEY=...
 ```
 
-## Storage Sync
+Both API variables must be present to select client API mode, and a database URL
+on the same client disables API mode. `mementos storage mode` reports the chosen
+backend without opening a database or making a network request.
+
+The old `storage push`, `pull`, and `sync` commands remain for compatibility;
+they are not the cloud cutover architecture. See [Configuration and
+storage](docs/CONFIGURATION.md) and the [cloud cutover runbook](docs/CUTOVER-RUNBOOK.md).
 
-Mementos owns its local and remote storage path. The primary local runtime is
-SQLite under `~/.hasna/mementos/` by default, with config under
-`~/.hasna/mementos/storage/config.json`. Mementos does not sync raw local data
-files.
+## TypeScript APIs
 
-Cloud storage is PostgreSQL/RDS-compatible. Enable it with
-`HASNA_MEMENTOS_STORAGE_MODE=cloud` plus `HASNA_MEMENTOS_DATABASE_URL` or
-`MEMENTOS_DATABASE_URL`, or set RDS host/user fields in the storage config.
-Legacy `hybrid` and `remote` mode values are accepted only as deprecated aliases
-for `cloud`. Cloud commands fail closed when PostgreSQL/RDS is requested but not
-configured. Status and dry-run diagnostics redact credentials and do not contact AWS.
-There is no S3 object-storage adapter in this runtime, and diagnostics do not
-store sensitive values, mutate AWS resources, deploy, or migrate production data.
+The main package exports the synchronous database/domain API from
+`@hasna/mementos` and an authenticated fetch client from `@hasna/mementos/sdk`.
+The repository also contains the separately published zero-dependency
+`@hasna/mementos-sdk` client. See [Library and SDK APIs](docs/LIBRARY.md) and
+the [standalone SDK README](sdk/README.md).
+
+## Shared event webhooks
+
+The CLI includes the `events` and `webhooks` command groups supplied by
+`@hasna/events`, allowing memory events to trigger command or HTTP automation.
+Inspect their installed-version help before configuring a webhook:
+
+```bash
+mementos events --help
+mementos webhooks --help
+```
+
+Event command handlers receive the envelope on stdin and in
+`HASNA_EVENT_JSON`. Include `working_dir`, `project_path`, or `repo_path` when a
+downstream agent must run in a particular repository.
+
+## Development
 
 ```bash
-mementos storage status
-mementos storage push
-mementos storage pull
-mementos storage sync
-mementos storage migrate --dry-run
+bun install
+bun run typecheck
+bun test
+bun run build
 ```
 
-## Data Directory
+Development entry points are `bun run dev:cli`, `bun run dev:mcp`, and
+`bun run dev:serve`.
+
+## Documentation
 
-Data is stored in `~/.hasna/mementos/`.
+- [CLI reference](docs/CLI.md)
+- [MCP reference](docs/MCP.md)
+- [REST API reference](docs/REST-API.md)
+- [Configuration and storage](docs/CONFIGURATION.md)
+- [Library and SDK APIs](docs/LIBRARY.md)
+- [Cloud cutover runbook](docs/CUTOVER-RUNBOOK.md)
 
 ## License
 
-Apache-2.0 -- see [LICENSE](LICENSE)
+Apache-2.0 — see [LICENSE](LICENSE).

package/dist/cli/__fixtures__/clean-fallback-stub-server.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=clean-fallback-stub-server.d.ts.map

package/dist/cli/__fixtures__/clean-fallback-stub-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clean-fallback-stub-server.d.ts","sourceRoot":"","sources":["../../../src/cli/__fixtures__/clean-fallback-stub-server.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,CAAC"}

package/dist/cli/commands/io-clean.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"io-clean.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/io-clean.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmCzC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAwC3D"}
+{"version":3,"file":"io-clean.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/io-clean.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAyCzC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAwC3D"}

package/dist/cli/commands/memory-cmd-crud.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory-cmd-crud.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/memory-cmd-crud.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6BzC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAmT3D"}
+{"version":3,"file":"memory-cmd-crud.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/memory-cmd-crud.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+BzC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAka3D"}

package/dist/cli/commands/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0QzC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAK9D"}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsUzC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAK9D"}

package/dist/cli/commands/system-mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"system-mcp.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/system-mcp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGzC,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA6FzD"}
+{"version":3,"file":"system-mcp.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/system-mcp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGzC,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAqHzD"}

package/dist/cli/commands/system-profile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"system-profile.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/system-profile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKzC,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA0G7D"}
+{"version":3,"file":"system-profile.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/system-profile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKzC,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA2G7D"}

package/dist/cli/global-options.d.ts

@@ -0,0 +1,27 @@
+import type { Command } from "commander";
+/**
+ * The program-level options, in one place.
+ *
+ * These are declared on the root `mementos` command, and commander resolves a
+ * short flag appearing AFTER a subcommand name to the parent's option. So any
+ * short flag listed here is claimed globally: a subcommand that declares the
+ * same short can never receive a value through it, no matter what `--help` says.
+ *
+ * That is not hypothetical. `save`/`update`/`list`/`recall`/... each declared
+ * `-s, --scope`, which `-s, --session` below shadowed. `mementos save k v -s
+ * shared` therefore wrote `session_id="shared"` and left scope at its default,
+ * while `--help` advertised `-s, --scope` — a documented flag that silently
+ * misrouted its value into a different column (HC-00149).
+ *
+ * Exported so the invariant can be enforced by a test instead of by review:
+ * see `global-options.test.ts`.
+ */
+export declare const GLOBAL_OPTIONS: ReadonlyArray<readonly [flags: string, description: string]>;
+/**
+ * Short flags no subcommand may reuse: the globals above plus commander's own
+ * built-ins (`-V` for --version, `-h` for --help).
+ */
+export declare function reservedShortFlags(): Set<string>;
+/** Apply the global options to the root program. */
+export declare function applyGlobalOptions(program: Command): Command;
+//# sourceMappingURL=global-options.d.ts.map

package/dist/cli/global-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-options.d.ts","sourceRoot":"","sources":["../../src/cli/global-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,CAMvF,CAAC;AAEF;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,GAAG,CAAC,MAAM,CAAC,CAOhD;AAED,oDAAoD;AACpD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAG5D"}