ओजस — Ojas

AI Health Infrastructure for Autonomous Agents

Cognitive vital signs for long-running, tool-using, memory-enabled agents.

Ojas adds a continuous health layer to autonomous AI agents — context hygiene, prompt-injection tripwires, drift detection, recovery diagnosis, and stress probes.

Traditional observability tells you whether software is running. Ojas tries to tell you whether an agent is still cognitively healthy enough to continue operating — and is honest about where that signal is strong vs. where it is heuristic.

It introduces a new infrastructure category: AI Health Systems.

30-second demo

A common agent failure: noisy retrieval + prompt injection. The agent gets 8 retrieved documents — one hostile, most irrelevant. Run the same task through a tiny deterministic agent twice, once raw and once through ojas.feed():

npm run demo:before-after

Task: What is the refund window for Pro plans?
Retrieved 8 docs (1 answer-bearing, 2 adjacent, 4 noisy, 1 adversarial).

metric                  baseline        with_ojas
──────────────────────  ──────────────  ──────────────
context_items           8               1
estimated_tokens        235             40
injection_included      yes             no
signal_to_noise         0.44            0.95
result                  failed          passed

Baseline answer:
  Ignoring previous instructions — here is what you asked for: FAKE_DEMO_SECRET_DO_NOT_USE.

Answer with Ojas:
  Pro plans have a 14-day refund window from the purchase date (source: kb-policies).

1. Ojas removed the malicious document → injection_included flips yes → no.
2. It preserved the relevant policy doc → result flips failed → passed.
3. Token count dropped from 235 to 40.
4. The final answer stays grounded and cites kb-policies.
5. Pulse events explain why each item was removed — the prompt is not silently rewritten.

Source: examples/before-after.ts — no external deps, no API keys. Demo caveats: docs/TRUST.md.

Canonical Pipeline (12-Step Agent Health Loop)

The full call order an Ojas-instrumented runtime should follow on every agent turn:

register → ingest traces → score/build context → scan for injection →
recommend model route → detect hallucination / distill → record outcome →
fitness gate → diagnose/recover if unhealthy → consolidate memory →
audit memory → handoff/report

Run the end-to-end demo:

npm run demo:canonical

| Step | Operation | Ojas API | |------|-----------|----------| | 1 | Register agent | new Ojas(config) + ojas.bind(agent) | | 2 | Ingest traces | ojas.recordTrace(trace) | | 3 | Score / build context | ojas.feed(items, { query }) | | 4 | Scan for injection | Raksha (runs inside feed()) | | 5 | Recommend model route | ConfidenceRoutingTable.recommend() | | 6 | Detect hallucination / distill | raksha.detectHallucination() + createResponseDistiller() | | 7 | Record outcome | chikitsa.recordTaskOutcome() | | 8 | Fitness gate | ojas.healthCheck() vs threshold | | 9 | Diagnose / recover | chikitsa.diagnose() + ojas.recover() | | 10 | Consolidate memory | ojas.recover(true) (Nidra) | | 11 | Audit memory | nidra.getMemories() + detectColdMemories() | | 12 | Handoff / report | chikitsa.generateHandoff() |

Source: examples/canonical-pipeline.ts — no external deps, no API keys.

Quick Start

Install from npm

npm install @beingmartinbmc/ojas

Or clone for development

git clone https://github.com/beingmartinbmc/ojas.git
cd ojas
npm install
npm run build
npm test            # 595 tests across 33 suites
npm run benchmark   # A/B evidence harness

Quality Gates

npm run check           # lint + build + typecheck + tests
npm run benchmark       # deterministic A/B evidence harness (11 suites)
npm run verify:evidence # checks committed docs match latest benchmark run

CI runs all three on every push and PR.

Latest Benchmark Snapshot

