# OpsMemory Chat Integration

> **Connecting Decision Memory to AI-Assisted Workflows**

## Overview

The OpsMemory Chat Integration connects organizational decision memory to AdvisoryAI Chat, enabling:

1. **Context Enrichment**: Past relevant decisions surface automatically in chat
2. **Decision Recording**: New decisions from chat actions are auto-recorded
3. **Feedback Loop**: Outcomes improve future AI suggestions
4. **Object Linking**: Structured references to decisions, issues, and tactics

## Architecture

```
┌──────────────────────────────────────────────────────────────────────┐
│                        Chat Session                                   │
│  ┌────────────────────────────────────────────────────────────────┐  │
│  │ User: "What should we do about CVE-2023-44487?"                │  │
│  └────────────────────────────────────────────────────────────────┘  │
│                                │                                      │
│                                ▼                                      │
│  ┌────────────────────────────────────────────────────────────────┐  │
│  │ OpsMemoryChatProvider.EnrichContextAsync()                     │  │
│  │   → Query similar past decisions                               │  │
│  │   → Include known issues and tactics                           │  │
│  │   → Return top-3 with outcomes                                 │  │
│  └────────────────────────────────────────────────────────────────┘  │
│                                │                                      │
│                                ▼                                      │
│  ┌────────────────────────────────────────────────────────────────┐  │
│  │ Prompt Assembly (via AdvisoryAiPromptContextEnricher)          │  │
│  │   System: "Previous similar situations..."                     │  │
│  │   - CVE-2022-41903 (same category): Accepted, SUCCESS          │  │
│  │   - CVE-2023-1234 (similar severity): Quarantined, SUCCESS     │  │
│  │   Known Issues: [ops-mem:issue-xyz123] may apply               │  │
│  └────────────────────────────────────────────────────────────────┘  │
│                                │                                      │
│                                ▼                                      │
│  ┌────────────────────────────────────────────────────────────────┐  │
│  │ Assistant Response with Object Links:                          │  │
│  │   "Based on 3 similar past decisions [ops-mem:dec-abc123]..."  │  │
│  │   [Accept Risk]{action:approve,cve_id=CVE-2023-44487}          │  │
│  └────────────────────────────────────────────────────────────────┘  │
│                                │                                      │
│                                ▼ (if action executed)                 │
│  ┌────────────────────────────────────────────────────────────────┐  │
│  │ OpsMemoryDecisionRecorder.RecordFromActionAsync()              │  │
│  │   → Extract situation from chat context                        │  │
│  │   → Record decision with action, rationale                     │  │
│  │   → Link to Run attestation                                    │  │
│  └────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────┘
```

## Core Components

### IOpsMemoryChatProvider

The main interface for chat context enrichment:

```csharp
public interface IOpsMemoryChatProvider
{
    /// <summary>
    /// Enriches chat context with relevant past decisions.
    /// </summary>
    Task<OpsMemoryChatContext> EnrichContextAsync(
        ChatEnrichmentRequest request,
        CancellationToken ct = default);

    /// <summary>
    /// Records a decision made during a chat session.
    /// </summary>
    Task RecordDecisionAsync(
        ChatDecisionRecord record,
        CancellationToken ct = default);
}
```

**Location:** `src/AdvisoryAI/StellaOps.AdvisoryAI/Chat/Integration/IOpsMemoryChatProvider.cs`

### OpsMemoryChatProvider

Implementation that queries OpsMemory and formats results for chat:

- **Similarity Search**: Finds past decisions with similar CVE/severity/category
- **Known Issues**: Includes relevant documented issues
- **Tactics**: Surfaces applicable response tactics
- **Fire-and-Forget Recording**: Async decision capture without blocking UX

**Location:** `src/AdvisoryAI/StellaOps.AdvisoryAI/Chat/Integration/OpsMemoryChatProvider.cs`

### AdvisoryAiPromptContextEnricher

Transforms OpsMemory context into AI prompt format:

```csharp
public interface IAdvisoryAiPromptContextEnricher
{
    /// <summary>
    /// Enriches AI prompt with OpsMemory context.
    /// </summary>
    Task<PromptEnrichmentResult> EnrichAsync(
        PromptEnrichmentRequest request,
        CancellationToken ct = default);
}
```

**Location:** `src/AdvisoryAI/StellaOps.AdvisoryAI/Chat/Integration/AdvisoryAiPromptContextEnricher.cs`

## Object Link Format

OpsMemory uses structured object links for cross-referencing:

| Type | Format | Example |
|------|--------|---------|
| Decision | `[ops-mem:dec-{id}]` | `[ops-mem:dec-abc12345]` |
| Known Issue | `[ops-mem:issue-{id}]` | `[ops-mem:issue-xyz98765]` |
| Tactic | `[ops-mem:tactic-{id}]` | `[ops-mem:tactic-respond-001]` |
| Playbook | `[ops-mem:playbook-{id}]` | `[ops-mem:playbook-log4j-response]` |

### Link Resolution

