@cntxt-labs/medha-cli 0.5.0 → 0.7.0

package/README.md

@@ -16,10 +16,57 @@ decides an action; you and your agent decide what to do with it.
   treated like 200 out of 200.
 - **Explainable.** Every number can be traced: `medha show` splits trust into its components and
   `medha explain-threshold` says which bars were cleared and which were not.
-- **Safe to try.** `medha simulate` shows what a signal would do without recording anything.
 - **One binary, no server.** CLI and MCP server in a single executable. State is an append-only
   episode log you can back up, compact, sync, or replay.
 
+> [!NOTE]
+> **Rust Core & TypeScript Hybrid Acceleration**: Medha provides both an active, full-featured TypeScript CLI/library ecosystem and a high-performance native Rust core. The native algorithms and trust computations are directly bridged to TypeScript and Node.js/Bun through our NAPI-RS adapter (`@cntxt-labs/medha-napi` / `crates/medha-napi`), providing native execution speeds while keeping the TypeScript CLI and npm packages fully supported. Standalone Rust binaries are also available (`crates/medha-cli`).
+
+## Mental Model: The Dual-Loop Architecture
+
+Most memory tools store unstructured chat history or flat key-value assertions. Medha acts as an **evidential calibration loop**:
+
+```text
+                    THE DUAL-LOOP MENTAL MODEL
+ 
+  ┌──────────────────────────────────────────────────────────────┐
+  │                 FAST INNER LOOP: EXECUTION                   │
+  │                                                              │
+  │   Agent Task ──► Query Trust Hints ──► Context Injection     │
+  │                         │                                    │
+  │                         ▼                                    │
+  │               Should I apply this rule?                      │
+  │              (Agent / Human Decision)                        │
+  └────────────────────────┬─────────────────────────────────────┘
+                           │ Outcomes observed
+                           ▼
+  ┌──────────────────────────────────────────────────────────────┐
+  │                 SLOW OUTER LOOP: EVIDENCE                    │
+  │                                                              │
+  │   Record Signals & Guard Checks (APPLY, REJECT, PASS/FAIL)   │
+  │                         │                                    │
+  │                         ▼                                    │
+  │              Evidential Trust Engine                         │
+  │        T = min(Ceiling, L × G × R × D)                       │
+  │     Wilson Lower Bound (L) × Guard Factor (G)                │
+  │     × Recency Decay (R) × Durability (D)                     │
+  │                         │                                    │
+  │                         ▼                                    │
+  │       Calibrated Status: Probation ──► Active ──► Trusted    │
+  │                                 └──► Quarantined / Retired   │
+  └──────────────────────────────────────────────────────────────┘
+```
+
+- **The Fast Inner Loop**: When starting a task, agents query `hints` or `medha show`. Entities with high trust are injected into active context; probation or quarantined entities are discounted or ignored. **Medha reports evidence; you decide.**
+- **The Slow Outer Loop**: As actions execute, the agent or test runner reports ground truth: did the rule work (`APPLY`), did a human reject it (`REJECT_RULE`), did an automated test pass (`guard --ok`)?
+- **Trust Formula ($T$)**:
+  $$T = \min\big(\text{ceiling}, L \times G \times R \times D\big)$$
+  - **$L$ (Wilson Lower Bound)**: 95% confidence interval on success rate $k/n$. Protects against small-sample overconfidence ($2/2 \ne 200/200$).
+  - **$G$ (Guard Factor)**: 1.0 if verified by test/AST guard; penalized if failing or unverified.
+  - **$R$ (Recency Decay)**: Exponential decay based on time elapsed since last use (default 30-day half-life, floor 0.20).
+  - **$D$ (Durability Factor)**: Logarithmic bonus for rules validated across multiple git commits, branches, or weeks.
+  - **Ceiling**: Unguarded entities cannot exceed 0.85, preventing unverified heuristics from becoming `trusted`.
+
 ## Install
 
 ```sh
@@ -115,6 +162,32 @@ Report the result with `medha guard --ok` or `--fail`.
 Entity state is a fold over that log, so it can always be rebuilt, audited, or corrected
 (`medha retract`, `medha remove-episode`).
 
+**Decision tree.** An entity can carry a tree of *branches*, each a condition plus a decision
+(`apply`, `ignore`, or a probability). Branches earn their own trust from their own evidence, which
+is what you want when a rule only holds in one situation: "always skip migration backups" can be
+excellent advice in CI and wrong on a laptop.
+
+```sh
+medha decision --id migration-notes --condition "in CI" --apply
+medha decision --id migration-notes --condition "on a laptop" --ignore --parent <case-id>
+```
+
+Evidence is then attributed to a branch as well as to the entity, so a branch can read `trusted`
+while the entity as a whole reads `probation`:
+
+```sh
+medha record --id migration-notes --signal APPLY --case-id <case-id>
+```
+
+`caseId` must name a branch of that entity — a typo is rejected rather than silently filed against
+the entity. Attributing evidence to a branch never *replaces* the entity-level fold; it is a second
+view of the same signal.
+
+Editing a branch (`medha decision --id .. --condition .. --case-id <case-id>`) changes its decision
+and leaves it where it is. Pass `--parent <case-id>` to move it, or `--detach` to promote it to the
+top level. Writes that name an unknown parent, a descendant of themselves, or a condition a sibling
+already uses are rejected.
+
 ### How trust is computed
 
 ```