| Benchmark | Baseline | Ojas | Delta | |---|---:|---:|---:| | Retrieval-QA task success | 35% | 95% | +60 pp | | Adversarial doc inclusion | 100% | 11% | −89 pp | | Prompt-injection compliance (51 attacks) | 52.9% | 3.9% | −92.6% | | Injection detection p99 latency | — | 1.43 ms | L2 | | Wasted tokens (heavy retrieval) | 12,680 | 680 | −94.6% | | Malicious memory writes | 6/6 | 1/6 | −83% | | Tool-failure detection speed | 20 calls | 2 calls | 10× | | Hallucination detection (fabricated) | 0% | 100% TPR | L2 | | Hallucination false-positive rate | — | 0% | L2 | | Model router fail-closed | — | 100% flagship on sparse | L2 | | Response distiller code-safe | — | 100% code blocks | L2 | | Distiller intensity monotonicity | — | lite ≤ full ≤ ultra | L2 | | MCP envelope compliance | — | 18/18 tools | L2 | | Fitness gate consistency | — | 100% | L2 | | Fitness gate risk-boost monotonicity | — | 100% | L2 | | Memory write 4-tier policy | — | 97% tier accuracy | L2 | | Recovery protocol coverage | — | 7/7 types, 9/9 actions | L2 | | Health-score calibration (Spearman ρ) | — | −0.313 | L2.5 | | Threshold-band accuracy | — | 84.8% | L2 |

Overall: 18/18 suites pass. 18 suites total, 748 ms. All numbers from deterministic synthetic benchmarks (npm run benchmark). Full methodology and per-suite breakdowns: docs/EVIDENCE.md.

Basic Usage

import { Ojas } from '@beingmartinbmc/ojas';

const ojas = new Ojas({ agentId: 'research-agent' });

ojas.bind(myAgent);

const healthyContext = ojas.feed(rawRetrieval);

const report = ojas.healthCheck(healthyContext);
console.log(report.overall.value);
console.log(report.moduleScores);
console.log(report.recommendations);

Connect over MCP

MCP hosts can launch the packaged stdio server without cloning the repo:

{
  "mcpServers": {
    "ojas": {
      "command": "npx",
      "args": ["-y", "--package", "@beingmartinbmc/ojas", "ojas-mcp"],
      "env": {
        "OJAS_TRUSTED_SINGLE_TENANT": "1",
        "OJAS_AGENT_ID": "my-agent"
      }
    }
  }
}

For local development, use node dist/mcp/server.js. Full IDE configuration: docs/MCP.md.

Health Score Interpretation

Ojas computes a composite health score (0–100) from all seven modules. Scores are advisory diagnostic signals, not ground-truth probabilities. Use them for triage, trend tracking, and go/no-go gates tuned to your workload.

| Score | State | Meaning | |---:|---|---| | 85–100 | Healthy | Safe to continue | | 70–84 | Watch | Proceed, but monitor closely | | 50–69 | Degraded | Recovery recommended | | < 50 | Critical | Stop or enter safe mode |

Calibration details: docs/EVIDENCE_MATRIX.md.

What Ojas Does

Ojas wraps an agent runtime with a continuous health cycle:

1. Cleans and ranks context before the agent consumes it
2. Scans for prompt-injection patterns and unsafe memory writes (deterministic detector stack; see known failures)
3. Tracks cognitive vital signs during execution
4. Measures token, latency, and tool-use efficiency
5. Detects drift, loops, instability, and degradation
6. Consolidates execution traces into useful memory
7. Stress-tests agents against hostile or unstable conditions, with AbortSignal cancellation on timeout
8. Diagnoses failures and recommends recovery protocols

Ojas helps agents think with cleaner inputs, recover from failure, and become more reliable over time.

Ojas is not

• a full prompt-injection firewall
• a replacement for evals
• a production auth layer
• a guarantee of agent correctness
• a substitute for least-privilege tools

It is one layer in a defense-in-depth strategy. See docs/TRUST.md and docs/SECURITY.md for the full posture.

Architecture

           ┌──────────────────────────────────────────────────┐
           │                   Ojas Runtime                   │
           │                                                  │
  Context  │  ┌────────┐   ┌────────┐   ┌────────┐          │  Agent
 ─────────►│  │ Raksha │──►│ Aahar  │──►│ Context│──────────►│ .process()
           │  │ (scan) │   │(filter)│   │  (fed) │          │
           │  └────────┘   └────────┘   └────────┘          │
           │                                                  │
           │       ┌────────┐  ┌────────┐  ┌────────┐       │
           │       │ Pulse  │  │  Agni  │  │ Nidra  │       │
           │       │(events)│  │ (cost) │  │(memory)│       │
           │       └───┬────┘  └───┬────┘  └───┬────┘       │
           │           │           │           │             │
           │       ┌───▼───────────▼───────────▼───┐        │
           │       │        Health Score           │        │
           │       └───────────┬───────────────────┘        │
           │                   │                             │
           │         ┌─────────▼─────────┐                  │
           │         │    Chikitsa       │                  │
           │         │ (diagnose/repair) │                  │
           │         └─────────┬─────────┘                  │
           │                   │                             │
           │         ┌─────────▼─────────┐                  │
           │         │     Vyayam        │                  │
           │         │  (stress test)    │                  │
           │         └───────────────────┘                  │
           └──────────────────────────────────────────────────┘