The `OpsMemoryLinkResolver` resolves object links to display text and URLs:

```csharp
public interface IObjectLinkResolver
{
    /// <summary>
    /// Resolves an object link to display information.
    /// </summary>
    Task<ObjectLinkResolution?> ResolveAsync(
        string objectLink,
        CancellationToken ct = default);
}
```

**Example Resolution:**

```
Input:  [ops-mem:dec-abc12345]
Output:
  - DisplayText: "Accept Risk decision for CVE-2022-41903"
  - Url: "/opsmemory/decisions/abc12345"
  - Metadata: { outcome: "SUCCESS", actor: "security-team" }
```

## Configuration

```yaml
AdvisoryAI:
  Chat:
    OpsMemory:
      # Enable OpsMemory integration
      Enabled: true

      # Maximum number of similar decisions to surface
      MaxSuggestions: 3

      # Minimum similarity score (0.0-1.0)
      MinSimilarity: 0.5

      # Include known issues in context
      IncludeKnownIssues: true

      # Include response tactics
      IncludeTactics: true

      # Automatically record decisions from actions
      RecordDecisions: true

OpsMemory:
  Integration:
    # Link recorded decisions to AI Run attestations
    AttestationLinking: true

    # Don't block chat flow on recording
    FireAndForget: true
```

## Known Issues and Tactics

### Known Issues

Document common false positives or expected behaviors:

```csharp
public interface IKnownIssueStore
{
    Task<KnownIssue?> GetByIdAsync(string id, CancellationToken ct);
    Task<IReadOnlyList<KnownIssue>> SearchAsync(
        KnownIssueSearchRequest request, CancellationToken ct);
}
```

**Example Known Issue:**
```json
{
  "id": "issue-log4j-test-code",
  "title": "Log4j in test dependencies",
  "description": "Log4j detected in test-scope dependencies is not exploitable in production",
  "applies_to": {
    "cve_pattern": "CVE-2021-44228",
    "scope": "test"
  },
  "recommended_action": "accept_risk",
  "status": "active"
}
```

### Response Tactics

Pre-defined response strategies for common situations:

```csharp
public interface ITacticStore
{
    Task<Tactic?> GetByIdAsync(string id, CancellationToken ct);
    Task<IReadOnlyList<Tactic>> GetMatchingTacticsAsync(
        TacticMatchRequest request, CancellationToken ct);
}
```

**Example Tactic:**
```json
{
  "id": "tactic-quarantine-critical",
  "name": "Quarantine Critical Vulnerabilities",
  "trigger": {
    "severity": ["CRITICAL"],
    "reachability": ["REACHABLE", "UNKNOWN"]
  },
  "steps": [
    "Block deployment to production",
    "Notify security team",
    "Schedule remediation within 24h"
  ],
  "automation": {
    "action": "quarantine",
    "notify_channel": "#security-alerts"
  }
}
```

## Integration Points

### AdvisoryAI Integration

Register OpsMemory integration during startup:

```csharp
services.AddAdvisoryAIOpsMemoryIntegration(options =>
{
    options.Enabled = true;
    options.MaxSuggestions = 3;
    options.IncludeKnownIssues = true;
    options.IncludeTactics = true;
});
```

### Chat Flow Integration

The integration hooks into the chat pipeline:

1. **Pre-Prompt**: `AdvisoryAiPromptContextEnricher` adds OpsMemory context
2. **Response**: AI references past decisions with object links
3. **Post-Action**: `OpsMemoryChatProvider.RecordDecisionAsync` captures the decision

## Best Practices

### Tuning Similarity Threshold

- **0.3-0.5**: Broader matches, may include less relevant decisions
- **0.5-0.7**: Balanced - recommended starting point
- **0.7+**: Strict matching, only very similar situations

### Recording Quality Decisions

For decisions to be useful for future suggestions:

1. **Include Context**: CVE ID, severity, package information
2. **Clear Rationale**: Why this action was chosen
3. **Track Outcomes**: Update with SUCCESS/FAILURE after implementation

### Managing Known Issues

- Review quarterly for relevance
- Archive issues for CVEs that are fully remediated
- Keep issue descriptions actionable

## Testing

### Unit Tests

Located in `src/AdvisoryAI/__Tests/StellaOps.AdvisoryAI.Tests/Chat/Integration/`:

- `OpsMemoryChatProviderTests.cs` - Provider functionality
- `AdvisoryAiPromptContextEnricherTests.cs` - Prompt enrichment

### Integration Tests

Located in `src/OpsMemory/__Tests/StellaOps.OpsMemory.Tests/Integration/`:

- `OpsMemoryChatProviderIntegrationTests.cs` - Full flow with PostgreSQL

## Related Documentation

- [OpsMemory Architecture](architecture.md) - Core OpsMemory design
- [AdvisoryAI Architecture](../advisory-ai/architecture.md) - AI assistant design
- [Decision Recording API](../../api/opsmemory.md) - REST API reference

---

_Last updated: 10-Jan-2026_