Retrieval

When an enterprise knowledge base grows to hundreds or thousands of runbooks and configuration cards, how do you prevent context window pollution while ensuring that high-value prior experience is accurately recalled?

Mopheus rejects flat, one-dimensional text search. Instead, it couples multidimensional entity scoping (strong boundary isolation) with a native multi-language weighted full-text search engine and two-phase progressive matching to achieve deterministic and highly relevant experience matching.

Scoping Philosophy: Boundaries Before SearchCopy Anchor Link

In large-language-model context management, "less is more, precision beats recall." Injecting MySQL performance tuning guides into an Oracle migration task is not only a waste of tokens, but actively misleads the agent into running invalid SQL syntax.

Mopheus enforces Boundaries Before Search:

1. Orthogonal Isolation: Boundaries between assets, projects, and tech stacks are strictly partitioned. Private specs of one entity never leak into another.
2. Progressive Matching: Search expands smoothly from rigid entity constraints to universal conventions.
3. Anti-Hallucination Fallback: When no matching records exist for a specific scope, the system gracefully falls back to the global baseline instead of force-matching irrelevant records.

┌─────────────────────────────────────────────────────────────┐
│             Multidimensional Scoping & Search Funnel        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   Task Trigger / Query (with asset_id, db_type, project_id) │
│                         │                                   │
│                         ▼                                   │
│   [Tier 1: Rigid Entity Partitioning] Filter asset & project│
│                         │                                   │
│                         ▼                                   │
│   [Tier 2: Tech Stack Alignment] Match db_type & profile_id │
│                         │                                   │
│                         ▼                                   │
│   [Tier 3: Weighted FTS] Multi-language GIN + Two-Phase FTS │
│                         │                                   │
│                         ▼                                   │
│   [Tier 4: Precedence Reranking] Human Correction > Asset   │
│                         │                                   │
│                         ▼                                   │
│   Output: High-Confidence Candidates for MEMORY.md / API    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Multidimensional Scoping DimensionsCopy Anchor Link

Every memory card supports binding to the following metadata dimensions:

Global Facts vs. Asset-Specific FactsCopy Anchor Link

Understanding this distinction is essential to understanding Mopheus memory:

• Global Baseline Facts (L0): context_tags->>'asset_id' IS NULL and context_tags->>'user_id' IS NULL. These are universal rules for all agents in the workspace (e.g., "Container repository paths are mounted read-only", "API errors must use errx").
• Asset-Specific Facts (L2): context_tags->>'asset_id' = '<target_id>'. These contain private configurations for a specific host or database (e.g., SGA_MAX_SIZE=64G on Node 1). Any task not explicitly targeting that asset will never receive these cards.

Retrieval Engine Architecture & Execution PlanCopy Anchor Link

Mopheus operates without external semantic model services or vector database extensions. Retrieval is powered by native PostgreSQL multi-language weighted full-text search combined with dynamic scope weighting, delivering sub-millisecond, self-contained relational search.

              ┌───────────────────────────────┐
              │ Input Query (Error / Intent)  │
              └───────────────┬───────────────┘
                              │
              ┌───────────────┴───────────────┐
              │ normalizeMemoryRetrievalPlan  │
              │ (Error codes, scopes, tokens) │
              └───────────────┬───────────────┘
                              │
       ┌──────────────────────┼──────────────────────┐
       ▼                      ▼                      ▼
 [Layer 1: Global]      [Layer 2: Exact]       [Layer 3: Ranked]
 Universal Baselines    Exact Error Code Match Native Multi-Language FTS
 (Zero Scope Binding)   (context_tags contain) (zhparser & english GIN)
       │                      │                      │
       └──────────────────────┼──────────────────────┘
                              │
                              ▼
                [Two-Phase Fallback & Scope Weighting]
                Phase 1 (Strict AND) ──► Phase 2 (Ranked OR)
                Score = ts_rank * scope_weight
                              │
                              ▼
                [Final Deduplicated Top-K Results]

1. 3-Layer Execution PlanCopy Anchor Link

1. Layer 1: Global Baseline Layer (Global)
   When queries do not restrict types, the engine automatically retrieves zero-scoped environment_fact and preference cards as a baseline.