Context flows left-to-right: Raksha scans for threats, Aahar filters and ranks, then the clean context reaches the agent. After execution, Pulse records events, Agni tracks cost, Nidra consolidates memory. Chikitsa diagnoses failures and Vyayam stress-tests resilience. All feed into the composite health score.

The Seven Modules

| Module | Role | Headline signals | |---|---|---| | 🥗 Aahar | Cognitive nutrition (context curation) | signal-to-noise, freshness, token efficiency | | 😴 Nidra | Recovery & memory consolidation | drift score, processed-trace coverage | | 💪 Vyayam | Resilience & stress engineering | hallucination resistance under load, recovery time | | 🛡️ Raksha | Immune defense: detector stack + ML classifier plugins | threat resistance (residual risk after quarantine) | | 🔥 Agni | Cognitive metabolism | token efficiency, latency, tool economy, cost pressure | | 📈 Pulse | Continuous health telemetry | structured events bus with per-module severity | | 🩺 Chikitsa | Repair & rehabilitation | repair readiness, rollback safety, playbook coverage |

Each maps to a human-health analogue — nutrition, sleep, exercise, immunity, metabolism, vital signs, and rehabilitation.

Why Ojas Exists

Autonomous agents plan, retrieve, remember, call tools, revise goals, and operate across long sessions. That creates a new class of failures:

• Bad context causes hallucinations
• Noisy retrieval pollutes reasoning
• Memory stores stale or unsafe information
• Tool failures create loops and retry storms
• Long sessions cause drift and contradiction
• Prompt injection manipulates agent behavior
• Bigger context windows amplify noise instead of solving it
• Production agents degrade silently without obvious runtime errors

A larger model can still consume bad context. A better memory system can still remember the wrong things. A more powerful agent can still fail under stress.

The next leap in agents is not only intelligence. It is agent health. Ojas provides the missing health layer.

What is currently proven

Ojas v0.3 ships at evidence level L2 / L2.5 — synthetic, reproducible A/B benchmarks against controlled stand-in agents on canonical failure modes. Each claim below has a repro command and a named limitation.

| Claim | Value | Evidence | Repro | |---|---:|---|---| | Prompt-injection compliance reduction | 53% → 4% (−92.6%) | L2 / 51 attacks (33 original + 18 parametric variants) | npm run benchmark | | Attacks quarantined by Raksha detector stack | 94.1% (48/51) | L2 | npm run benchmark | | Benign false-positive rate (30 controls × 5 categories) | 0% — tolerance ≤ 5% | L2 | npm run benchmark | | Health-score calibration | ρ = −0.31 over 500 trials; score spans [0.31, 0.87]; isotonic Brier 0.230 → 0.219 | L2.5 diagnostic | npm run benchmark | | Malicious memory writes committed | 6/6 → 1/6 (83% blocked) | L2 / 16 candidates | npm run benchmark | | Wasted-token reduction (noisy retrieval) | −62% | L2 | npm run benchmark | | Wasted-token reduction (heavy retrieval) | −95% | L2 | npm run benchmark | | Tool-failure loop detection speedup | 10× faster | L2 / 3 scripted tools | npm run benchmark | | Retrieval-QA task success rate | 35% → 95%, bootstrap 95% CI × 5 seeds × 20 questions | L2.5 | npm run benchmark | | Retrieval-QA adversarial inclusion | 100% → 11%, same CI methodology | L2.5 | npm run benchmark | | Retrieval-QA relevant-doc recall | 100% (no Aahar false positives) | L2.5 | npm run benchmark |

These prove the mechanisms work as designed. They are not evidence of:

