# Ai Memory Engine (`ruv/ai-memory-engine`) Actor

Give your AI persistent memory. Store conversations, search semantically, build knowledge graphs, and watch your AI get smarter with every interaction.

- **URL**: https://apify.com/ruv/ai-memory-engine.md
- **Developed by:** [Reuven Cohen](https://apify.com/ruv) (community)
- **Categories:** AI, Agents, MCP servers
- **Stats:** 5 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.01 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## AI Memory Engine - Smart Database That Learns & Remembers

**Give your AI persistent memory.** Store conversations, search semantically, build knowledge graphs, and watch your AI get smarter with every interaction. The ultimate memory solution for AI agents, chatbots, and intelligent automation.

🧠 **Self-Learning** · 🔍 **Semantic Search** · 🕸️ **Knowledge Graphs** · ⚡ **Sub-millisecond** · 🔗 **LLM Agnostic** · 🔌 **One-Click Integrations**

[![Apify Actor](https://img.shields.io/badge/Apify-Actor-blue)](https://apify.com/ruv/ai-memory-engine)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

---

### Why AI Memory Engine?

**The Problem:** Every AI application needs memory, but building it is complex. You need embeddings, vector databases, search algorithms, and persistence - all expensive and time-consuming to set up.

**The Solution:** AI Memory Engine gives you production-ready AI memory in one click. Built on [RuvLLM](https://github.com/ruvnet/ruvector) with native SIMD acceleration, HNSW indexing, and SONA self-learning - no external dependencies required.

#### What Makes This Different

| Feature | AI Memory Engine | Traditional Solutions |
|---------|------------------|----------------------|
| **Setup Time** | 1 minute | Hours to days |
| **Cost** | Pay per use ($0.001/operation) | $50-500/month subscriptions |
| **Memory Persistence** | Built-in cross-session | Requires external DB |
| **Self-Learning** | SONA neural architecture | Manual tuning |
| **Apify Integration** | One-click from any actor | Custom code required |
| **Export Options** | 6 vector DB formats | Limited |

#### Key Capabilities

**27 Actions** including:
- **Core**: store, search, get, list, update, delete, clear
- **Advanced Search**: batch_search, hybrid_search, find_duplicates, deduplicate
- **AI Features**: chat, recommend, analyze, build_knowledge, learn
- **Integration**: integrate_actor, integrate_synthetic, integrate_scraper, template
- **Utilities**: natural language commands, cluster, export_vectordb, feedback

**One-Click Actor Integration** with 10+ popular scrapers:
- Google Maps, Instagram, TikTok, YouTube, Twitter, Amazon, TripAdvisor, LinkedIn, and more
- Automatically memorize any scraper results with semantic search

**6 Pre-Built Templates** for instant deployment:
- Lead Intelligence, Customer Support, Research Assistant
- Competitor Intelligence, Content Library, Product Catalog

---

### What Does This Do?

| Without AI Memory | With AI Memory Engine |
|-------------------|----------------------|
| AI forgets everything between sessions | **Remembers all conversations** |
| Same questions, same generic answers | **Personalized, context-aware responses** |
| No learning from interactions | **Gets smarter with every use** |
| Expensive vector DB subscriptions | **Built-in, no external dependencies** |
| Complex RAG setup | **One-click semantic search** |
| Manual integration with scrapers | **One-click memory from any actor** |
| Learn new tools for each vector DB | **Export to Pinecone, Weaviate, ChromaDB** |

---

### Use Cases

#### 💬 Chatbots with Memory
```json
{
  "action": "chat",
  "chatMessage": "What products did I look at last week?",
  "sessionId": "customer-123"
}
````

Your chatbot remembers every conversation and provides personalized responses.

#### 📚 RAG (Retrieval Augmented Generation)

```json
{
  "action": "store",
  "memories": [
    {"text": "Product X requires 220V power supply", "metadata": {"type": "specs"}},
    {"text": "Product X comes with 2-year warranty", "metadata": {"type": "warranty"}}
  ]
}
```

Then search with natural language:

```json
{
  "action": "search",
  "query": "What's the warranty on Product X?"
}
```

#### 🛍️ Recommendation Engine

```json
{
  "action": "recommend",
  "query": "customer interested in home automation"
}
```

Get personalized recommendations based on learned patterns.

#### 🧠 Knowledge Graph

```json
{
  "action": "build_knowledge",
  "memories": [
    "John works at TechCorp as a Senior Engineer",
    "TechCorp is located in San Francisco",
    "John manages the AI team"
  ]
}
```

Automatically extract entities and relationships.

***

### Quick Start (1 Minute)

#### Try the Demo

```json
{
  "action": "demo"
}
```

This will:

1. Store sample memories (customer preferences, product info, support tickets)
2. Run semantic searches
3. Generate recommendations
4. Show you what's possible

**Output:**

```json
{
  "demo": true,
  "memoriesStored": 8,
  "sampleSearch": {
    "query": "What does the customer prefer?",
    "results": [
      {
        "text": "Customer prefers eco-friendly products and fast shipping",
        "similarity": 0.89
      }
    ]
  }
}
```

***

### Core Features

#### 1. Store Memories

Add any text to your AI's memory:

```json
{
  "action": "store",
  "memories": [
    {"text": "Customer John prefers phone support over email", "metadata": {"customerId": "C001", "type": "preference"}},
    {"text": "Issue resolved by offering free shipping upgrade", "metadata": {"type": "resolution", "success": true}},
    {"text": "User mentioned they have a small apartment", "metadata": {"type": "context", "userId": "U001"}}
  ]
}
```

**Output:**

```json
{
  "stored": 3,
  "totalMemories": 3,
  "memories": [
    {"id": "mem_1702489200_0", "text": "Customer John prefers phone support..."}
  ]
}
```

#### 2. Semantic Search

Find relevant memories using natural language:

```json
{
  "action": "search",
  "query": "How do we usually resolve customer complaints?",
  "topK": 5,
  "similarityThreshold": 0.6
}
```

**Output:**

```json
{
  "query": "How do we usually resolve customer complaints?",
  "resultsFound": 2,
  "results": [
    {
      "text": "Issue resolved by offering free shipping upgrade",
      "similarity": 0.82,
      "metadata": {"type": "resolution", "success": true}
    },
    {
      "text": "Customer complaint resolved by offering 20% discount",
      "similarity": 0.78
    }
  ]
}
```

#### 3. Chat with Memory

Have conversations where AI remembers everything:

```json
{
  "action": "chat",
  "chatMessage": "What do we know about customer John?",
  "chatHistory": [
    {"role": "user", "content": "I need to call John today"},
    {"role": "assistant", "content": "I can help you prepare for the call."}
  ],
  "sessionId": "support-session-1",
  "provider": "gemini",
  "apiKey": "your-gemini-key"
}
```

**Output:**

```json
{
  "message": "What do we know about customer John?",
  "response": "Based on our records, John prefers phone support over email. He mentioned having a small apartment, which might be relevant for product recommendations.",
  "contextUsed": 2,
  "relevantMemories": [
    {"text": "Customer John prefers phone support over email", "similarity": 0.91}
  ]
}
```

#### 4. Build Knowledge Graphs

Automatically extract entities and relationships:

```json
{
  "action": "build_knowledge",
  "memories": [
    "Apple Inc was founded by Steve Jobs in California",
    "Steve Jobs was CEO of Apple until 2011",
    "Tim Cook became CEO of Apple in 2011",
    "Apple headquarters is in Cupertino, California"
  ]
}
```

**Output:**

```json
{
  "nodesCreated": 6,
  "edgesCreated": 8,
  "topEntities": [
    {"label": "Apple", "mentions": 4},
    {"label": "Steve Jobs", "mentions": 2},
    {"label": "California", "mentions": 2}
  ]
}
```

#### 5. Analyze Patterns

Get insights from your stored memories:

```json
{
  "action": "analyze"
}
```

**Output:**

```json
{
  "totalMemories": 150,
  "insights": [
    "You have 150 memories stored",
    "42 searches performed with 128 results returned",
    "Most common metadata keys: type, customerId, category",
    "Top keyword: 'shipping' (23 occurrences)"
  ],
  "topKeywords": [
    {"word": "shipping", "count": 23},
    {"word": "customer", "count": 18}
  ]
}
```

***

### Integrations

#### 🔗 Integrate with Synthetic Data Generator

Generate test data and automatically memorize it:

```json
{
  "action": "integrate_synthetic",
  "integrationConfig": {
    "syntheticDataActor": "ruv/ai-synthetic-data-generator",
    "dataType": "ecommerce",
    "count": 1000,
    "memorizeFields": ["title", "description", "category"]
  }
}
```

This calls the [AI Synthetic Data Generator](https://apify.com/ruv/ai-synthetic-data-generator) and stores the results as searchable memories.

**Supported data types:**

- `ecommerce` - Product catalogs
- `jobs` - Job listings
- `real_estate` - Property listings
- `social` - Social media posts
- `stock_trading` - Market data
- `medical` - Healthcare records
- `company` - Corporate data

#### 🌐 Integrate with Web Scraper

Scrape websites and build a searchable knowledge base:

```json
{
  "action": "integrate_scraper",
  "scraperConfig": {
    "urls": [
      "https://docs.example.com/getting-started",
      "https://docs.example.com/api-reference"
    ],
    "selector": "article",
    "maxPages": 50
  }
}
```

Perfect for:

- Documentation search
- Competitor analysis
- Content aggregation
- Research databases

#### 🔌 One-Click Actor Integration

**Instantly memorize results from any Apify actor:**

```json
{
  "action": "integrate_actor",
  "actorId": "apify/google-maps-scraper",
  "actorConfig": {
    "runId": "latest",
    "memorizeFields": ["title", "address", "totalScore", "categoryName"],
    "limit": 500
  }
}
```

**Supported actors (one-click ready):**
| Actor | What Gets Memorized |
|-------|---------------------|
| `apify/google-maps-scraper` | Business name, address, rating, reviews |
| `apify/instagram-scraper` | Captions, hashtags, engagement |
| `apify/tiktok-scraper` | Video text, author, play count |
| `apify/youtube-scraper` | Titles, descriptions, view counts |
| `apify/twitter-scraper` | Tweets, authors, engagement |
| `apify/amazon-scraper` | Products, prices, ratings |
| `apify/tripadvisor-scraper` | Venues, ratings, locations |
| `apify/linkedin-scraper` | Profiles, headlines, companies |
| `apify/web-scraper` | Any website content |
| `apify/website-content-crawler` | Full page content |

**Example: Build a local business database:**

```json
{
  "action": "integrate_actor",
  "actorId": "apify/google-maps-scraper",
  "actorConfig": {
    "actorInput": {
      "searchStringsArray": ["restaurants near San Francisco"],
      "maxCrawledPlaces": 100
    }
  }
}
```

Then search naturally:

```json
{
  "action": "search",
  "query": "highly rated Italian restaurants with parking"
}
```

***

### Pre-Built Templates

**Get started instantly with industry templates:**

```json
{
  "action": "template",
  "template": "customer-support"
}
```

**Available templates:**
| Template | Use Case |
|----------|----------|
| `lead-intelligence` | Sales lead tracking, CRM enrichment |
| `customer-support` | FAQ knowledge base, ticket resolution |
| `research-assistant` | Academic & market research |
| `competitor-intelligence` | Market tracking, competitive analysis |
| `content-library` | Content ideas, editorial planning |
| `product-catalog` | E-commerce knowledge base |

Each template includes:

- Sample memories for immediate use
- Suggested search queries
- Optimized metadata structure

***

### Natural Language Commands

**Talk to your memory database in plain English:**

```json
{
  "action": "natural",
  "command": "remember that John prefers email communication"
}
```

**Supported commands:**
| Command | Action |
|---------|--------|
| `remember [text]` | Store a new memory |
| `forget about [topic]` | Remove related memories |
| `what do you know about [topic]` | Semantic search |
| `find [query]` | Search memories |
| `how many memories` | Get stats |
| `list memories` | Show all memories |
| `clear everything` | Reset database |
| `analyze` | Get insights |
| `find duplicates` | Detect duplicates |
| `export` | Download data |
| `help` | Show commands |

**Examples:**

```json
{"action": "natural", "command": "what do you know about customer preferences"}
{"action": "natural", "command": "forget about old pricing"}
{"action": "natural", "command": "analyze"}
```

***

### Memory Clustering

**Automatically group memories by similarity:**

```json
{
  "action": "cluster",
  "numClusters": 5
}
```

**Output:**

```json
{
  "totalMemories": 150,
  "numClusters": 5,
  "clusters": [
    {
      "id": 0,
      "label": "customer, preferences, shipping",
      "keywords": ["customer", "preferences", "shipping", "support", "email"],
      "size": 34,
      "sampleMemories": [...]
    },
    {
      "id": 1,
      "label": "product, pricing, features",
      "keywords": ["product", "pricing", "features", "specifications"],
      "size": 28,
      "sampleMemories": [...]
    }
  ]
}
```

**Use cases:**

- Discover topics in large memory collections
- Identify content gaps
- Organize knowledge automatically
- Find related memories without a query

***

### Vector DB Export

**Export to any vector database:**

```json
{
  "action": "export_vectordb",
  "vectorDbFormat": "pinecone"
}
```

**Supported formats:**
| Format | Database | Output Structure |
|--------|----------|------------------|
| `pinecone` | Pinecone | `{id, values, metadata}` |
| `weaviate` | Weaviate | `{id, vector, properties}` |
| `chromadb` | ChromaDB | `{ids, embeddings, documents, metadatas}` |
| `qdrant` | Qdrant | `{id, vector, payload}` |
| `langchain` | LangChain | `{pageContent, metadata, embeddings}` |
| `openai` | OpenAI-compatible | `{input, embedding}` |

**Example: Migrate to Pinecone**

```json
{
  "action": "export_vectordb",
  "vectorDbFormat": "pinecone"
}
```

**Output:**

```json
{
  "format": "pinecone",
  "vectors": [
    {
      "id": "mem_123",
      "values": [0.123, 0.456, ...],
      "metadata": {"text": "Customer prefers...", "type": "preference"}
    }
  ],
  "namespace": "default"
}
```

***

### Session Persistence

Keep memories across multiple runs:

```json
{
  "action": "store",
  "memories": [{"text": "New customer preference discovered"}],
  "sessionId": "my-project-memory"
}
```

Later, in another run:

```json
{
  "action": "search",
  "query": "customer preferences",
  "sessionId": "my-project-memory"
}
```

All memories from the session are automatically restored.

***

### Export & Import

#### Export Memories

```json
{
  "action": "export",
  "exportFormat": "json"
}
```

Formats available:

- `json` - Full export with metadata and embeddings
- `csv` - Spreadsheet compatible
- `embeddings` - Raw vectors for ML pipelines

#### Import Memories

```json
{
  "action": "import",
  "importData": {
    "memories": [
      {"text": "Imported memory 1", "metadata": {}, "embedding": [...]}
    ]
  }
}
```

***

### Configuration Options

#### Embedding Models

| Model | Dimensions | Speed | Quality | API Required |
|-------|------------|-------|---------|--------------|
| `local-384` | 384 | ⚡⚡⚡ Fastest | Good | No |
| `local-768` | 768 | ⚡⚡ Fast | Better | No |
| `gemini` | 768 | ⚡ Normal | Best | Yes (free tier) |
| `openai` | 1536 | ⚡ Normal | Best | Yes |

#### Distance Metrics

| Metric | Best For |
|--------|----------|
| `cosine` | Text similarity (default) |
| `euclidean` | Numerical data |
| `dot_product` | Normalized vectors |
| `manhattan` | Outlier-resistant |

#### AI Providers

| Provider | Models Available |
|----------|-----------------|
| `local` | No LLM (search only) |
| `gemini` | Gemini 2.0 Flash, 1.5 Pro |
| `openrouter` | GPT-4o, Claude 3.5, Llama 3.3, 100+ models |

***

### API Integration

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient("your-api-token")

## Store memories
client.actor("ruv/ai-memory-engine").call(run_input={
    "action": "store",
    "memories": [{"text": "Customer feedback: Great product!", "metadata": {"type": "feedback"}}],
    "sessionId": "my-app"
})

## Search memories
result = client.actor("ruv/ai-memory-engine").call(run_input={
    "action": "search",
    "query": "What feedback have we received?",
    "sessionId": "my-app"
})

print(result["defaultDatasetId"])
```

#### JavaScript

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'your-api-token' });

// Chat with memory
const run = await client.actor('ruv/ai-memory-engine').call({
    action: 'chat',
    chatMessage: 'What do customers like about our product?',
    sessionId: 'support-bot',
    provider: 'gemini',
    apiKey: process.env.GEMINI_API_KEY
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items[0].result.response);
```

#### cURL

```bash
curl -X POST "https://api.apify.com/v2/acts/ruv~ai-memory-engine/runs?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "search",
    "query": "shipping preferences",
    "sessionId": "customer-data"
  }'
```

***

### Pricing

This actor uses Pay-Per-Event pricing:

| Event | Price | Description |
|-------|-------|-------------|
| `apify-actor-start` | $0.00005 | Actor startup (per GB memory) |
| `apify-default-dataset-item` | $0.00001 | Result in dataset |
| `memory-store` | $0.001 | Store memory with RuvLLM embeddings |
| `memory-search` | $0.001 | Semantic search with HNSW |
| `chat-interaction` | $0.003 | AI chat with memory context |
| `knowledge-graph-build` | $0.005 | Build knowledge graph |
| `recommendation` | $0.002 | Get recommendations (per batch) |
| `pattern-analysis` | $0.003 | Analyze patterns with SONA |
| `memory-export` | $0.002 | Export database |
| `memory-import` | $0.002 | Import data |
| `synthetic-integration` | $0.005 | Integrate with synthetic data |
| `scraper-integration` | $0.01 | Integrate with web scraper |
| `learning-cycle` | $0.005 | Force SONA learning cycle |

**Example costs:**

- Store 1,000 memories: $1.00
- 1,000 searches: $1.00
- 100 chat interactions: $0.30
- Build knowledge graph: $0.005

***

### Performance

| Operation | Latency | Throughput |
|-----------|---------|------------|
| Store memory | ~2ms | 500/sec |
| Search (1000 memories) | ~5ms | 200/sec |
| Search (10000 memories) | ~20ms | 50/sec |
| Chat with context | ~100ms | 10/sec |

***

### FAQ

**Q: How long are memories stored?**
A: Memories persist as long as you use a `sessionId`. Without a session, memories exist only for the run.

**Q: Can I use this with my own LLM?**
A: Yes! Use OpenRouter to access 100+ models including GPT-4, Claude, Llama, Mistral, and more.

**Q: Is there a limit on memories?**
A: No hard limit. Performance is optimized for up to 100,000 memories per session.

**Q: Can I use this for production?**
A: Absolutely! The actor is designed for production workloads with session persistence and high throughput.

**Q: Does it work without an API key?**
A: Yes! Local embeddings and search work without any API. LLM features require Gemini or OpenRouter key.

***

### MCP Integration (Model Context Protocol)

AI Memory Engine is fully compatible with [Apify's MCP server](https://mcp.apify.com), allowing AI agents (Claude, GPT-4, etc.) to directly interact with your memory database.

#### Quick Setup

**Add to Claude Code (one command):**

```bash
claude mcp add ai-memory --transport sse --url "https://mcp.apify.com/sse?token=YOUR_APIFY_TOKEN&actors=ruv/ai-memory-engine"
```

> Replace `YOUR_APIFY_TOKEN` with your [Apify API token](https://console.apify.com/settings/integrations).

**For Claude Desktop / VS Code / Cursor (config file):**

```json
{
  "mcpServers": {
    "ai-memory": {
      "transport": "sse",
      "url": "https://mcp.apify.com/sse?token=YOUR_APIFY_TOKEN&actors=ruv/ai-memory-engine"
    }
  }
}
```

**Alternative: Local MCP Server**

```json
{
  "mcpServers": {
    "ai-memory": {
      "command": "npx",
      "args": ["-y", "@apify/actors-mcp-server", "--actors", "ruv/ai-memory-engine"],
      "env": {
        "APIFY_TOKEN": "your-apify-token"
      }
    }
  }
}
```

#### What AI Agents Can Do

Once connected, AI agents can autonomously:

- **Store memories** from conversations
- **Search semantically** through stored knowledge
- **Build knowledge graphs** from unstructured data
- **Get recommendations** based on patterns
- **Manage sessions** across conversations

#### Example AI Agent Workflow

```
User: "Remember that I prefer dark mode and fast responses"
Agent: [Calls AI Memory Engine store action]
       [Stores: {"text": "User prefers dark mode and fast responses", "metadata": {"type": "preference"}}]
       "Got it! I'll remember your preference for dark mode and fast responses."

User: "What are my preferences?"
Agent: [Calls AI Memory Engine search action with query "user preferences"]
       [Returns stored memory with similarity 0.94]
       "Based on our conversation, you prefer dark mode and fast responses."
```

#### MCP Resources

- [Apify MCP Documentation](https://docs.apify.com/platform/integrations/mcp)
- [MCP Server Configuration](https://mcp.apify.com/)
- [Model Context Protocol Spec](https://modelcontextprotocol.io/)

***

### Related Actors

- [AI Synthetic Data Generator](https://apify.com/ruv/ai-synthetic-data-generator) - Generate mock data for testing
- [Self-Learning AI Memory](https://apify.com/ruv/self-learning-ai-memory) - PostgreSQL-based vector storage

***

### Links

- [GitHub Repository](https://github.com/ruvnet/ruvector)
- [Report Issues](https://github.com/ruvnet/ruvector/issues)

***

**Built with [RuVector](https://github.com/ruvnet/ruvector)** - High-performance vector database for AI applications.

# Actor input Schema

## `action` (type: `string`):

Select the operation to perform on your memory database

## `sessionId` (type: `string`):

Unique identifier to persist memories across multiple Actor runs. Use the same Session ID to continue where you left off. Leave empty for one-time runs.

## `namespace` (type: `string`):

Organize memories into separate collections (like folders). Different namespaces are completely isolated.

## `memories` (type: `array`):

Text content to store in memory. Each item becomes a searchable memory with vector embeddings.

## `query` (type: `string`):

What are you looking for? The engine uses semantic understanding to find relevant memories even with different wording.

## `queries` (type: `array`):

Multiple search queries to run in parallel. Each query returns its own set of results.

## `memoryId` (type: `string`):

Unique identifier of a specific memory for get/delete/update operations

## `memoryIds` (type: `array`):

Array of memory IDs for batch delete operation

## `updates` (type: `object`):

Fields to update on a memory. You can update text, metadata, or both.

## `metadataFilter` (type: `object`):

Filter memories by metadata fields. Only memories matching ALL specified fields are affected.

## `topK` (type: `integer`):

Maximum number of similar memories to return

## `similarityThreshold` (type: `number`):

Minimum similarity score required. Higher values return more relevant but fewer results.

## `distanceMetric` (type: `string`):

Algorithm used to measure similarity between memory vectors

## `keywordWeight` (type: `number`):

Weight given to exact keyword matching in hybrid search. Set to 0 for pure semantic search.

## `semanticWeight` (type: `number`):

Weight given to semantic similarity in hybrid search. Set to 1 for pure semantic search.

## `limit` (type: `integer`):

Maximum number of memories to return when listing

## `offset` (type: `integer`):

Number of memories to skip for pagination (e.g., offset=100 starts at the 101st result)

## `sortBy` (type: `string`):

Field to sort list results by

## `sortOrder` (type: `string`):

Sort direction for list results

## `duplicateThreshold` (type: `number`):

How similar memories must be to be considered duplicates. 0.95 = very similar, 1.0 = exact match.

## `chatMessage` (type: `string`):

Your message to the AI assistant. The assistant will use stored memories to provide context-aware responses.

## `chatHistory` (type: `array`):

Previous messages in the conversation for context. Each message has a 'role' (user/assistant) and 'content'.

## `provider` (type: `string`):

Which AI service to use for chat and advanced features

## `apiKey` (type: `string`):

Your API key for the selected provider. Get free Gemini key at ai.google.dev

## `model` (type: `string`):

Which language model to use for chat and generation

## `sonaEnabled` (type: `boolean`):

SONA (Self-Optimizing Neural Architecture) continuously improves search quality based on usage patterns

## `learningEnabled` (type: `boolean`):

Learn from search queries and feedback to improve future results

## `forceBackgroundLearning` (type: `boolean`):

Run a SONA background learning cycle after this operation completes

## `ewcLambda` (type: `number`):

How strongly to prevent forgetting old patterns when learning new ones. Higher = more conservative learning.

## `patternThreshold` (type: `number`):

Minimum confidence required to learn a new pattern. Higher = only learn strong patterns.

## `knowledgeGraphEnabled` (type: `boolean`):

Automatically extract entities and relationships from stored memories to build a knowledge graph

## `feedbackRating` (type: `integer`):

Rate the quality of a search result or recommendation to help SONA learn (5 = perfect, 1 = irrelevant)

## `feedbackCorrection` (type: `string`):

If a memory is incorrect, provide the correct text here. SONA will learn from this correction.

## `exportFormat` (type: `string`):

File format for exporting your memory database

## `vectorDbFormat` (type: `string`):

Export in a format compatible with popular vector databases

## `importData` (type: `object`):

JSON data to import into memory. Should contain an array of memories with text and optional metadata.

## `actorId` (type: `string`):

Select a popular actor or enter any Apify actor ID (owner/actor-name)

## `customActorId` (type: `string`):

Enter the full actor ID (e.g., username/actor-name) when using 'Custom Actor' option

## `actorCategory` (type: `string`):

Filter actors by category to find the right one faster

## `actorRunMode` (type: `string`):

Where to get the actor's data from

## `actorRunId` (type: `string`):

Run ID to fetch data from (when using 'Specific Run' mode)

## `actorDatasetId` (type: `string`):

Dataset ID to fetch data from (when using 'Dataset Only' mode)

## `actorInput` (type: `object`):

Input configuration for starting a fresh actor run

## `actorConfig` (type: `object`):

Configure how actor data is processed and stored in memory

## `actorTimeout` (type: `integer`):

Maximum wait time for fresh actor runs (in seconds). Longer timeouts allow more data but cost more.

## `actorMemoryLimit` (type: `integer`):

Memory allocation for fresh actor runs (higher = faster but costs more)

## `integrationConfig` (type: `object`):

Settings for generating and memorizing synthetic test data

## `scraperConfig` (type: `object`):

Configure web pages to scrape and memorize

## `tradingSymbols` (type: `array`):

Crypto/stock symbols to analyze and generate trading signals for

## `tradingStrategy` (type: `string`):

Neural network strategy to use for signal generation

## `memorizeSignals` (type: `boolean`):

Save generated trading signals as searchable memories for later analysis

## `memorizeMarketData` (type: `boolean`):

Also store market data (price, volume, indicators) alongside signals

## `signalConfidenceThreshold` (type: `integer`):

Minimum confidence level required to store a signal (0-100). Higher = only store high-conviction signals.

## `searchTradingHistory` (type: `boolean`):

Instead of generating new signals, search existing trading memories

## `tradingHistoryQuery` (type: `string`):

Search query for finding relevant trading signals and market data in memory

## `tradingActorConfig` (type: `object`):

Advanced configuration for the Neural Trader System actor

## `template` (type: `string`):

Load a pre-built memory template optimized for specific use cases

## `command` (type: `string`):

Tell the AI what you want in plain English. Examples: 'remember that John prefers email', 'what do you know about customers', 'find similar products'

## `numClusters` (type: `integer`):

How many groups to organize your memories into based on similarity

## `embeddingModel` (type: `string`):

Model used to convert text into vector embeddings for semantic search

## `seed` (type: `string`):

Set a seed for reproducible results across runs

## Actor input object example

```json
{
  "action": "demo",
  "sessionId": "my-chatbot-session",
  "namespace": "customer-support",
  "memories": [
    {
      "text": "The customer prefers fast shipping over lower prices",
      "metadata": {
        "type": "preference",
        "customer_id": "123"
      }
    },
    {
      "text": "Product X works best with Product Y for home automation",
      "metadata": {
        "type": "knowledge",
        "category": "products"
      }
    },
    {
      "text": "User asked about return policy on December 10th",
      "metadata": {
        "type": "conversation",
        "date": "2024-12-10"
      }
    }
  ],
  "query": "customer shipping preferences",
  "queries": [
    "What does the customer prefer?",
    "Product recommendations",
    "Support history"
  ],
  "memoryId": "mem_abc123",
  "memoryIds": [
    "mem_123",
    "mem_456"
  ],
  "updates": {
    "text": "Updated memory text",
    "metadata": {
      "updated": true,
      "version": 2
    }
  },
  "metadataFilter": {
    "category": "products",
    "active": true
  },
  "topK": 10,
  "similarityThreshold": 0.8,
  "distanceMetric": "cosine",
  "keywordWeight": 0.3,
  "semanticWeight": 0.7,
  "limit": 100,
  "offset": 0,
  "sortBy": "createdAt",
  "sortOrder": "desc",
  "duplicateThreshold": 0.95,
  "chatMessage": "What products would you recommend based on my preferences?",
  "chatHistory": [
    {
      "role": "user",
      "content": "What products do you recommend?"
    },
    {
      "role": "assistant",
      "content": "Based on your preferences, I recommend Product X."
    }
  ],
  "provider": "gemini",
  "model": "gemini-2.0-flash-exp",
  "sonaEnabled": true,
  "learningEnabled": true,
  "forceBackgroundLearning": false,
  "ewcLambda": 2000,
  "patternThreshold": 0.85,
  "knowledgeGraphEnabled": false,
  "feedbackRating": 5,
  "exportFormat": "json",
  "vectorDbFormat": "pinecone",
  "importData": {
    "memories": [
      {
        "text": "Sample memory to import",
        "metadata": {
          "source": "import"
        }
      }
    ]
  },
  "actorId": "apify/google-maps-scraper",
  "customActorId": "apify/cheerio-scraper",
  "actorCategory": "all",
  "actorRunMode": "latest",
  "actorRunId": "HG7ML7M8z78YcAPEB",
  "actorDatasetId": "3MmuMLbFVS3Iss36T",
  "actorInput": {
    "searchStrings": [
      "coffee shops in NYC"
    ],
    "maxResults": 50
  },
  "actorConfig": {
    "memorizeFields": [
      "title",
      "description",
      "address",
      "rating"
    ],
    "limit": 100,
    "skipDuplicates": true,
    "enrichWithMetadata": true
  },
  "actorTimeout": 120,
  "actorMemoryLimit": 1024,
  "integrationConfig": {
    "syntheticDataActor": "ruv/ai-synthetic-data-generator",
    "dataType": "ecommerce",
    "count": 100,
    "memorizeFields": [
      "title",
      "description",
      "category"
    ]
  },
  "scraperConfig": {
    "urls": [
      "https://example.com/docs"
    ],
    "selector": "article",
    "maxPages": 10
  },
  "tradingSymbols": [
    "BTC",
    "ETH",
    "AAPL",
    "GOOGL"
  ],
  "tradingStrategy": "ensemble",
  "memorizeSignals": true,
  "memorizeMarketData": false,
  "signalConfidenceThreshold": 70,
  "searchTradingHistory": false,
  "tradingHistoryQuery": "recent SELL recommendations",
  "tradingActorConfig": {
    "actorId": "ruv/neural-trader-system",
    "action": "analyze",
    "riskProfile": "moderate",
    "memory": 2048,
    "timeout": 300
  },
  "command": "remember that the client prefers meetings on Tuesday",
  "numClusters": 5,
  "embeddingModel": "ruvllm-768",
  "seed": "42"
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "sessionId": "my-project",
    "memories": [
        {
            "text": "The customer prefers fast shipping over lower prices",
            "metadata": {
                "type": "preference",
                "customer_id": "123"
            }
        },
        {
            "text": "Product X works best with Product Y for home automation",
            "metadata": {
                "type": "knowledge",
                "category": "products"
            }
        },
        {
            "text": "User asked about return policy on December 10th",
            "metadata": {
                "type": "conversation",
                "date": "2024-12-10"
            }
        }
    ],
    "query": "What does the customer prefer?",
    "queries": [
        "What does the customer prefer?",
        "Product recommendations",
        "Support history"
    ],
    "memoryIds": [
        "mem_123",
        "mem_456"
    ],
    "updates": {
        "text": "Updated memory text",
        "metadata": {
            "updated": true,
            "version": 2
        }
    },
    "metadataFilter": {
        "type": "preference"
    },
    "chatMessage": "What products would you recommend based on my preferences?",
    "chatHistory": [
        {
            "role": "user",
            "content": "What products do you recommend?"
        },
        {
            "role": "assistant",
            "content": "Based on your preferences, I recommend Product X."
        }
    ],
    "importData": {
        "memories": [
            {
                "text": "Sample memory to import",
                "metadata": {
                    "source": "import"
                }
            }
        ]
    },
    "actorInput": {
        "searchStrings": [
            "coffee shops in NYC"
        ],
        "maxResults": 50
    },
    "actorConfig": {
        "memorizeFields": [
            "title",
            "description",
            "address",
            "rating"
        ],
        "limit": 100,
        "skipDuplicates": true,
        "enrichWithMetadata": true
    },
    "integrationConfig": {
        "syntheticDataActor": "ruv/ai-synthetic-data-generator",
        "dataType": "ecommerce",
        "count": 100,
        "memorizeFields": [
            "title",
            "description",
            "category"
        ]
    },
    "scraperConfig": {
        "urls": [
            "https://example.com/docs"
        ],
        "selector": "article",
        "maxPages": 10
    },
    "tradingSymbols": [
        "BTC",
        "ETH",
        "SOL"
    ],
    "tradingHistoryQuery": "high confidence BUY signals for BTC",
    "tradingActorConfig": {
        "actorId": "ruv/neural-trader-system",
        "action": "analyze",
        "riskProfile": "moderate",
        "memory": 2048,
        "timeout": 300
    },
    "command": "what do you know about customers"
};

// Run the Actor and wait for it to finish
const run = await client.actor("ruv/ai-memory-engine").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "sessionId": "my-project",
    "memories": [
        {
            "text": "The customer prefers fast shipping over lower prices",
            "metadata": {
                "type": "preference",
                "customer_id": "123",
            },
        },
        {
            "text": "Product X works best with Product Y for home automation",
            "metadata": {
                "type": "knowledge",
                "category": "products",
            },
        },
        {
            "text": "User asked about return policy on December 10th",
            "metadata": {
                "type": "conversation",
                "date": "2024-12-10",
            },
        },
    ],
    "query": "What does the customer prefer?",
    "queries": [
        "What does the customer prefer?",
        "Product recommendations",
        "Support history",
    ],
    "memoryIds": [
        "mem_123",
        "mem_456",
    ],
    "updates": {
        "text": "Updated memory text",
        "metadata": {
            "updated": True,
            "version": 2,
        },
    },
    "metadataFilter": { "type": "preference" },
    "chatMessage": "What products would you recommend based on my preferences?",
    "chatHistory": [
        {
            "role": "user",
            "content": "What products do you recommend?",
        },
        {
            "role": "assistant",
            "content": "Based on your preferences, I recommend Product X.",
        },
    ],
    "importData": { "memories": [{
                "text": "Sample memory to import",
                "metadata": { "source": "import" },
            }] },
    "actorInput": {
        "searchStrings": ["coffee shops in NYC"],
        "maxResults": 50,
    },
    "actorConfig": {
        "memorizeFields": [
            "title",
            "description",
            "address",
            "rating",
        ],
        "limit": 100,
        "skipDuplicates": True,
        "enrichWithMetadata": True,
    },
    "integrationConfig": {
        "syntheticDataActor": "ruv/ai-synthetic-data-generator",
        "dataType": "ecommerce",
        "count": 100,
        "memorizeFields": [
            "title",
            "description",
            "category",
        ],
    },
    "scraperConfig": {
        "urls": ["https://example.com/docs"],
        "selector": "article",
        "maxPages": 10,
    },
    "tradingSymbols": [
        "BTC",
        "ETH",
        "SOL",
    ],
    "tradingHistoryQuery": "high confidence BUY signals for BTC",
    "tradingActorConfig": {
        "actorId": "ruv/neural-trader-system",
        "action": "analyze",
        "riskProfile": "moderate",
        "memory": 2048,
        "timeout": 300,
    },
    "command": "what do you know about customers",
}

# Run the Actor and wait for it to finish
run = client.actor("ruv/ai-memory-engine").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "sessionId": "my-project",
  "memories": [
    {
      "text": "The customer prefers fast shipping over lower prices",
      "metadata": {
        "type": "preference",
        "customer_id": "123"
      }
    },
    {
      "text": "Product X works best with Product Y for home automation",
      "metadata": {
        "type": "knowledge",
        "category": "products"
      }
    },
    {
      "text": "User asked about return policy on December 10th",
      "metadata": {
        "type": "conversation",
        "date": "2024-12-10"
      }
    }
  ],
  "query": "What does the customer prefer?",
  "queries": [
    "What does the customer prefer?",
    "Product recommendations",
    "Support history"
  ],
  "memoryIds": [
    "mem_123",
    "mem_456"
  ],
  "updates": {
    "text": "Updated memory text",
    "metadata": {
      "updated": true,
      "version": 2
    }
  },
  "metadataFilter": {
    "type": "preference"
  },
  "chatMessage": "What products would you recommend based on my preferences?",
  "chatHistory": [
    {
      "role": "user",
      "content": "What products do you recommend?"
    },
    {
      "role": "assistant",
      "content": "Based on your preferences, I recommend Product X."
    }
  ],
  "importData": {
    "memories": [
      {
        "text": "Sample memory to import",
        "metadata": {
          "source": "import"
        }
      }
    ]
  },
  "actorInput": {
    "searchStrings": [
      "coffee shops in NYC"
    ],
    "maxResults": 50
  },
  "actorConfig": {
    "memorizeFields": [
      "title",
      "description",
      "address",
      "rating"
    ],
    "limit": 100,
    "skipDuplicates": true,
    "enrichWithMetadata": true
  },
  "integrationConfig": {
    "syntheticDataActor": "ruv/ai-synthetic-data-generator",
    "dataType": "ecommerce",
    "count": 100,
    "memorizeFields": [
      "title",
      "description",
      "category"
    ]
  },
  "scraperConfig": {
    "urls": [
      "https://example.com/docs"
    ],
    "selector": "article",
    "maxPages": 10
  },
  "tradingSymbols": [
    "BTC",
    "ETH",
    "SOL"
  ],
  "tradingHistoryQuery": "high confidence BUY signals for BTC",
  "tradingActorConfig": {
    "actorId": "ruv/neural-trader-system",
    "action": "analyze",
    "riskProfile": "moderate",
    "memory": 2048,
    "timeout": 300
  },
  "command": "what do you know about customers"
}' |
apify call ruv/ai-memory-engine --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=ruv/ai-memory-engine",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Ai Memory Engine",
        "description": "Give your AI persistent memory. Store conversations, search semantically, build knowledge graphs, and watch your AI get smarter with every interaction.",
        "version": "1.0",
        "x-build-id": "G3BXtbIu47JCtaLU1"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/ruv~ai-memory-engine/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-ruv-ai-memory-engine",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/ruv~ai-memory-engine/runs": {
            "post": {
                "operationId": "runs-sync-ruv-ai-memory-engine",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/ruv~ai-memory-engine/run-sync": {
            "post": {
                "operationId": "run-sync-ruv-ai-memory-engine",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "action"
                ],
                "properties": {
                    "action": {
                        "title": "Action",
                        "enum": [
                            "demo",
                            "store",
                            "search",
                            "get",
                            "list",
                            "delete",
                            "update",
                            "clear",
                            "stats",
                            "batch_search",
                            "hybrid_search",
                            "find_duplicates",
                            "deduplicate",
                            "chat",
                            "build_knowledge",
                            "recommend",
                            "analyze",
                            "feedback",
                            "export",
                            "import",
                            "integrate_synthetic",
                            "integrate_scraper",
                            "integrate_actor",
                            "integrate_trading",
                            "template",
                            "natural",
                            "cluster",
                            "export_vectordb",
                            "learn"
                        ],
                        "type": "string",
                        "description": "Select the operation to perform on your memory database",
                        "default": "demo"
                    },
                    "sessionId": {
                        "title": "Session ID",
                        "type": "string",
                        "description": "Unique identifier to persist memories across multiple Actor runs. Use the same Session ID to continue where you left off. Leave empty for one-time runs."
                    },
                    "namespace": {
                        "title": "Memory Namespace",
                        "type": "string",
                        "description": "Organize memories into separate collections (like folders). Different namespaces are completely isolated.",
                        "default": "default"
                    },
                    "memories": {
                        "title": "Memories to Store",
                        "type": "array",
                        "description": "Text content to store in memory. Each item becomes a searchable memory with vector embeddings."
                    },
                    "query": {
                        "title": "Search Query",
                        "type": "string",
                        "description": "What are you looking for? The engine uses semantic understanding to find relevant memories even with different wording."
                    },
                    "queries": {
                        "title": "Batch Search Queries",
                        "type": "array",
                        "description": "Multiple search queries to run in parallel. Each query returns its own set of results."
                    },
                    "memoryId": {
                        "title": "Memory ID",
                        "type": "string",
                        "description": "Unique identifier of a specific memory for get/delete/update operations"
                    },
                    "memoryIds": {
                        "title": "Memory IDs (Batch)",
                        "type": "array",
                        "description": "Array of memory IDs for batch delete operation",
                        "items": {
                            "type": "string"
                        }
                    },
                    "updates": {
                        "title": "Memory Updates",
                        "type": "object",
                        "description": "Fields to update on a memory. You can update text, metadata, or both."
                    },
                    "metadataFilter": {
                        "title": "Metadata Filter",
                        "type": "object",
                        "description": "Filter memories by metadata fields. Only memories matching ALL specified fields are affected."
                    },
                    "topK": {
                        "title": "Number of Results",
                        "minimum": 1,
                        "maximum": 100,
                        "type": "integer",
                        "description": "Maximum number of similar memories to return",
                        "default": 10
                    },
                    "similarityThreshold": {
                        "title": "Similarity Threshold",
                        "minimum": 0,
                        "maximum": 1,
                        "type": "number",
                        "description": "Minimum similarity score required. Higher values return more relevant but fewer results.",
                        "default": 0.7
                    },
                    "distanceMetric": {
                        "title": "Distance Metric",
                        "enum": [
                            "cosine",
                            "euclidean",
                            "dot_product",
                            "manhattan"
                        ],
                        "type": "string",
                        "description": "Algorithm used to measure similarity between memory vectors",
                        "default": "cosine"
                    },
                    "keywordWeight": {
                        "title": "Keyword Weight (Hybrid Search)",
                        "minimum": 0,
                        "maximum": 1,
                        "type": "number",
                        "description": "Weight given to exact keyword matching in hybrid search. Set to 0 for pure semantic search.",
                        "default": 0.3
                    },
                    "semanticWeight": {
                        "title": "Semantic Weight (Hybrid Search)",
                        "minimum": 0,
                        "maximum": 1,
                        "type": "number",
                        "description": "Weight given to semantic similarity in hybrid search. Set to 1 for pure semantic search.",
                        "default": 0.7
                    },
                    "limit": {
                        "title": "Results per Page",
                        "minimum": 1,
                        "maximum": 1000,
                        "type": "integer",
                        "description": "Maximum number of memories to return when listing",
                        "default": 100
                    },
                    "offset": {
                        "title": "Skip Results",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Number of memories to skip for pagination (e.g., offset=100 starts at the 101st result)",
                        "default": 0
                    },
                    "sortBy": {
                        "title": "Sort By",
                        "enum": [
                            "createdAt",
                            "updatedAt",
                            "accessCount"
                        ],
                        "type": "string",
                        "description": "Field to sort list results by",
                        "default": "createdAt"
                    },
                    "sortOrder": {
                        "title": "Sort Order",
                        "enum": [
                            "asc",
                            "desc"
                        ],
                        "type": "string",
                        "description": "Sort direction for list results",
                        "default": "desc"
                    },
                    "duplicateThreshold": {
                        "title": "Duplicate Similarity Threshold",
                        "minimum": 0.8,
                        "maximum": 1,
                        "type": "number",
                        "description": "How similar memories must be to be considered duplicates. 0.95 = very similar, 1.0 = exact match.",
                        "default": 0.95
                    },
                    "chatMessage": {
                        "title": "Your Message",
                        "type": "string",
                        "description": "Your message to the AI assistant. The assistant will use stored memories to provide context-aware responses."
                    },
                    "chatHistory": {
                        "title": "Conversation History",
                        "type": "array",
                        "description": "Previous messages in the conversation for context. Each message has a 'role' (user/assistant) and 'content'."
                    },
                    "provider": {
                        "title": "AI Provider",
                        "enum": [
                            "gemini",
                            "openrouter",
                            "local"
                        ],
                        "type": "string",
                        "description": "Which AI service to use for chat and advanced features",
                        "default": "gemini"
                    },
                    "apiKey": {
                        "title": "AI Provider API Key",
                        "type": "string",
                        "description": "Your API key for the selected provider. Get free Gemini key at ai.google.dev"
                    },
                    "model": {
                        "title": "AI Model",
                        "enum": [
                            "gemini-2.0-flash-exp",
                            "gemini-2.0-flash-thinking-exp",
                            "gemini-1.5-pro",
                            "openai/gpt-4o",
                            "openai/gpt-4o-mini",
                            "anthropic/claude-3.5-sonnet",
                            "meta-llama/llama-3.3-70b-instruct"
                        ],
                        "type": "string",
                        "description": "Which language model to use for chat and generation",
                        "default": "gemini-2.0-flash-exp"
                    },
                    "sonaEnabled": {
                        "title": "Enable SONA Learning",
                        "type": "boolean",
                        "description": "SONA (Self-Optimizing Neural Architecture) continuously improves search quality based on usage patterns",
                        "default": true
                    },
                    "learningEnabled": {
                        "title": "Enable Interaction Learning",
                        "type": "boolean",
                        "description": "Learn from search queries and feedback to improve future results",
                        "default": true
                    },
                    "forceBackgroundLearning": {
                        "title": "Force Learning Cycle",
                        "type": "boolean",
                        "description": "Run a SONA background learning cycle after this operation completes",
                        "default": false
                    },
                    "ewcLambda": {
                        "title": "Anti-Forgetting Strength (EWC++)",
                        "minimum": 100,
                        "maximum": 15000,
                        "type": "number",
                        "description": "How strongly to prevent forgetting old patterns when learning new ones. Higher = more conservative learning.",
                        "default": 2000
                    },
                    "patternThreshold": {
                        "title": "Pattern Confidence Threshold",
                        "minimum": 0.5,
                        "maximum": 1,
                        "type": "number",
                        "description": "Minimum confidence required to learn a new pattern. Higher = only learn strong patterns.",
                        "default": 0.85
                    },
                    "knowledgeGraphEnabled": {
                        "title": "Build Knowledge Graph",
                        "type": "boolean",
                        "description": "Automatically extract entities and relationships from stored memories to build a knowledge graph",
                        "default": false
                    },
                    "feedbackRating": {
                        "title": "Result Rating",
                        "minimum": 1,
                        "maximum": 5,
                        "type": "integer",
                        "description": "Rate the quality of a search result or recommendation to help SONA learn (5 = perfect, 1 = irrelevant)",
                        "default": 5
                    },
                    "feedbackCorrection": {
                        "title": "Correction Text",
                        "type": "string",
                        "description": "If a memory is incorrect, provide the correct text here. SONA will learn from this correction."
                    },
                    "exportFormat": {
                        "title": "Export Format",
                        "enum": [
                            "json",
                            "csv",
                            "embeddings"
                        ],
                        "type": "string",
                        "description": "File format for exporting your memory database",
                        "default": "json"
                    },
                    "vectorDbFormat": {
                        "title": "Vector DB Export Format",
                        "enum": [
                            "pinecone",
                            "weaviate",
                            "chromadb",
                            "qdrant",
                            "langchain",
                            "openai"
                        ],
                        "type": "string",
                        "description": "Export in a format compatible with popular vector databases",
                        "default": "pinecone"
                    },
                    "importData": {
                        "title": "Import Data",
                        "type": "object",
                        "description": "JSON data to import into memory. Should contain an array of memories with text and optional metadata."
                    },
                    "actorId": {
                        "title": "Actor to Integrate",
                        "enum": [
                            "apify/google-maps-scraper",
                            "apify/yelp-scraper",
                            "apify/tripadvisor-scraper",
                            "apify/instagram-scraper",
                            "apify/twitter-scraper",
                            "apify/tiktok-scraper",
                            "apify/reddit-scraper",
                            "apify/facebook-scraper",
                            "apify/linkedin-scraper",
                            "apify/youtube-scraper",
                            "apify/amazon-scraper",
                            "apify/shopify-scraper",
                            "apify/ebay-scraper",
                            "apify/walmart-scraper",
                            "apify/booking-scraper",
                            "apify/airbnb-scraper",
                            "apify/expedia-scraper",
                            "apify/glassdoor-scraper",
                            "apify/indeed-scraper",
                            "apify/crunchbase-scraper",
                            "apify/google-search-scraper",
                            "apify/news-scraper",
                            "apify/rss-feed-scraper",
                            "apify/zillow-scraper",
                            "apify/realtor-scraper",
                            "ruv/ai-synthetic-data-generator",
                            "ruv/neural-trader-system",
                            "custom"
                        ],
                        "type": "string",
                        "description": "Select a popular actor or enter any Apify actor ID (owner/actor-name)",
                        "default": "apify/google-maps-scraper"
                    },
                    "customActorId": {
                        "title": "Custom Actor ID",
                        "type": "string",
                        "description": "Enter the full actor ID (e.g., username/actor-name) when using 'Custom Actor' option"
                    },
                    "actorCategory": {
                        "title": "Filter by Category",
                        "enum": [
                            "all",
                            "local",
                            "social",
                            "ecommerce",
                            "travel",
                            "professional",
                            "content",
                            "realestate",
                            "data"
                        ],
                        "type": "string",
                        "description": "Filter actors by category to find the right one faster",
                        "default": "all"
                    },
                    "actorRunMode": {
                        "title": "Data Source",
                        "enum": [
                            "latest",
                            "specific",
                            "fresh",
                            "dataset",
                            "discovery"
                        ],
                        "type": "string",
                        "description": "Where to get the actor's data from",
                        "default": "latest"
                    },
                    "actorRunId": {
                        "title": "Specific Run ID",
                        "type": "string",
                        "description": "Run ID to fetch data from (when using 'Specific Run' mode)"
                    },
                    "actorDatasetId": {
                        "title": "Dataset ID",
                        "type": "string",
                        "description": "Dataset ID to fetch data from (when using 'Dataset Only' mode)"
                    },
                    "actorInput": {
                        "title": "Actor Input (Fresh Run)",
                        "type": "object",
                        "description": "Input configuration for starting a fresh actor run"
                    },
                    "actorConfig": {
                        "title": "Memory Settings",
                        "type": "object",
                        "description": "Configure how actor data is processed and stored in memory"
                    },
                    "actorTimeout": {
                        "title": "Actor Timeout",
                        "minimum": 30,
                        "maximum": 600,
                        "type": "integer",
                        "description": "Maximum wait time for fresh actor runs (in seconds). Longer timeouts allow more data but cost more.",
                        "default": 120
                    },
                    "actorMemoryLimit": {
                        "title": "Actor Memory (MB)",
                        "minimum": 256,
                        "maximum": 8192,
                        "type": "integer",
                        "description": "Memory allocation for fresh actor runs (higher = faster but costs more)",
                        "default": 1024
                    },
                    "integrationConfig": {
                        "title": "Synthetic Data Configuration",
                        "type": "object",
                        "description": "Settings for generating and memorizing synthetic test data"
                    },
                    "scraperConfig": {
                        "title": "Web Scraper Configuration",
                        "type": "object",
                        "description": "Configure web pages to scrape and memorize"
                    },
                    "tradingSymbols": {
                        "title": "Trading Symbols",
                        "type": "array",
                        "description": "Crypto/stock symbols to analyze and generate trading signals for",
                        "items": {
                            "type": "string"
                        }
                    },
                    "tradingStrategy": {
                        "title": "Trading Strategy",
                        "enum": [
                            "ensemble",
                            "neural_momentum",
                            "lstm_prediction",
                            "transformer_attention",
                            "reinforcement"
                        ],
                        "type": "string",
                        "description": "Neural network strategy to use for signal generation",
                        "default": "ensemble"
                    },
                    "memorizeSignals": {
                        "title": "Store Trading Signals",
                        "type": "boolean",
                        "description": "Save generated trading signals as searchable memories for later analysis",
                        "default": true
                    },
                    "memorizeMarketData": {
                        "title": "Store Market Data",
                        "type": "boolean",
                        "description": "Also store market data (price, volume, indicators) alongside signals",
                        "default": false
                    },
                    "signalConfidenceThreshold": {
                        "title": "Signal Confidence Threshold",
                        "minimum": 0,
                        "maximum": 100,
                        "type": "integer",
                        "description": "Minimum confidence level required to store a signal (0-100). Higher = only store high-conviction signals.",
                        "default": 70
                    },
                    "searchTradingHistory": {
                        "title": "Search Trading History",
                        "type": "boolean",
                        "description": "Instead of generating new signals, search existing trading memories",
                        "default": false
                    },
                    "tradingHistoryQuery": {
                        "title": "Trading History Query",
                        "type": "string",
                        "description": "Search query for finding relevant trading signals and market data in memory"
                    },
                    "tradingActorConfig": {
                        "title": "Neural Trader Actor Settings",
                        "type": "object",
                        "description": "Advanced configuration for the Neural Trader System actor"
                    },
                    "template": {
                        "title": "Template",
                        "enum": [
                            "lead-intelligence",
                            "customer-support",
                            "research-assistant",
                            "competitor-intelligence",
                            "content-library",
                            "product-catalog"
                        ],
                        "type": "string",
                        "description": "Load a pre-built memory template optimized for specific use cases"
                    },
                    "command": {
                        "title": "Natural Language Command",
                        "type": "string",
                        "description": "Tell the AI what you want in plain English. Examples: 'remember that John prefers email', 'what do you know about customers', 'find similar products'"
                    },
                    "numClusters": {
                        "title": "Number of Clusters",
                        "minimum": 2,
                        "maximum": 20,
                        "type": "integer",
                        "description": "How many groups to organize your memories into based on similarity",
                        "default": 5
                    },
                    "embeddingModel": {
                        "title": "Embedding Model",
                        "enum": [
                            "ruvllm-768",
                            "ruvllm-384",
                            "gemini",
                            "openai"
                        ],
                        "type": "string",
                        "description": "Model used to convert text into vector embeddings for semantic search",
                        "default": "ruvllm-768"
                    },
                    "seed": {
                        "title": "Random Seed",
                        "type": "string",
                        "description": "Set a seed for reproducible results across runs"
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```