2. Layer 2: Exact Error Code Matching Layer (Exact)
   The engine extracts standardized error codes (e.g., ORA-01555, 42P01, PLS-00302) from the query string using regex patterns. If specific error codes are present, it directly matches them against error_resolution cards via JSONB containment.
3. Layer 3: Ranked Full-Text Search Layer (Ranked)
   For natural language descriptions, error messages, and operational runbooks, the engine executes weighted relevance matching over the underlying GIN inverted index.

2. Multi-Language Weighting & Two-Phase Progressive SearchCopy Anchor Link

• Field Weights & Tokenization:
  The content_tsv column is maintained by database triggers:
  • Weight A (Title): Highest weight (1.0), ensuring cards whose titles contain key search terms surface first.
  • Weight B (Content): Standard weight (0.4), matching detailed technical procedures and diagnostic logs.
  • Dual Tokenization: Concurrently supports the Chinese lexical parser (zhparser) and English dictionary (english), queried via plainto_tsquery.
• Two-Phase Progressive Search:
  • Phase 1: Strict AND Mode: Requires all parsed query keywords to appear in content_tsv, scored with ts_rank.
  • Phase 2: Ranked OR Fallback Mode: If Phase 1 yields insufficient results for the top-k quota, the engine splits terms with || and applies a strict relevance threshold (minRankedSimilarityThreshold >= 0.10) to eliminate low-quality noise.
• Trigram Similarity Fallback:
  If full-text search dictionaries are unavailable, the engine falls back to trigram/bigram similarity (pg_bigm or pg_trgm) to guarantee high availability.

3. Dynamic Scope WeightingCopy Anchor Link

Relevance scoring combines textual similarity (ts_rank) with contextual scope alignment:

$$\text{Final Score} = \text{Text Similarity} \times \text{scope_weight}$$

Where scope_weight is calculated as:

• 1.0 (Highest Confidence): If context_tags->>'profile_id' exactly matches the query environment profile.
• 0.6: If context_tags->>'db_type' exactly matches the query tech stack.
• 0.3: If the card is general institutional knowledge without specific scope bindings.

This ensures that runbooks verified on the exact target environment always rank above generic templates.

Precedence Ranking RulesCopy Anchor Link

In addition to mathematical similarity, Mopheus applies strict operational precedence rules:

1. Human Corrections (human_correction) Always Prioritized
   In default retrieval, human_correction cards rank alongside error_resolution and failure_scenario. Corrections from human engineers take precedence over automated agent suggestions.
2. Asset-Specific Knowledge Overrides Generic Defaults
   Cards bound to a specific asset_id receive strict filtering and elevated scope weights, ensuring physical host realities supersede generic standards.
3. Validation & Hit Frequency Weighting
   occurrence_count (times confirmed across tickets) and recall_hit_count (task retrieval frequency) serve as long-term confidence indicators.
4. Superseding Filtering
   Cards marked as deprecated via --supersedes or disabled via enabled = false are physically excluded from active recall, preventing obsolete instructions from misleading agents.

Dynamic Retrieval via CLICopy Anchor Link

During task execution, if an agent or human operator encounters an unexpected error not covered in MEMORY.md, they can run on-demand queries using mop memory retrieve:

# 1. Retrieve verified Oracle snapshot errors on a specific asset
mop memory retrieve "ORA-01555 snapshot too old" \
  --asset-id "9b2c34a1-0000-0000-0000-000000000001" \
  --db-type "oracle" \
  --top-k 5

# 2. Retrieve project-specific commit standards
mop memory retrieve "Conventional Commits" \
  --project-id "d3e4f5a6-0000-0000-0000-000000000002" \
  --type "preference"

# 3. Retrieve cloud-specific network timeout runbooks via context tags
mop memory retrieve "SLB healthcheck timeout" \
  --context-tags '{"env":"prod","cloud":"aliyun"}'

The CLI outputs matched card IDs, types, titles, relative OKF paths, occurrence counts, and last seen timestamps, allowing the agent to read the full card directly.

Safe Zero-Match FallbackCopy Anchor Link

When operating on a brand-new asset, a new project repo, or an unencountered failure, the query score may return zero matches.

In this scenario:

• No Hallucination: The system never pulls marginally related cards just to fill the context.
• Global Baseline Preserved: L0 global workspace guidelines remain in effect.
• Clear Guidance: Instructs the agent to proceed through disciplined diagnostics and trigger distillation upon completion.