@@ -163,7 +236,8 @@ Then copy [`SKILL.md`](SKILL.md) to
 | `hints` | Batch-fetch trust hints for the entities you are about to rely on. Returns `{ hints, unknown }`; treat `unknown` as probation. |
 | `list_entities` | Paginated search by kind, status, namespace or drift. |
 | `show_entity` | Full detail for one entity: components, temporal state, recent episodes. |
-| `record_signal` | Record `APPLY`, `REJECT_RULE`, `SKIP`, and so on. Returns `recorded: false` for an unknown entity unless `ensure` is set. |
+| `record_signal` | Record `APPLY`, `REJECT_RULE`, `SKIP`, and so on. Returns `recorded: false` for an unknown entity unless `ensure` is set. Pass `caseId` to also teach a decision-tree branch. |
+| `record_decision` | Create or edit a branch of an entity's decision tree. Pass `parentId` to nest it, or `detach: true` to promote it to the top level. Returns the minted `caseId`. |
 | `report_guard` | Record a guard result. |
 | `propose` | Submit a candidate entity. |
 | `drift` | List drifting entities. |
@@ -179,6 +253,7 @@ host can inject the most trusted guidance without overrunning its context.
 
 - **`medha ui`** launches a local web dashboard over the store.
 - **`medha report`** writes a standalone, offline HTML snapshot you can attach to a review.
+- **`medha issue [title]`** prepares a GitHub issue prefilled with sanitized runtime and store diagnostics.
 - **`medha sync status|pull|push`** shares evidence between machines through a git ref or a file.
   Registries travel with the episodes, so custom kinds and signals do not have to be copied by hand.
 
@@ -186,9 +261,57 @@ host can inject the most trusted guidance without overrunning its context.
 
 - **Kinds and signals.** Register your own in `.medha/config.json`. A kind can set its own trust
   thresholds and recency half-life, and can weight evidence by a signal's value (for example, a
