ekkOS_docs
Integration

Custom Agent Integration

Add ekkOS memory to your own AI agents and applications.

Integration Options

There are two ways to integrate ekkOS with custom agents:

MCP Protocol

For agents that support the Model Context Protocol

REST API

Direct HTTP calls for any application

REST API Integration

Search Memory

Find relevant patterns and context:

curl -X POST https://mcp.ekkos.dev/api/v1/memory/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "authentication patterns",
    "limit": 5
  }'

Save Pattern

Store a new pattern:

curl -X POST https://mcp.ekkos.dev/api/v1/patterns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Rate limiting with Redis",
    "problem": "Need to limit API requests",
    "solution": "Use Redis sorted sets with sliding window",
    "tags": ["api", "redis", "performance"]
  }'

Write Working Memory

Capture conversation messages:

curl -X POST https://mcp.ekkos.dev/api/v1/working \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "user",
    "content": "Help me implement user authentication",
    "session_id": "session_123",
    "source": "my-custom-agent"
  }'

TypeScript SDK

Installation

npm install @ekkos/sdk

Usage Example

import { EkkosClient } from '@ekkos/sdk';

const ekkos = new EkkosClient({
  apiKey: process.env.EKKOS_API_KEY
});

// Search memory
const results = await ekkos.search({
  query: 'authentication best practices',
  limit: 5
});

// Inject context into your AI prompt
const context = results.map(r => r.content).join('\n');
const prompt = `
Given this context from memory:
${context}

User question: ${userQuestion}
`;

// Save a new pattern
await ekkos.forgeInsight({
  title: 'JWT refresh token rotation',
  problem: 'Tokens expire during long sessions',
  solution: 'Implement automatic token refresh with rotation',
  tags: ['auth', 'security', 'jwt']
});

// Track outcome
await ekkos.recordOutcome({
  applicationId: results.retrieval_id,
  success: true
});

Recommended Integration Pattern

  1. 1
    Before AI call — Search memory for relevant context
  2. 2
    Inject context — Add retrieved patterns to system prompt
  3. 3
    Make AI call — Let the AI use the enriched context
  4. 4
    Capture conversation — Write messages to working memory
  5. 5
    Track outcome — Report if the patterns helped

Next Steps