stemedb/.claude/guides/integrations/ai-coding-assistant-integration.md

# AI Coding Assistant Integration Guide

> Research report on integrating Episteme (StemeDB) with Claude Code, Gemini CLI, OpenAI Codex, and other AI coding assistants.

## Executive Summary

There are **three main integration approaches** for AI coding assistants, each with different trade-offs:

| Approach | Reliability | Complexity | Cross-Platform | Best For |
|----------|-------------|------------|----------------|----------|
| **Skills/Commands + CLI** | High | Low | Good | Direct, reliable integration |
| **Context Files (CLAUDE.md, AGENTS.md)** | High | Very Low | Excellent | Static knowledge, guidelines |
| **A2A Protocol** | Medium | Medium | Emerging | Agent-to-agent collaboration |
| **MCP Servers** | Variable | High | Good | Dynamic tools (when working) |

**Recommendation:** Start with **Skills + CLI tools** for reliability, use **context files** for static knowledge, and consider **A2A** for agent collaboration. MCP is powerful but has reliability concerns.

---

## Part 1: Integration Approaches Comparison

### Why MCP Can Be Problematic

MCP servers can be unreliable for several reasons:
- Connection management complexity (STDIO process lifecycle, HTTP session state)
- Protocol version mismatches between clients
- Authentication failures with OAuth 2.1 flows
- Tool search latency when many tools are registered
- Context window consumption from tool descriptions

### Recommended: Skills + CLI Integration

