@cntxt-labs/medha-cli 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +49 -1
  2. package/SKILL.md +37 -0
  3. package/package.json +6 -6
package/README.md CHANGED
@@ -16,10 +16,57 @@ decides an action; you and your agent decide what to do with it.
16
16
  treated like 200 out of 200.
17
17
  - **Explainable.** Every number can be traced: `medha show` splits trust into its components and
18
18
  `medha explain-threshold` says which bars were cleared and which were not.
19
- - **Safe to try.** `medha simulate` shows what a signal would do without recording anything.
20
19
  - **One binary, no server.** CLI and MCP server in a single executable. State is an append-only
21
20
  episode log you can back up, compact, sync, or replay.
22
21
 
22
+ > [!NOTE]
23
+ > **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`).
24
+
25
+ ## Mental Model: The Dual-Loop Architecture
26
+
27
+ Most memory tools store unstructured chat history or flat key-value assertions. Medha acts as an **evidential calibration loop**:
28
+
29
+ ```text
30
+ THE DUAL-LOOP MENTAL MODEL
31
+
32
+ ┌──────────────────────────────────────────────────────────────┐
33
+ │ FAST INNER LOOP: EXECUTION │
34
+ │ │
35
+ │ Agent Task ──► Query Trust Hints ──► Context Injection │
36
+ │ │ │
37
+ │ ▼ │
38
+ │ Should I apply this rule? │
39
+ │ (Agent / Human Decision) │
40
+ └────────────────────────┬─────────────────────────────────────┘
41
+ │ Outcomes observed
42
+ ▼
43
+ ┌──────────────────────────────────────────────────────────────┐
44
+ │ SLOW OUTER LOOP: EVIDENCE │
45
+ │ │
46
+ │ Record Signals & Guard Checks (APPLY, REJECT, PASS/FAIL) │
47
+ │ │ │
48
+ │ ▼ │
49
+ │ Evidential Trust Engine │
50
+ │ T = min(Ceiling, L × G × R × D) │
51
+ │ Wilson Lower Bound (L) × Guard Factor (G) │
52
+ │ × Recency Decay (R) × Durability (D) │
53
+ │ │ │
54
+ │ ▼ │
55
+ │ Calibrated Status: Probation ──► Active ──► Trusted │
56
+ │ └──► Quarantined / Retired │
57
+ └──────────────────────────────────────────────────────────────┘
58
+ ```
59
+
60
+ - **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.**
61
+ - **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`)?
62
+ - **Trust Formula ($T$)**:
63
+ $$T = \min\big(\text{ceiling}, L \times G \times R \times D\big)$$
64
+ - **$L$ (Wilson Lower Bound)**: 95% confidence interval on success rate $k/n$. Protects against small-sample overconfidence ($2/2 \ne 200/200$).
65
+ - **$G$ (Guard Factor)**: 1.0 if verified by test/AST guard; penalized if failing or unverified.
66
+ - **$R$ (Recency Decay)**: Exponential decay based on time elapsed since last use (default 30-day half-life, floor 0.20).
67
+ - **$D$ (Durability Factor)**: Logarithmic bonus for rules validated across multiple git commits, branches, or weeks.
68
+ - **Ceiling**: Unguarded entities cannot exceed 0.85, preventing unverified heuristics from becoming `trusted`.
69
+
23
70
  ## Install
24
71
 
25
72
  ```sh
@@ -206,6 +253,7 @@ host can inject the most trusted guidance without overrunning its context.
206
253
 
207
254
  - **`medha ui`** launches a local web dashboard over the store.
208
255
  - **`medha report`** writes a standalone, offline HTML snapshot you can attach to a review.
256
+ - **`medha issue [title]`** prepares a GitHub issue prefilled with sanitized runtime and store diagnostics.
209
257
  - **`medha sync status|pull|push`** shares evidence between machines through a git ref or a file.
210
258
  Registries travel with the episodes, so custom kinds and signals do not have to be copied by hand.
211
259
 
package/SKILL.md CHANGED
@@ -8,6 +8,43 @@ description: Evidential memory for rules, recipes and tools. Use when deciding h
8
8
  Medha remembers how well rules, recipes and tools have actually worked and returns **trust hints**.
9
9
  You record evidence; **you** decide what to do with it.
10
10
 
11
+ ## Mental Model: Dual-Loop Architecture
12
+
13
+ ```text
14
+ THE DUAL-LOOP MENTAL MODEL
15
+
16
+ ┌──────────────────────────────────────────────────────────────┐
17
+ │ FAST INNER LOOP: EXECUTION │
18
+ │ │
19
+ │ Agent Task ──► Query Trust Hints ──► Context Injection │
20
+ │ │ │
21
+ │ ▼ │
22
+ │ Should I apply this rule? │
23
+ │ (Agent / Human Decision) │
24
+ └────────────────────────┬─────────────────────────────────────┘
25
+ │ Outcomes observed
26
+ ▼
27
+ ┌──────────────────────────────────────────────────────────────┐
28
+ │ SLOW OUTER LOOP: EVIDENCE │
29
+ │ │
30
+ │ Record Signals & Guard Checks (APPLY, REJECT, PASS/FAIL) │
31
+ │ │ │
32
+ │ ▼ │
33
+ │ Evidential Trust Engine │
34
+ │ T = min(Ceiling, L × G × R × D) │
35
+ │ Wilson Lower Bound (L) × Guard Factor (G) │
36
+ │ × Recency Decay (R) × Durability (D) │
37
+ │ │ │
38
+ │ ▼ │
39
+ │ Calibrated Status: Probation ──► Active ──► Trusted │
40
+ │ └──► Quarantined / Retired │
41
+ └──────────────────────────────────────────────────────────────┘
42
+ ```
43
+
44
+ - **Fast Inner Loop**: Read `hints` (or `medha show`) before applying rules. Treat unknown entities as `probation`.
45
+ - **Slow Outer Loop**: Report ground truth as events occur (`record_signal`, `report_guard`).
46
+ - **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`.
47
+
11
48
  ## Setup
12
49
 
13
50
  Run once per project (creates `.medha/`; add it to `.gitignore` or commit it deliberately):
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cntxt-labs/medha-cli",
3
- "version": "0.6.0",
3
+ "version": "0.7.0",
4
4
  "description": "Evidential memory for rules, recipes and tools: records what happened and returns trust hints. CLI and MCP server.",
5
5
  "keywords": [
6
6
  "mcp",
@@ -40,11 +40,11 @@
40
40
  "node": ">=18"
41
41
  },
42
42
  "optionalDependencies": {
43
- "@cntxt-labs/medha-linux-x64": "0.6.0",
44
- "@cntxt-labs/medha-linux-arm64": "0.6.0",
45
- "@cntxt-labs/medha-darwin-arm64": "0.6.0",
46
- "@cntxt-labs/medha-darwin-x64": "0.6.0",
47
- "@cntxt-labs/medha-win32-x64": "0.6.0"
43
+ "@cntxt-labs/medha-linux-x64": "0.7.0",
44
+ "@cntxt-labs/medha-linux-arm64": "0.7.0",
45
+ "@cntxt-labs/medha-darwin-arm64": "0.7.0",
46
+ "@cntxt-labs/medha-darwin-x64": "0.7.0",
47
+ "@cntxt-labs/medha-win32-x64": "0.7.0"
48
48
  },
49
49
  "devDependencies": {
50
50
  "@modelcontextprotocol/sdk": "^1.30.0",