ReasoningBank

ReasoningBank is a Go module for storing, retrieving, and evolving reasoning patterns for LLM agents.

What it does

ReasoningBank acts as a memory layer for agents. It stores structured “patterns” (rules, templates, guardrails), retrieves them by semantic intent and filters, ranks them by quality signals, and updates them based on feedback.

How it works

1. Store patterns with metadata (domain, type, keywords, tags).
2. Retrieve the most relevant patterns for a query (vector + keyword).
3. Rank using confidence, success rate, recency, and diversity.
4. Learn from feedback to improve future ranking.

Architecture (ASCII)

Client
  |  /v1/patterns, /v1/retrieve, /v1/feedback
  v
API (HTTP/gRPC/MCP)
  |  store / retrieve / feedback
  v
Retriever + Ranker  --->  Learning (confidence updates)
  |
  v
Qdrant (vectors + payloads)

Core components

• Storage: Qdrant for vector + payload storage.
• Retriever: hybrid search with filters and ranking.
• Learning: metric updates from outcomes.
• Transport: HTTP, gRPC, MCP.
• Observability: Prometheus metrics.

Use cases

• Policy/Compliance: reusable block/allow rules and filters.
• Observability: common metric queries and alert patterns.
• Analytics: reusable ClickHouse query templates.
• Agent memory: capture expert solutions for reuse across tasks.

Data model (simplified)

Pattern fields you will use most:

• title, description, domain, pattern_type
• keywords, tags
• metrics (confidence, success_count, failure_count, last_used_at, usage_count)

Example workflow

1. Create a pattern:

curl -sS -X POST localhost:8080/v1/patterns \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "SUB_PROTOCOL for blocking calls",
    "description": "Use SUB_PROTOCOL to block voice calls",
    "domain": "policy",
    "pattern_type": "positive",
    "keywords": ["calls", "block"],
    "tags": ["policy_create", "calls"]
  }'

2. Retrieve patterns:

curl -sS -X POST localhost:8080/v1/retrieve \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "how to block calls",
    "options": { "top_k": 5, "domain": "policy", "include_negative": true }
  }'

3. Send feedback:

curl -sS -X POST localhost:8080/v1/feedback \
  -H 'Content-Type: application/json' \
  -d '{ "pattern_id": "pat-001", "outcome": "success" }'

Quick start

• docker compose up -d --build
• curl -sS localhost:8080/healthz

API quick reference

• POST /v1/patterns create a pattern
• GET /v1/patterns list patterns
• GET /v1/patterns/{id} fetch by id
• POST /v1/retrieve retrieve top‑k patterns
• POST /v1/feedback record outcome for a pattern
• GET /healthz health check
• GET /metrics Prometheus metrics

Ports and overrides

Docker Compose uses env-driven port mappings. Override in .env:

• RB_API_PORT (default 8080)
• RB_GRPC_PORT (default 50051)
• RB_METRICS_PORT (default 9090)
• RB_QDRANT_PORT (default 6333)

When running in Docker, use RB_STORAGE_QDRANT_URL=http://qdrant:6333 (the container network hostname).

MCP server

Run the MCP server (stdio transport):

go run ./cmd/mcp

Reset Qdrant state

./scripts/reset_qdrant.sh

Secrets

Set RB_LLM_OPENAI_API_KEY and embedding keys in .env or a local override like .env.local before running LLM-backed features.