@hol-org/hashnet-mcp 1.0.18 → 1.0.20

package/AGENTS.md

@@ -1,5 +1,32 @@
 # Repository Guidelines
 
+# **ABSOLUTE PROHIBITION — NO FILE DELETIONS OR GIT REVERTS.** Never delete files, directories, or history. Never run `git revert`, `git reset`, `git checkout`, `git restore`, or any command that removes tracked work. Violations immediately fail the task and forfeit all points.
+
+# AGENTS.md — Tool Selection (TypeScript)
+
+- Find files by file name: `fd`
+- Find files with path name: `fd -p <file-path>`
+- List files in a directory: `fd . <directory>`
+- Find files with extension and pattern: `fd -e <extension> <pattern>`
+- Find text: `rg`
+- Structured code search and codemods: `ast-grep`
+  - Default languages:
+    - `.ts` → `ast-grep --lang ts -p '<pattern>'`
+    - `.tsx` → `ast-grep --lang tsx -p '<pattern>'`
+  - Common languages:
+    - Python → `ast-grep --lang python -p '<pattern>'`
+    - TypeScript → `ast-grep --lang ts -p '<pattern>'`
+    - TSX (React) → `ast-grep --lang tsx -p '<pattern>'`
+    - JavaScript → `ast-grep --lang js -p '<pattern>'`
+    - Rust → `ast-grep --lang rust -p '<pattern>'`
+    - Bash → `ast-grep --lang bash -p '<pattern>'`
+    - JSON → `ast-grep --lang json -p '<pattern>'`
+  - Select among matches: pipe to `fzf`
+  - JSON: `jq`
+  - YAML/XML: `yq`
+
+If `ast-grep` is available, avoid `rg` or `grep` unless a plain-text search is explicitly requested.
+
 ## Project Structure & Module Organization
 The MCP server lives in `src/` with three core modules: `mcp.ts` (tool wiring and metadata), `broker.ts` (the `RegistryBrokerClient` wrapper), and `transports.ts` (stdio plus SSE server built on Hono). Place shared schemas in `src/schemas/` and transport helpers in `src/transports/` if they grow larger. Configuration belongs in `tsconfig.json`, environment defaults in `.env.example`, and any integration fixtures under `examples/`. Keep tests in `tests/` mirroring the source tree so `tests/mcp/tools.spec.ts` maps cleanly to `src/mcp.ts`.
 
@@ -70,6 +97,9 @@ Each workflow emits a structured report (steps, timings, context) whether execut
 - Tool-suite fixtures (optional): `TEST_UAID`, `TEST_CHAT_UAID`, `TEST_REGISTRATION_ATTEMPT_ID`, and `BROKER_PROTOCOL_TOOLS`. Populate them (see `.env.example`) so `pnpm test:tools` can exercise UAID/chat flows locally or skip protocol checks when the broker doesn’t expose those endpoints; leave blank to rely on auto-discovered UAIDs/attempt IDs from the preceding scenarios.
 Workflow pipelines declare their required env vars and will fail fast with a descriptive error if anything is missing; payload-specific secrets (OpenRouter tokens, Agentverse headers, bearer tokens) should be supplied via `.env` or injected by your CLI before invoking the workflow.
 
+### Memory (optional)
+- Set `MEMORY_ENABLED=1` to enable local memory capture (SQLite by default; see `.env.example` for limits and store selection). When enabled, workflows like `workflow.chatSmoke`, `workflow.openrouterChat`, `workflow.historyTopUp`, `workflow.registryBrokerShowcase`, and `workflow.fullRegistration` will load scoped context (uaid/session/namespace) and append discovery/chat traces. Pass `disableMemory: true` in workflow inputs to opt out even when memory is enabled.
+
 ### Running `pnpm workflow:register`
 1. The CLI prompts for display name, alias, description, MCP URL, chat message, and report path (defaults provided).
 2. Runs the registration → chat → ops pipelines and prints progress to the console.

package/README.md

@@ -93,7 +93,7 @@ Use `"type": "sse"` if your build expects it.
 Categories are exposed as MCP tools (`hol.*`) plus workflows (`workflow.*`):
 - **Discovery**: `hol.search`, `hol.vectorSearch`, `hol.registrySearchByNamespace`, `hol.resolveUaid`
 - **Registration**: `hol.getRegistrationQuote`, `hol.registerAgent`, `hol.waitForRegistrationCompletion`, `hol.updateAgent`
-- **Chat**: `hol.chat.createSession` (uaid preferred), `hol.chat.sendMessage` (sessionId or uaid; auto-creates session), `hol.chat.history`, `hol.chat.compact`, `hol.chat.end`, `hol.closeUaidConnection`
+- **Chat**: `hol.chat.createSession` (uaid or agentUrl), `hol.chat.sendMessage` (sessionId or uaid/agentUrl; auto-creates session), `hol.chat.history`, `hol.chat.compact`, `hol.chat.end`, `hol.closeUaidConnection`
 - **Protocols/Ops**: `hol.listProtocols`, `hol.detectProtocol`, `hol.stats`, `hol.metricsSummary`, `hol.dashboardStats`, `hol.websocketStats`
 - **Credits**: `hol.credits.balance`, `hol.purchaseCredits.hbar`, `hol.x402.minimums`, `hol.x402.buyCredits`
 - **Ledger**: `hol.ledger.challenge`, `hol.ledger.authenticate`
