317 lines
12 KiB
Markdown
317 lines
12 KiB
Markdown
# 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_
|