poimen-memory/docs/api/T7_RANKING_API.md

T7.4: Multi-Signal Ranking API Reference

Overview

Advanced ranking with 7 configurable signals. Choose preset profiles or customize weights.

---

Signals

Semantic (Default Weight: 40%)

Vector similarity from pgvector. Range: 0.0-1.0.

• Higher = more semantically similar to query

Lexical (Default Weight: 25%)

BM25 ranking from OpenSearch. Range: 0.0-1.0.

• Higher = more lexically similar to query

Recency (Default Weight: 15%)

Time decay from last update. Formula: exp(-age_days / 30)

• Recent updates boost score
• 30-day half-life (score = 0.37 at 30 days)

Frequency (Default Weight: 10%)

Access count log scale. Formula: log(access_count + 1) / log(max_access + 1)

• Frequently accessed entities ranked higher
• Normalized to 0.0-1.0

Confidence (Default Weight: 5%)

Base confidence with staleness decay. Formula: base * exp(-staleness_days / 90)

• Entities confirmed recently score higher
• 90-day half-life

Community (Default Weight: 3%)

Activity in connected community. Range: 0.0-1.0.

• Factor 1: Community size (0-100 entities)
• Factor 2: Recent edges (0-50 edges in 7 days)
• Score = (size_factor + activity_factor) / 2

Contradiction (Default Weight: 2%)

Penalty for unresolved contradictions. Range: -0.3 to 0.0.

• Formula: -min(0.3, ratio * 0.3) where ratio = unresolved / total
• No contradictions = 0
• All contradictions = -0.3

---

Endpoints

GET /memory/ranking/profiles

List available ranking profiles

Request:

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/memory/ranking/profiles

Response (200 OK):

{
  "profiles": [
    {
      "name": "default",
      "description": "Balanced multi-signal ranking",
      "weights": {
        "semantic": 0.40,
        "lexical": 0.25,
        "recency": 0.15,
        "frequency": 0.10,
        "confidence": 0.05,
        "community": 0.03,
        "contradiction": 0.02
      }
    },
    {
      "name": "recency_focused",
      "description": "Prioritize recent updates",
      "weights": {
        "semantic": 0.30,
        "lexical": 0.15,
        "recency": 0.35,
        "frequency": 0.10,
        "confidence": 0.05,
        "community": 0.03,
        "contradiction": 0.02
      }
    },
    {
      "name": "accuracy_focused",
      "description": "Prioritize high-confidence, no contradictions",
      "weights": {
        "semantic": 0.35,
        "lexical": 0.20,
        "recency": 0.10,
        "frequency": 0.05,
        "confidence": 0.20,
        "community": 0.05,
        "contradiction": 0.05
      }
    }
  ]
}

---

POST /memory/query (with ranking profile)

Query with multi-signal ranking

Request:

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "kubernetes debugging",
    "ranking_profile": "recency_focused",
    "explain_ranking": true
  }' \
  http://localhost:8080/memory/query

Response (200 OK):

{
  "query": "kubernetes debugging",
  "ranking_profile": "recency_focused",
  "results": [
    {
      "id": "e_k8s_debug",
      "name": "Kubernetes Debugging",
      "final_score": 0.92,
      "signal_breakdown": {
        "semantic": {
          "raw": 0.95,
          "weight": 0.30,
          "contribution": 0.285
        },
        "lexical": {
          "raw": 0.88,
          "weight": 0.15,
          "contribution": 0.132
        },
        "recency": {
          "raw": 0.98,
          "weight": 0.35,
          "contribution": 0.343
        },
        "frequency": {
          "raw": 0.72,
          "weight": 0.10,
          "contribution": 0.072
        },
        "confidence": {
          "raw": 0.90,
          "weight": 0.05,
          "contribution": 0.045
        },
        "community": {
          "raw": 0.65,
          "weight": 0.03,
          "contribution": 0.020
        },
        "contradiction": {
          "raw": 0.0,
          "weight": 0.02,
          "contribution": 0.0
        }
      }
    }
  ],
  "search_time_ms": 145
}

---

Profiles

default

Balanced ranking across all signals.

When to use:

• General queries
• No specific ranking priority
• Balanced experience

recency_focused

Prioritize recently updated entities (35% weight).

When to use:

• Troubleshooting (recent solutions better)
• Current best practices
• Up-to-date documentation

Example:

curl -X POST http://localhost:8080/memory/query \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"query": "kubernetes 1.28 best practices", "ranking_profile": "recency_focused"}'

accuracy_focused

High confidence (20%) + minimal contradictions (5% penalty weight).

When to use:

• Critical decisions (production deployments)
• Compliance audits
• High-stakes troubleshooting

Example:

curl -X POST http://localhost:8080/memory/query \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"query": "database backup procedures", "ranking_profile": "accuracy_focused"}'

---

Custom Profiles (Future)

Currently, 3 preset profiles available. Future support for custom weights:

# (Not yet implemented)
curl -X POST http://localhost:8080/memory/ranking/profiles \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "my_custom",
    "weights": {
      "semantic": 0.5,
      "lexical": 0.3,
      "recency": 0.2,
      ...
    }
  }'

---

Signal Analysis

Score Contribution Example

Query: "kubernetes debugging" Profile: recency_focused

Signal	Raw	Weight	Contribution	Impact
semantic	0.95	0.30	0.285	High semantic match
lexical	0.88	0.15	0.132	Good BM25 match
recency	0.98	0.35	0.343	Very recent (days old)
frequency	0.72	0.10	0.072	Moderately accessed
confidence	0.90	0.05	0.045	Recently confirmed
community	0.65	0.03	0.020	Active community
contradiction	0.0	0.02	0.0	No issues
TOTAL			0.897	89.7% relevance

---

Tuning Guide

If results are too general

• Increase semantic weight (0.40 → 0.50)
• Decrease lexical weight (0.25 → 0.15)
• Use accuracy_focused profile

If results are too fresh

• Decrease recency weight (0.15 → 0.05)
• Increase confidence weight (0.05 → 0.15)
• Use accuracy_focused profile

If results have errors

• Increase contradiction penalty (0.02 → 0.10)
• Increase confidence weight (0.05 → 0.20)
• Use accuracy_focused profile

---

Rate Limits

Endpoint	Limit
/ranking/profiles	200/hr
/query with profile	1000/hr

---

Performance

• Signal computation: < 20ms overhead per query
• Signal cache: 5-minute TTL
• Multi-signal ranking: No additional latency for scoring