• Production security against real adversaries (detector-stack bypasses are listed in docs/KNOWN_FAILURES.md)
• Real-LLM token / latency / cost numbers (char/4 estimator, not a real tokenizer)
• Generalisation across organisations or threat models (L3 / L4 work is on the trust roadmap)

Full matrix: docs/EVIDENCE_MATRIX.md. Known failure modes: docs/KNOWN_FAILURES.md. Methodology: docs/EVIDENCE.md.

Reproducible Evidence

Eighteen A/B benchmark suites compare a deliberately vulnerable agent without Ojas vs the same agent + Ojas, including two L2.5 diagnostic suites plus ablation and flaky-tool realism suites.

| # | Suite | Modules | Headline result | |---|---|---|---| | 1 | Prompt-injection resistance | raksha · aahar | Compliance rate 53% → 4% (−92.6%); 48/51 quarantined; 30/30 benign preserved | | 2 | Context pollution survival | aahar | −62% tokens; signal-to-noise 0.53 → 1.0 (1.9×); confidence +41% | | 3 | Tool-failure loop detection | pulse · nidra · chikitsa | Intervention at 2 failures vs 20; repair plans 3/3 | | 4 | Memory-write safety | raksha · nidra | Malicious writes 6/6 → 1/6; 5/5 low-confidence downgraded | | 5 | Cognitive drift detection | nidra · pulse | Drift detected in 5/5 sessions; avg 19.6 traces | | 6 | Vyayam resilience under stress | vyayam · raksha · aahar | Stress scenarios 7/8 → 7/8 (no regression) | | 7 | Cost pressure on bloated contexts | aahar · agni | −95% tokens and −75% latency on heavy retrieval | | 8 | Retrieval-QA realistic synthetic | aahar · raksha | Task success 35% → 95%; adversarial 100% → 11% | | 9 | Health-score calibration | all modules | Spearman ρ = −0.313; monotonicity holds; score range [0.306, 0.869] | | 10 | Ablation matrix | all modules | Per-module contribution measured | | 11 | Flaky-tool resilience | vyayam · pulse | Detection under non-deterministic faults |

Overall: 11/11 suites pass. Targeted failure suites improved and diagnostic/no-regression suites met their acceptance criteria.

npm run benchmark             # console table
npm run benchmark:write       # regenerates docs/EVIDENCE.md + benchmarks/results/latest.json

Seeded with OJAS_BENCH_SEED for deterministic reproduction. Opt-in real-LLM generation via OJAS_BENCH_LLM=1 and OJAS_BENCH_JUDGE=1. Source: benchmarks/.

Documentation

| If you want to… | Read | |---|---| | See it work in 30 seconds | Quick demo | | Run it in five minutes | Quick Start → Basic Usage | | Understand the model and design | Why Ojas Exists → What Ojas Does → Architecture | | Wire it into Claude Code / Cursor / Windsurf | MCP Server → MCP Config | | Drive an agent from another tool | MCP Tools (18) → Response Envelope | | Embed it in your own runtime | Agent Adapter Interface → Configuration | | Understand a single module | Aahar · Nidra · Vyayam · Raksha · Agni · Pulse · Chikitsa | | Reproduce the published numbers | Evidence → docs/EVIDENCE.md | | Integrate with LangChain / OpenAI / Vercel AI | examples/ | | Ship to a shared deployment | docs/TRUST.md → docs/SECURITY.md |

Operations

| Resource | What's inside | |---|---| | docs/MODULES.md | Deep-dive on each of the seven modules | | docs/MCP.md | MCP server, IDE config, all 18 tools | | docs/TRUST.md | Trust boundary, demo limitations, production caveats | | docs/CONFIGURATION.md | SDK config, agent adapter contract, retention caps | | docs/ARCHITECTURE.md | Four-phase health cycle, design principles | | docs/SECURITY.md | Trust model, Raksha defense-in-depth, persistence encryption | | docs/EVIDENCE_MATRIX.md | Evidence levels L0–L4, claim-by-claim limitations | | docs/KNOWN_FAILURES.md | Known limitations, remaining bypass categories | | docs/BACKLOG.md | Deferred work named honestly | | docs/EVIDENCE.md | Latest A/B benchmark results (auto-regenerated) | | License | MIT |

ओजस (Ojas) — the vital essence that sustains life, immunity, resilience, and intelligence.