-  timeout counts less against a tool than a crash).
+  timeout counts less against a tool than a crash). See [Kind specs](#kind-specs) below.
 - **Weight updaters.** Swap how evidence moves trust with `medha updater list` and `medha updater fork <name>`, which scaffolds a custom one.
 
+### Kind specs
+
+A **kind spec** gives one kind its own policy. Pass them to `medha init --config <file>`:
+
+```json
+{
+  "kindSpecs": [
+    {
+      "name": "lint",
+      "description": "linter rules: frequent, cheap evidence",
+      "thresholds": { "active": 0.15, "trusted": 0.4, "minUsesForTrusted": 3 },
+      "recency": { "halfLifeDays": 20, "floor": 0.2 },
+      "evidenceWeighting": "signal-value"
+    },
+    {
+      "name": "rule",
+      "signalLimits": { "maxSuccessesPerAuthor": 3 },
+      "decisionPolicy": { "requireHumanFor": ["apply"] }
+    }
+  ]
+}
+```
+
+```sh
+medha init --config medha.config.json
+```
+
+`--config` adds to the built-in kinds (`rule`, `recipe`, `tool`) rather than replacing them. A spec
+naming a new kind (`lint` above) also registers it, and a spec naming a built-in kind (`rule`) sets
+that kind's policy. Every field except `name` is optional, and a field you leave out keeps its
+default.
+
+| Field | Keys (default) | What it does |
+|---|---|---|
+| `thresholds` | `active` (0.25), `trusted` (0.6), `minUsesForTrusted` (5), `retiredTrustThreshold` (0.1), `minUsesForRetired` (3), `unguardedCeiling` (0.5) | Where the lifecycle transitions sit for this kind. `unguardedCeiling` caps trust while no guard has passed; no threshold lets an unguarded entity become `trusted`. |
+| `recency` | `halfLifeDays` (45), `floor` (0.3) | How fast old evidence fades, and the least it fades to. |
+| `evidenceWeighting` | `"count"` (default) or `"signal-value"` | Count each signal as one trial, or weight it by the signal's value. |
+| `signalLimits` | `minIntervalMs`, `maxSuccessesPerAuthor` (both off) | Limit how much one author can raise trust. Negative evidence is never limited. |
+| `decisionPolicy` | `requireHumanFor`: `"apply"` or a list of `apply`/`ignore`/`probability` (off) | Decision-tree branches of these types need a `human:` author. This is a label the caller sets, not verification: it stops an agent that follows instructions, not one that lies. |
+
+Config files are strict: an unknown key, such as `kindPolicies` or `thresholds.bogus`, is refused with
+the list of allowed keys, so a typo cannot quietly leave a policy switched off.
+
+To change specs after `init`, edit `.medha/config.json`. There they live under
+`registries.kindSpecs`, and a new kind's name must also be added to `registries.kinds`. Run
+`medha maintain preflight` to check the result. [Extending medha](https://nimishph.github.io/medha/guide/extending)
+covers kinds, signals and updaters in depth.
+
 ## Maintain it
 
 ```sh

package/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: medha
+description: Evidential memory for rules, recipes and tools. Use when deciding how far to trust a review rule, recipe or tool based on how it has actually performed — record uses, rejections and guard results, and read back trust hints. Medha reports evidence; it never decides.
+---
+
+# medha
+
+Medha remembers how well rules, recipes and tools have actually worked and returns **trust hints**.
+You record evidence; **you** decide what to do with it.
+
+## Mental Model: Dual-Loop Architecture
+
+```text
+                    THE DUAL-LOOP MENTAL MODEL
+ 
+  ┌──────────────────────────────────────────────────────────────┐
+  │                 FAST INNER LOOP: EXECUTION                   │
+  │                                                              │
+  │   Agent Task ──► Query Trust Hints ──► Context Injection     │
+  │                         │                                    │
+  │                         ▼                                    │
+  │               Should I apply this rule?                      │
+  │              (Agent / Human Decision)                        │
+  └────────────────────────┬─────────────────────────────────────┘
+                           │ Outcomes observed
+                           ▼
+  ┌──────────────────────────────────────────────────────────────┐
+  │                 SLOW OUTER LOOP: EVIDENCE                    │
+  │                                                              │
+  │   Record Signals & Guard Checks (APPLY, REJECT, PASS/FAIL)   │
+  │                         │                                    │
+  │                         ▼                                    │
+  │              Evidential Trust Engine                         │
+  │        T = min(Ceiling, L × G × R × D)                       │
+  │     Wilson Lower Bound (L) × Guard Factor (G)                │
+  │     × Recency Decay (R) × Durability (D)                     │
+  │                         │                                    │
+  │                         ▼                                    │
+  │       Calibrated Status: Probation ──► Active ──► Trusted    │
+  │                                 └──► Quarantined / Retired   │
+  └──────────────────────────────────────────────────────────────┘
+```
+
+- **Fast Inner Loop**: Read `hints` (or `medha show`) before applying rules. Treat unknown entities as `probation`.
+- **Slow Outer Loop**: Report ground truth as events occur (`record_signal`, `report_guard`).
+- **Trust Formula**: $T = \min(\text{ceiling}, L \times G \times R \times D)$. Usage alone never exceeds 0.85; a passing guard is required to achieve `trusted`.
+
+## Setup
+
+Run once per project (creates `.medha/`; add it to `.gitignore` or commit it deliberately):
+
+```sh
+medha init
+```
+
+MCP server (register in `.mcp.json`): `{ "mcpServers": { "medha": { "command": "medha", "args": ["mcp", "serve"] } } }`
+
+## Entities
+
+An entity is addressed by `namespace` (default empty), `kind` (`rule` | `recipe` | `tool`, default
+`rule`) and `id`. New entities start on **probation**.
+
+## Per-kind policy (kindSpecs)
+
+A kind can carry its own policy. Set it at init with `medha init --config <file>`:
+
+```json
+{ "kindSpecs": [
+  { "name": "lint", "thresholds": { "active": 0.15, "trusted": 0.4, "minUsesForTrusted": 3 },
+    "recency": { "halfLifeDays": 20 }, "evidenceWeighting": "signal-value" },
+  { "name": "rule", "signalLimits": { "maxSuccessesPerAuthor": 3 },
+    "decisionPolicy": { "requireHumanFor": ["apply"] } }
+] }
+```
+
+- Allowed keys: `name`, `description`, `thresholds` (`active`, `trusted`, `minUsesForTrusted`,
+  `retiredTrustThreshold`, `minUsesForRetired`, `unguardedCeiling`), `recency` (`halfLifeDays`,
+  `floor`), `evidenceWeighting` (`count` | `signal-value`), `signalLimits` (`minIntervalMs`,
+  `maxSuccessesPerAuthor`), `decisionPolicy` (`requireHumanFor`). An unknown key is an error.
+- A spec for a new kind registers it too; built-in kinds stay. Omitted fields keep their defaults.
+- After init, specs live in `.medha/config.json` under `registries.kindSpecs`, and a new kind's
+  name must also be listed in `registries.kinds`. Check with `medha maintain preflight`.
+- `decisionPolicy.requireHumanFor` means **a human must run that command**. If you get
+  `CORE_PERMISSION_DENIED`, do not retry with a `human:` author. You can set that label yourself,
+  so passing it proves nothing. Escalate to a human instead.
+
+## Workflow
+
+1. **Read** before relying on a rule: MCP `hints` (pass `compact: true` for cheap output) or
+   `medha show --id <id>`. `hints` returns `{ hints, unknown }` — treat `unknown` keys as probation.
+2. **Propose** a new rule: `propose` / `medha propose --id <id> --source <who> [--text ..]`.
+3. **Record** evidence as it happens: `record_signal` / `medha record --id <id> --signal APPLY --ensure`.
+   Signals: `APPLY` (used and worked), `REJECT_RULE` (a human rejected it), `SKIP` (not applicable).
+   If the entity is unknown and `ensure` is not set, the response says `recorded: false` — nothing was written.
+4. **Report guards**: `report_guard` / `medha guard --id <id> --ok|--fail --guard review`.
+   Without a passing guard, trust is capped at 0.5 — usage alone never makes a rule `trusted`.
+5. **Explain**: `medha explain-threshold --id <id>` lists each threshold with ok/no and the numbers.
+6. **Preview** with `simulate` (persists nothing) before recording a consequential signal.
+
+## Branching a rule (only when a rule is only good sometimes)
+
+A rule that holds in one situation and not another belongs in a decision tree, not in a single
+trust number. `record_decision` mints a branch and returns its `caseId`:
+
+```
+record_decision { id, condition: "in CI",          decision: { type: "apply" } }
+record_decision { id, condition: "on a laptop",    decision: { type: "ignore" }, parentId: <first> }
+```
+
+Then attribute evidence to the branch, not just the entity:
+
+```
+record_signal { id, signal: "APPLY", caseId: <branch> }
+```
+
+Read a branch's own trust with `show_entity` — `decisionTree` lists each branch with its `parentId`,
+condition, evidence and status. Branch evidence is *in addition to* the entity's aggregate, never a
+replacement for it, so an entity can be `probation` while one branch is `trusted`.
+
+- `caseId` must be a real branch of that entity; a typo is rejected, not filed against the entity.
+- Editing a branch by `caseId` without `parentId` leaves it exactly where it is. Pass `parentId` to
+  move it, or `detach: true` to make it a root.
+- Two branches with the same condition under the same parent are rejected — the same condition once
+  under each of two roots is fine.
+
+## Lifecycle
+
+`probation → active → trusted`, and down to `quarantined` / `retired` on repeated rejection.
+`drift` lists entities whose recent behavior diverges from their baseline.
+
+## Rules of thumb
+
+- Trust is a hint, not a verdict: Wilson lower bound over successes/trials, decayed, gated by guards.
+- Use `--json` on any CLI command for machine output; `--home <dir>` to point at a shared home.
+- `medha maintain preflight` checks store integrity; `medha maintain backup <path>` exports a snapshot.

package/bin/medha.cjs

@@ -6,6 +6,7 @@
 // that matches the machine. This file finds it and runs it.
 
 const { spawnSync } = require('node:child_process');
+const { chmodSync } = require('node:fs');
 const path = require('node:path');
 
 const SUPPORTED = ['linux-x64', 'linux-arm64', 'darwin-arm64', 'darwin-x64', 'win32-x64'];
@@ -37,6 +38,29 @@ function locate(platform, cpu, resolve) {
   }
 }
 
+/**
+ * Restore the executable bit on the program, and say whether it worked.
+ *
+ * The published tarball is supposed to carry mode 0755, but a package can still arrive without it:
+ * an install that strips permissions, a copy through a filesystem or archive tool that does not keep
+ * them, or a version published before the mode was fixed. The program is always a program, so the
+ * bit is safe to set here — this is the difference between a one-line `chmod` the user has to guess
+ * and a command that just runs.
+ */
+function makeExecutable(program) {
+  try {
+    chmodSync(program, 0o755);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** True when a spawn failed only because the file was not executable. */
+function isPermissionFailure(error) {
+  return error !== undefined && error !== null && error.code === 'EACCES';
+}
+
 function main() {
   const found = locate(process.platform, process.arch, require.resolve);
   if (found.problem !== undefined) {
@@ -44,14 +68,27 @@ function main() {
     process.exitCode = 1;
     return;
   }
-  const child = spawnSync(found.program, process.argv.slice(2), {
-    stdio: 'inherit',
-    cwd: process.cwd(),
-  });
+  const run = () =>
+    spawnSync(found.program, process.argv.slice(2), { stdio: 'inherit', cwd: process.cwd() });
+
+  let child = run();
+  if (
+    isPermissionFailure(child.error) &&
+    process.platform !== 'win32' &&
+    makeExecutable(found.program)
+  ) {
+    child = run();
+  }
   if (child.error) {
     process.stderr.write(
       `medha: could not start ${path.basename(found.program)}: ${child.error.message}\n`,
     );
+    if (isPermissionFailure(child.error)) {
+      process.stderr.write(
+        `hint: ${found.program} is not executable and medha could not make it so. ` +
+          `Run: chmod +x "${found.program}"\n`,
+      );
+    }
     process.exitCode = 1;
     return;
   }
@@ -62,6 +99,6 @@ function main() {
   process.exitCode = child.status ?? 1;
 }
 
-module.exports = { SUPPORTED, platformPackage, locate };
+module.exports = { SUPPORTED, platformPackage, locate, makeExecutable, isPermissionFailure };
 
 if (require.main === module) main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cntxt-labs/medha-cli",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Evidential memory for rules, recipes and tools: records what happened and returns trust hints. CLI and MCP server.",
   "keywords": [
     "mcp",
@@ -40,11 +40,11 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@cntxt-labs/medha-linux-x64": "0.5.0",
-    "@cntxt-labs/medha-linux-arm64": "0.5.0",
-    "@cntxt-labs/medha-darwin-arm64": "0.5.0",
-    "@cntxt-labs/medha-darwin-x64": "0.5.0",
-    "@cntxt-labs/medha-win32-x64": "0.5.0"
+    "@cntxt-labs/medha-linux-x64": "0.7.0",
+    "@cntxt-labs/medha-linux-arm64": "0.7.0",
+    "@cntxt-labs/medha-darwin-arm64": "0.7.0",
+    "@cntxt-labs/medha-darwin-x64": "0.7.0",
+    "@cntxt-labs/medha-win32-x64": "0.7.0"
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",