@hasna/mementos 0.17.0 → 0.17.1

package/README.md

@@ -75,6 +75,95 @@ without a project it has no effect. Omitting it keeps an exact project match.
 
 ## CLI
 
+### Optional decision assistance
+
+Decision assistance is **off by default**. No provider account or key is needed
+for ordinary Mementos commands. Configure and enable the features you want from
+the CLI; there is no web setup. This adds no service-side configuration and does
+not change ordinary `search`, context injection, or consolidation.
+
+```bash
+mementos decisions status --json
+mementos decisions configure --provider openrouter --model typesafe/jev-1.13
+mementos decisions enable --retrieval --relationships
+# Supply OPENROUTER_API_KEY through your secret manager's process environment.
+mementos --project my-project decisions search "release approval policy" --limit 10 --json
+mementos decisions evaluate --input pair.json --json
+mementos decisions disable
+```
+
+`configure` always leaves assistance disabled. `enable` permits only the selected
+features and explicitly permits sending their text to the configured provider.
+The key is read from `OPENROUTER_API_KEY`; it is never saved in decision settings.
+`status` reports key presence without verifying or calling the provider. Settings
+are versioned client preferences in the Mementos data root's `decisions.json`;
+updates reject concurrent changes. `status`, configuration, and `evaluate` do not
+open a memory store or require a hosted Mementos account.
+
+`decisions search` retrieves a bounded candidate set using the existing project,
+agent, session, scope, category, and tag filters, then optionally reranks it. Every
+candidate is retained; ties preserve the original order. On a missing key,
+timeout, invalid answer, oversized input, or provider failure, the original
+ordering is returned with an explicit assessment reason. This command has no
+pagination cursor: its receipt names `ranking_scope: "returned_candidates"` and
+reports `has_more`. Use ordinary `search` for pagination. JSON includes compact
+snippets and source IDs/versions, with a 128 KiB output ceiling.
+
+`evaluate` accepts a JSON file or stdin (`--input -`). A relationship input is:
+
+```json
+{
+  "task": "relationship",
+  "candidates": [
+    { "id": "a", "text": "Production deployment requires approval." },
+    { "id": "b", "text": "Production deployment does not require approval." }
+  ]
+}
+```
+
+For relevance, use `"task": "relevance"`, a non-empty `"query"`, and a
+`"candidates"` array of the same `{id,text}` shape. Relationship suggestions are
+`equivalent`, `complementary`, `contradictory`, `unrelated`, or `uncertain`.
+Evaluation is read-only: suggestions never authorize writes or replace source
+authority, human review, or version checks. An unavailable evaluation exits 2;
+a disabled evaluation exits 0 with an explicit `disabled` receipt.
+
+The built-in adapter calls OpenRouter's Decisions API with a pinned model ID,
+no automatic retries, and provider fallback disabled. Defaults bound each
+assessment to 20 candidates, 16,000 serialized input characters, and five
+seconds; configure these with `--max-candidates`, `--max-input-chars`, and
+`--timeout-ms`. Input files are limited to 256 KiB and provider responses to
+64 KiB. Only query and candidate text go to OpenRouter; arbitrary metadata and
+candidate IDs are excluded. Known secret patterns and credential-bearing URLs
+are redacted before transmission. Redaction is heuristic: enable this only for
+content you are permitted to send to your chosen provider.
+
+Jev returns judgments, not generated memories or embeddings. Its confidence is
+distribution concentration, **not a probability of correctness**. Pinning the
+model and criteria makes requests reproducible but does not promise deterministic
+provider answers. Keep structural validation and authorization deterministic.
+
+Other providers, including local implementations, can implement the public
+`DecisionProvider` interface; no OpenRouter dependency is required by callers:
+
+```ts
+import { assessDecisions, rankDecisionCandidates } from "@hasna/mementos/sdk";
+import type { DecisionProvider } from "@hasna/mementos/sdk";
+
+// `provider` is your adapter implementing DecisionProvider.
+async function rank(provider: DecisionProvider, query: string,
+  candidates: Array<{ id: string; text: string }>) {
+  const assessment = await assessDecisions({ task: "relevance", query, candidates }, {
+    enabled: true, retrieval: true, provider: provider.id, model: provider.model,
+  }, { provider });
+  return { assessment, candidates: rankDecisionCandidates(candidates, assessment) };
+}
+```
+
+Knowledge consumers can reuse this contract to assess already authorized
+retrieval candidates or flag potentially conflicting passages. Source citations,
+review state, and guarded publication remain the consumer's responsibility.
+
 ```bash
 mementos --help
 mementos <command> --help

package/dist/cli/commands/decisions.d.ts

@@ -0,0 +1,5 @@
+import type { Command } from "commander";
+import type { MemorySearchResult } from "../../types/index.js";
+export declare function decisionSearchResult(result: MemorySearchResult): Record<string, unknown>;
+export declare function registerDecisionCommands(program: Command): void;
+//# sourceMappingURL=decisions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"decisions.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/decisions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWzC,OAAO,KAAK,EAA+B,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAI5F,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAaxF;AAsBD,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAwI/D"}