**Agent Skills** ([agentskills.io](https://agentskills.io)) provide a simpler, more reliable approach:

```
┌─────────────────────────────────────────────────────┐
│                 AI Coding Assistant                  │
│  (Claude Code, Gemini CLI, Codex, Cursor)           │
└────────────────────────┬────────────────────────────┘
                         │
         ┌───────────────┼───────────────┐
         │               │               │
         ▼               ▼               ▼
   ┌──────────┐   ┌──────────┐   ┌──────────┐
   │  SKILL.md │   │AGENTS.md │   │   CLI    │
   │  /command │   │ Context  │   │   Tool   │
   └──────────┘   └──────────┘   └──────────┘
         │               │               │
         └───────────────┼───────────────┘
                         │
                         ▼
              ┌─────────────────────┐
              │  episteme-cli       │
              │  (Rust binary)      │
              └─────────────────────┘
                         │
                         ▼
              ┌─────────────────────┐
              │  StemeDB            │
              └─────────────────────┘
```

**Advantages:**
- Skills are just markdown files - no running processes
- CLI tools are standalone binaries - always available
- Context files are version-controlled and deterministic
- No connection management, no protocol negotiation
- Works offline, no authentication complexity

---

## Part 2: Agent Skills (SKILL.md)

### What Are Agent Skills?

Agent Skills are organized folders of instructions, scripts, and resources that AI assistants discover and load dynamically. They follow an open standard adopted by Claude Code, Codex, and others.

### SKILL.md Format

```yaml
---
name: episteme-query
description: Query the Episteme knowledge graph for assertions about a subject
disable-model-invocation: false
allowed-tools: Bash(episteme *)
---

# Episteme Query

Query the knowledge graph for information about a subject.

## Usage

```bash
episteme query --subject "$ARGUMENTS" --lens recency
```

## What to Look For

- Check for conflicting assertions
- Note the confidence levels
- Trace provenance if the source matters

## Output Format

Returns JSON with assertions matching the query.
```

### Skill Locations

| Location | Path | Scope |
|----------|------|-------|
| Personal | `~/.claude/skills/<name>/SKILL.md` | All your projects |
| Project | `.claude/skills/<name>/SKILL.md` | This project only |
| Codex | `~/.codex/skills/<name>/SKILL.md` | Codex sessions |

### Cross-Platform Compatibility

The Agent Skills specification ([agentskills.io](https://agentskills.io)) works across:
- Claude Code
- OpenAI Codex CLI
- Cursor
- Other compatible tools

**Key insight:** Write skills once, they work everywhere.

---

## Part 3: Context Files (AGENTS.md / CLAUDE.md / GEMINI.md)

### The Open Standard: AGENTS.md

[AGENTS.md](https://agents.md/) is an open format for guiding coding agents, now stewarded by the Linux Foundation's Agentic AI Foundation. It's adopted by 40,000+ open-source projects.

### File Discovery (Codex)

```
Discovery order (first match wins):
1. ./AGENTS.md (current directory)
2. Parent directories up to repo root
3. Sub-folders the agent is working in
4. ~/.factory/AGENTS.md (personal override)

Merge: Files concatenate root → leaf, closer files override.
```

### Recommended Sections

```markdown
# AGENTS.md

## Build & Test
Exact commands for compiling and testing.

## Architecture Overview
Short description of major modules.

## Knowledge System
This project uses Episteme for persistent knowledge:
- Query: `episteme query --subject <topic>`
- Store: `episteme assert <subject> <predicate> <object>`
- Lenses: consensus, recency, authority

When you learn something important, store it in Episteme.

## Conventions
Naming, folder layout, code style.
```

### Platform-Specific Files

| Platform | Primary File | Alternative |
|----------|-------------|-------------|
| Claude Code | `CLAUDE.md` | Also reads `AGENTS.md` |
| Gemini CLI | `GEMINI.md` | Also reads `AGENT.md` |
| OpenAI Codex | `AGENTS.md` | - |
| Cursor | `.cursor/rules/` | - |

**Best Practice:** Use `AGENTS.md` as the canonical file, reference it from platform-specific files:

```markdown
# CLAUDE.md

See [AGENTS.md](./AGENTS.md) for project conventions.

## Claude-Specific
Additional Claude Code settings here.
```

---

## Part 4: CLI Tool Integration

### The episteme-cli Approach

Instead of MCP, build a standalone CLI that skills can invoke:

```rust
// crates/episteme-cli/src/main.rs
use clap::{Parser, Subcommand};

#[derive(Parser)]
#[command(name = "episteme")]
#[command(about = "Episteme knowledge graph CLI")]
struct Cli {
    #[command(subcommand)]
    command: Commands,
}

#[derive(Subcommand)]
enum Commands {
    /// Query assertions about a subject
    Query {
        #[arg(short, long)]
        subject: String,
        #[arg(short, long, default_value = "recency")]
        lens: String,
        #[arg(short, long)]
        predicate: Option<String>,
    },
    /// Create a new assertion
    Assert {
        subject: String,
        predicate: String,
        object: String,
        #[arg(short, long)]
        source: Option<String>,
        #[arg(short, long, default_value = "1.0")]
        confidence: f64,
    },
    /// List conflicts for a subject
    Conflicts {
        #[arg(short, long)]
        subject: String,
    },
    /// Trace provenance chain
    Trace {
        #[arg(long)]
        assertion_id: String,
    },
}
```

### CLI Usage in Skills

```yaml
---
name: remember
description: Store a learning in the knowledge graph
allowed-tools: Bash(episteme *)
---

Store important learnings about this codebase.

## Usage

```bash
episteme assert "$0" "$1" "$2" --source "claude-session"
```

Where:
- $0 = subject (e.g., "AuthSystem")
- $1 = predicate (e.g., "uses")
- $2 = object (e.g., "JWT with 24h expiration")
```

### Output Format

Design CLI output for AI consumption:

```bash
$ episteme query --subject AuthSystem --lens recency

{
  "assertions": [
    {
      "id": "blake3:abc123...",
      "subject": "AuthSystem",
      "predicate": "uses",
      "object": "JWT",
      "confidence": 0.95,
      "source": "code-review-2024-01",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ],
  "lens": "recency",
  "conflicts": []
}
```

---

## Part 5: A2A Protocol (Agent-to-Agent)

### What is A2A?

[A2A](https://a2a-protocol.org/) is Google's open protocol for agent-to-agent communication, now under Linux Foundation governance. It's **complementary** to MCP:

- **MCP**: Agent → Tool communication
- **A2A**: Agent → Agent communication

### When to Use A2A

Use A2A when you want:
- Multiple AI agents collaborating on a task
- Episteme acting as a "memory agent" that other agents consult
- Cross-vendor agent ecosystems (Claude ↔ Gemini ↔ GPT agents)

### A2A Architecture

```
┌──────────────────┐     A2A      ┌──────────────────┐
│  Claude Agent    │◄────────────►│  Episteme Agent  │
│  (Coding tasks)  │              │  (Knowledge)     │
└──────────────────┘              └──────────────────┘
         │                                 │
         │ A2A                             │
         ▼                                 ▼
┌──────────────────┐              ┌──────────────────┐
│  Gemini Agent    │              │  StemeDB         │
│  (Review tasks)  │              │                  │
└──────────────────┘              └──────────────────┘
```

### Agent Card (Discovery)

Agents advertise capabilities via JSON "Agent Cards":

```json
{
  "name": "episteme-memory",
  "description": "Knowledge graph memory for AI agents",
  "version": "0.1.0",
  "capabilities": [
    "store_assertion",
    "query_knowledge",
    "resolve_conflicts"
  ],
  "endpoint": "https://episteme.local/a2a",
  "auth": {
    "type": "bearer"
  }
}
```

### Task Lifecycle

A2A uses task-oriented communication:

1. **Client agent** discovers Episteme via Agent Card
2. **Sends task**: "Remember that AuthSystem uses JWT"
3. **Episteme agent** processes, returns task status
4. **Long-running tasks** use SSE streaming for updates

### A2A vs MCP

| Aspect | MCP | A2A |
|--------|-----|-----|
| Communication | Tool invocation | Task delegation |
| Statefulness | Stateful sessions | Task-based state |
| Discovery | Client config | Agent Cards |
| Use case | AI → External tools | AI → AI collaboration |
| Opacity | Tools exposed | Internal state hidden |

---

## Part 6: Recommended Implementation Strategy

### Phase 1: CLI + Skills (Start Here)

1. **Build `episteme-cli`** as standalone Rust binary
2. **Create skills** that wrap CLI commands
3. **Add to AGENTS.md** with usage instructions

```bash
# Install
cargo install --path crates/episteme-cli

# Skills location
mkdir -p ~/.claude/skills/episteme-query
mkdir -p ~/.claude/skills/episteme-remember
```

### Phase 2: Context Integration

1. **Create AGENTS.md** with Episteme documentation
2. **Symlink or reference** from CLAUDE.md, GEMINI.md
3. **Version control** the context files

### Phase 3: A2A Agent (Optional)

1. **Implement Agent Card** endpoint
2. **Add A2A task handlers** for knowledge operations
3. **Deploy as service** for multi-agent scenarios

### Phase 4: MCP Server (If Needed)

Only if you need:
- Dynamic tool discovery (tools that change at runtime)
- Resource subscriptions (real-time updates)
- Deep IDE integration beyond skills

---

## Part 7: Episteme Skills Library

### Core Skills

#### `/episteme-query` - Query Knowledge

```yaml
---
name: episteme-query
description: Query the knowledge graph. Use before making changes to understand existing knowledge.
allowed-tools: Bash(episteme *)
---

Query Episteme for existing knowledge about a subject.

## Usage

```bash
episteme query --subject "$ARGUMENTS" --lens recency
```

## Lenses

- `recency` - Most recent assertions win
- `consensus` - Community agreement
- `authority` - Trusted sources weighted higher

## Example

```bash
episteme query --subject "PaymentService" --lens authority
```
```

#### `/episteme-remember` - Store Knowledge

```yaml
---
name: episteme-remember
description: Store a learning in the knowledge graph. Use after discovering something important.
disable-model-invocation: false
allowed-tools: Bash(episteme *)
---

Store important learnings in Episteme.

## Usage

```bash
episteme assert "$0" "$1" "$2" --source "claude-session" --confidence 0.9
```

## Arguments

- $0: Subject (what the assertion is about)
- $1: Predicate (the relationship)
- $2: Object (the value or target)

## Examples

```bash
# Architecture decision
episteme assert "UserService" "database" "PostgreSQL" --source "arch-review"

# Pattern discovery
episteme assert "ErrorHandling" "pattern" "Result<T, AppError>" --source "code-analysis"
```
```

#### `/episteme-conflicts` - Find Conflicts

```yaml
---
name: episteme-conflicts
description: Find conflicting assertions about a subject. Use when information seems contradictory.
allowed-tools: Bash(episteme *)
---

Find conflicting knowledge that needs resolution.

## Usage

```bash
episteme conflicts --subject "$ARGUMENTS"
```

## Output

Returns pairs of conflicting assertions with:
- Both assertion details
- Confidence levels
- Sources
- Suggested resolution strategy
```

---

## Part 8: Cross-Platform Configuration

### Universal Setup

```
project/
├── AGENTS.md              # Open standard, works everywhere
├── CLAUDE.md              # References AGENTS.md + Claude extras
├── .gemini/
│   └── GEMINI.md          # References AGENTS.md + Gemini extras
├── .claude/
│   └── skills/
│       ├── episteme-query/
│       │   └── SKILL.md
│       └── episteme-remember/
│           └── SKILL.md
└── .codex/
    └── skills/            # Symlink to .claude/skills/
```

### AGENTS.md Template

```markdown
# AGENTS.md

## Overview
[Project description]

## Knowledge System

This project uses **Episteme** for persistent AI memory.

### Querying Knowledge
Before making significant changes, query existing knowledge:
```bash
episteme query --subject <topic> --lens recency
```

### Storing Learnings
After discovering important patterns or decisions:
```bash
episteme assert <subject> <predicate> <object>
```

### Resolving Conflicts
When encountering contradictory information:
```bash
episteme conflicts --subject <topic>
```

## Build & Test
[Your build commands]

## Architecture
[Architecture overview]
```

---

## References

### Agent Skills
- [Agent Skills Specification](https://agentskills.io)
- [Claude Code Skills](https://code.claude.com/docs/en/skills)
- [Codex Skills](https://developers.openai.com/codex/skills/)

### Context Files
- [AGENTS.md Specification](https://agents.md/)
- [AGENTS.md on GitHub](https://github.com/openai/codex/blob/main/docs/agents_md.md)
- [Claude Code Memory](https://code.claude.com/docs/en/memory)

### A2A Protocol
- [A2A Protocol Specification](https://a2a-protocol.org/latest/)
- [A2A GitHub](https://github.com/a2aproject/A2A)
- [Linux Foundation Announcement](https://www.linuxfoundation.org/press/linux-foundation-launches-the-agent2agent-protocol-project)

### CLI Integration
- [Using Gemini CLI as Claude Subagent](https://aicodingtools.blog/en/claude-code/gemini-cli-as-subagent-of-claude-code)
- [Claude Code + Gemini CLI Integration](https://gist.github.com/AndrewAltimit/fc5ba068b73e7002cbe4e9721cebb0f5)

### MCP (Reference)
- [MCP Specification](https://modelcontextprotocol.io/specification/2025-11-25)
- [Rust MCP SDK](https://github.com/modelcontextprotocol/rust-sdk)