Automatic Learning

01. How It Learns Automatically

Every time Hebbrix answers a question, it runs 6 automatic quality checks. Every time an agent gets corrected, the correction is stored permanently. No human labeling, no thumbs up/down. Fully automatic.

1. Self-Consistency Check. Generates the same answer multiple times. If answers match → high confidence → positive reward.
2. Bidirectional NLI Grounding. Uses bidirectional Natural Language Inference to verify answers are grounded in actual memories. Checks in both directions to accurately detect contradictions, duplicates, and updates: 92% accuracy on complex memory pairs.
3. LLM-as-Judge. The AI evaluates its own answer quality: accuracy, completeness, and grounding in facts.
4. Answer Quality Heuristics. Checks length, specificity, and confidence. Contains numbers/dates? Good. Vague hedging? Bad.
5. Memory Attribution. Tracks which memories actually contributed to the answer. Good memories get rewarded and surface more often. Unhelpful memories naturally fade.
6. Retrieval Quality. Measures how well retrieved memories matched the query across vector similarity, keyword matching, and knowledge graph traversal.

02. Agent Autonomy Features

Three new APIs that make AI agents stop asking users repetitive questions:

• Confidence Scoring. Agents fetch confidence scores from GET /v1/confidence before acting to check "do I know enough to act without asking the user?" Returns a score and recommendation: act autonomously, proceed with caution, or ask the user.
• Correction Memory. When a user corrects an agent, it calls POST /v1/corrections. The correction is stored permanently. Next time any agent handles a similar situation, it checks corrections first, so the same mistake never happens twice. You can also submit explicit user feedback via POST /v1/feedback/relevance (see the API Reference below for the full feedback, decisions, and confidence schemas).
• Decision Outcome Logging. Agents log every decision and its outcome via POST /v1/decisions. Success? Failure? User satisfied? This feeds into the RL training pipeline so the system learns which decisions lead to good outcomes.

03. What Happens Behind the Scenes

1. User asks a question
2. Hebbrix searches memories and generates answer
3. Automatic reward calculator evaluates answer quality (-1 to +1)
4. LLM-as-Judge determines which memories contributed
5. Useful memories get their access_count increased
6. Next time, better memories appear first

04. Safety & Quality Controls

• Constitutional Constraints. Hard safety rules the RL system cannot override: never delete frequently-accessed memories, never delete recent memories, rate-limit destructive operations. These protect your data regardless of what the policy learns.
• Data Quality Gates. Every training batch is validated before it reaches the policy: reward range checks, variance checks (prevents training collapse), and distribution shift detection. Garbage data never corrupts the learning.
• Reward Health Monitoring. Continuous monitoring detects entropy collapse (policy stopped exploring) and reward gaming (agent exploiting the reward function). Training is automatically paused if anomalies are detected.
• Per-Request RL Controls. RL features are opt-out per request. Set use_rl_ranking: false or use_rl_reranking: false in your search request to get pure retrieval without any RL influence.

05. Research-Backed

Our approach implements techniques from 2024-2026 research:

• Memory-R1 (arXiv:2508.19828): GRPO for memory-based RL
• Mem-alpha (arXiv:2509.25911): Composite reward for memory construction
• RLSR (2025): Self-Reward for LLMs
• Self-RAG (ICLR 2024): Self-Reflective RAG
• DeepSeek-R1 (Nature 2025): GRPO training methodology
• DAPO (arXiv:2503.14476): Fixes for GRPO training stability

06. API Reference

The learning loop is fully automatic, but these endpoints let an agent check confidence before acting, log decisions and outcomes, store corrections, and submit explicit feedback. All require authentication (Authorization: Bearer <api_key>).

07. Schemas & Scoping

Two rules trip agents up most often: the strict enums on the create schemas, and the difference between the create body and the read endpoint's query parameter.

• decisions.outcome normalizes to an enum. POST /v1/decisions stores one of success, failure, partial, or unknown (default unknown), but accepts common synonyms and maps them, e.g. positive/good/ok/pass → success, negative/bad/fail/error → failure, mixed → partial, neutral/na → unknown. Only a genuinely-unrecognized value, for example safe_block, returns HTTP 422. decision_type is a free string up to 50 chars; description is required.
• corrections.correction_type is an optional enum. POST /v1/corrections requires only corrected_content; correction_type is optional and defaults to preference. When supplied it must be one of preference, factual, or procedural — any other value returns HTTP 422.

Tenant isolation via collection_id. Both corrections and decisions are tenant-isolatable. Pass collection_id when creating to scope a record to one collection. On the read endpoints, collection_id enforces strict isolation (only that collection's records), and include_global additionally folds in account-wide records. Omitting collection_id keeps everything account-wide, fully backward compatible.

# Create a correction scoped to one tenant/collection
curl -X POST https://api.hebbrix.com/v1/corrections \
  -H "Authorization: Bearer $HEBBRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "corrected_content": "Refund approvals above \$500 require human review",
    "correction_type": "procedural",
    "original_content": "above \$250 require human review",
    "collection_id": "col_tenant_acme"
  }'

# Read corrections for that tenant only (strict isolation)
curl "https://api.hebbrix.com/v1/corrections/relevant?query=approve+a+refund&collection_id=col_tenant_acme" \
  -H "Authorization: Bearer $HEBBRIX_API_KEY"

# ...or include account-wide corrections alongside the tenant's
curl "https://api.hebbrix.com/v1/corrections/relevant?query=approve+a+refund&collection_id=col_tenant_acme&include_global=true" \
  -H "Authorization: Bearer $HEBBRIX_API_KEY"

# Log a decision (outcome normalizes to success|failure|partial|unknown, synonyms accepted; query is NOT a body field)
curl -X POST https://api.hebbrix.com/v1/decisions \
  -H "Authorization: Bearer $HEBBRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decision_type": "refund_approval",
    "description": "Auto-approved a \$120 refund",
    "outcome": "success",
    "agent_confidence": 0.82,
    "collection_id": "col_tenant_acme"
  }'