@@ -105,6 +105,14 @@ Categories are exposed as MCP tools (`hol.*`) plus workflows (`workflow.*`):
 - **Chat**: Start with `hol.chat.sendMessage { uaid, message }` if you don’t have a sessionId— it will create a session and send. Otherwise use `hol.chat.createSession` then `hol.chat.sendMessage { sessionId, message }`. Manage with `hol.chat.history/compact/end`.
 - **Ops/Health**: `workflow.opsCheck` or the `hol.stats`/`hol.metricsSummary`/`hol.dashboardStats` trio.
 - **Credits**: Always check `hol.credits.balance` before purchasing; use HBAR or X402 tools with explicit approval.
+- **Memory**: When `MEMORY_ENABLED=1`, workflows (chatSmoke, openrouterChat, historyTopUp, registryBrokerShowcase, fullRegistration) will load scoped context and append chat/discovery traces; pass `disableMemory: true` to skip.
+
+## Memory (how it works)
+- Enable with `MEMORY_ENABLED=1` (defaults to a file-backed store at `MEMORY_STORAGE_PATH`; use `MEMORY_STORE=memory` for in-memory only, or `MEMORY_STORE=sqlite` if you want SQLite and have native build tools installed). Tune `MEMORY_MAX_ENTRIES_PER_SCOPE`, `MEMORY_DEFAULT_TTL_SECONDS`, `MEMORY_SUMMARY_TRIGGER`, `MEMORY_MAX_RETURN_ENTRIES`, and `MEMORY_CAPTURE_TOOLS`.
+- MCP tools: `hol.memory.context`, `hol.memory.note`, `hol.memory.search`, `hol.memory.clear` (see `help://hol/memory`). Scopes use `uaid`, `sessionId`, `namespace`, or `userId`.
+- Automatic capture: `hol.chat.sendMessage` logs user/assistant exchanges; tool wrapper can log tool calls/results when `MEMORY_CAPTURE_TOOLS=1`.
+- Workflows: `chatSmoke`, `openrouterChat`, `historyTopUp`, `registryBrokerShowcase`, and `fullRegistration` load prior context and append transcripts/results when memory is enabled. Add `disableMemory: true` in workflow inputs to opt out.
+- Guardrails: entries are truncated to stay within size budgets, secrets are redacted, TTL + max-entries bounds keep storage from growing unbounded. Summaries are generated heuristically once thresholds are exceeded.
 
 ## Tool catalog (what each does)
 **Discovery**
@@ -122,12 +130,11 @@ Categories are exposed as MCP tools (`hol.*`) plus workflows (`workflow.*`):
 - `hol.additionalRegistries` — catalog of additional registries/networks.
 
 **Chat**
-- `hol.chat.createSession` — open a session by `uaid` (preferred).
-- `hol.chat.sendMessage` — send to an existing sessionId or auto-create via `uaid`.
+- `hol.chat.createSession` — open a session by `uaid` or `agentUrl`.
+- `hol.chat.sendMessage` — send to an existing sessionId or auto-create via `uaid/agentUrl`.
 - `hol.chat.history` / `hol.chat.compact` / `hol.chat.end` — manage chat lifecycle.
 
 **Protocols / Ops**
-- `hol.listProtocols`, `hol.detectProtocol` — inspect/route inbound payloads.
 - `hol.stats`, `hol.metricsSummary`, `hol.dashboardStats`, `hol.websocketStats` — broker health/metrics.
 
 **Credits**
@@ -150,6 +157,7 @@ Set in `.env` or your process:
 - `REGISTRY_BROKER_API_URL` (default `https://registry.hashgraphonline.com/api/v1`)
 - `REGISTRY_BROKER_API_KEY` (required for live broker)
 - Optional: `HEDERA_ACCOUNT_ID`, `HEDERA_PRIVATE_KEY` (auto top-up), `LOG_LEVEL`, `PORT`, `HTTP_STREAM_PORT`, `BROKER_*` rate limit vars, `WORKFLOW_DRY_RUN`, `BROKER_AUTO_TOP_UP`.
+- Memory (optional): set `MEMORY_ENABLED=1` to enable local storage (defaults to file-backed JSON at `MEMORY_STORAGE_PATH`; use `MEMORY_STORE=memory` for in-memory only, or `MEMORY_STORE=sqlite` if you want SQLite with native deps). Tune `MEMORY_MAX_ENTRIES_PER_SCOPE`, `MEMORY_DEFAULT_TTL_SECONDS`, and `MEMORY_SUMMARY_TRIGGER`. See `help://hol/memory` for the `hol.memory.*` tools.
 
 ## Testing & quality
 - Run once with coverage: `pnpm test --run --coverage`