OpenClaw Turso Memory Plugin

Enhanced memory system for OpenClaw using Turso Embedded Database JavaScript bindings.

Overview

This plugin enhances OpenClaw's memory capabilities by adding a structured database layer alongside the existing Markdown-based memory system. It provides efficient storage and retrieval of different memory types with proper categorization and search capabilities.

Features

• Hot Memory: Immediate context and current session data
• Short-term Memory: Recent conversations (hours to days)
• Long-term Memory: Persistent knowledge and facts
• Memory Summaries: Aggregated information
• Full-text Search: Search across all memory types

---

📥 Installation

Step 1: Clone the Repository

cd ~/.openclaw/workspace
git clone https://git.actionbehind.com/ActionBehind/ai-memory-db.git
cd ai-memory-db

Step 2: Install Dependencies

npm install

This installs @tursodatabase/database (Turso JavaScript bindings).

Step 3: Verify Installation

node test-plugin.js

You should see output like:

🧪 Testing Turso Memory Plugin
🚀 Initializing...
✅ Initialized
💾 Storing hot memory...
✅ Hot memory stored
...
🏆 SUCCESS: Turso Memory Plugin is fully functional!

---

🔌 Integration with OpenClaw

Option A: Direct Usage in OpenClaw

Copy the plugin to your OpenClaw extensions folder:

mkdir -p ~/.openclaw/extensions/turso-memory
cp turso-memory-plugin.js ~/.openclaw/extensions/turso-memory/
cp package.json ~/.openclaw/extensions/turso-memory/

Then use it in your OpenClaw agent code:

import TursoMemoryPlugin from '~/.openclaw/extensions/turso-memory/turso-memory-plugin.js';

const memoryPlugin = new TursoMemoryPlugin({
  dbName: 'openclaw_memory.db',
  enabled: true
});

await memoryPlugin.initialize();

// Use in your agent...

Option B: Create an OpenClaw Tool

Create a tool file at ~/.openclaw/tools/turso-memory.js:

import TursoMemoryPlugin from '../extensions/turso-memory/turso-memory-plugin.js';

let plugin = null;

export async function initTursoMemory(config = {}) {
  plugin = new TursoMemoryPlugin({
    dbName: config.dbName || 'openclaw_memory.db',
    enabled: config.enabled !== false
  });
  await plugin.initialize();
  return plugin;
}

export async function storeMemory(type, data) {
  if (!plugin) throw new Error('Turso memory not initialized');
  return await plugin.storeMemory(type, data);
}

export async function queryMemories(type, filters) {
  if (!plugin) throw new Error('Turso memory not initialized');
  return await plugin.queryMemories(type, filters);
}

export async function searchMemories(term, options) {
  if (!plugin) throw new Error('Turso memory not initialized');
  return await plugin.searchMemories(term, options);
}

export async function closeMemory() {
  if (plugin) {
    await plugin.close();
    plugin = null;
  }
}

export function getMemoryStatus() {
  return plugin ? plugin.getStatus() : { enabled: false, initialized: false };
}

Option C: Use as Memory Hook

Create a hook at ~/.openclaw/hooks/turso-memory-hook.js:

import TursoMemoryPlugin from '../extensions/turso-memory/turso-memory-plugin.js';

class TursoMemoryHook {
  constructor(config) {
    this.plugin = new TursoMemoryPlugin({
      dbName: config.dbName || 'openclaw_memory.db',
      enabled: config.enabled !== false
    });
  }

  async onInit() {
    await this.plugin.initialize();
    console.log('Turso Memory: Initialized');
  }

  async onMemoryWrite(content, metadata = {}) {
    // Automatically store important memories
    if (metadata.importance > 0.7) {
      await this.plugin.storeMemory('long_term', {
        memory_type: metadata.type || 'fact',
        category: metadata.category || 'general',
        title: metadata.title || content.substring(0, 100),
        content: content,
        importance_score: metadata.importance,
        tags: metadata.tags || []
      });
    }
  }

  async onMemorySearch(query) {
    return await this.plugin.searchMemories(query, { limit: 10 });
  }

  async onShutdown() {
    await this.plugin.close();
  }
}

export default TursoMemoryHook;

---

🧪 Testing

Basic Test

Run the included test:

node test-plugin.js

Custom Test Script

Create your own test:

import TursoMemoryPlugin from './turso-memory-plugin.js';

async function myTest() {
  const plugin = new TursoMemoryPlugin({
    dbName: 'my_test.db',
    enabled: true
  });

  try {
    await plugin.initialize();
    console.log('✅ Plugin initialized');

    // Store a memory
    await plugin.storeMemory('long_term', {
      memory_type: 'fact',
      category: 'test',
      title: 'Test Memory',
      content: 'This is a test of the Turso memory plugin',
      importance_score: 0.8,
      tags: ['test', 'demo']
    });
    console.log('✅ Memory stored');

    // Query it back
    const memories = await plugin.queryMemories('long_term', { limit: 5 });
    console.log(`✅ Retrieved ${memories.length} memories`);

    // Search
    const results = await plugin.searchMemories('test', { limit: 5 });
    console.log(`✅ Found ${results.length} search results`);

  } catch (error) {
    console.error('❌ Test failed:', error.message);
  } finally {
    await plugin.close();
    console.log('✅ Plugin closed');
  }
}

myTest();

Run it:

node my-test.js

Verify Database File

After running tests, check the database file was created:

ls -la *.db
# Should see: openclaw_memory.db or your custom db name

---

📖 Usage Examples

Storing Different Memory Types

// Hot memory (immediate context)
await plugin.storeMemory('hot', {
  session_id: 'session-123',
  message_type: 'user_input',
  content: 'User asked about weather in London',
  priority: 8,
  tags: ['weather', 'query']
});

// Short-term memory (recent sessions)
await plugin.storeMemory('short_term', {
  session_id: 'session-123',
  category: 'conversation',
  title: 'Weather Query Session',
  summary: 'User asked about London weather',
  content: 'Full conversation details...',
  relevance_score: 0.7,
  tags: ['weather', 'london']
});

// Long-term memory (persistent facts)
await plugin.storeMemory('long_term', {
  memory_type: 'preference',
  category: 'personal',
  title: 'User Location Preference',
  content: 'User frequently asks about London weather, may live there',
  importance_score: 0.6,
  tags: ['preference', 'location', 'london']
});

// Summary memory
await plugin.storeMemory('summary', {
  summary_type: 'session',
  title: 'Session 123 Summary',
  content: 'User primarily interested in weather updates for London',
  tags: ['summary', 'weather', 'session-123']
});

Querying with Filters

// Get all hot memories for a session
const hotMemories = await plugin.queryMemories('hot', {
  session_id: 'session-123',
  priority_min: 5,
  limit: 10
});

// Get important long-term memories
const facts = await plugin.queryMemories('long_term', {
  category: 'personal',
  importance_min: 0.7,
  limit: 20
});

// Get all short-term memories
const recent = await plugin.queryMemories('short_term', { limit: 50 });

Searching

// Search across all memory types
const results = await plugin.searchMemories('london', { limit: 10 });

// Results include table_name so you know which type
results.forEach(r => {
  console.log(`[${r.table_name}] ${r.title || r.content.substring(0, 50)}`);
});

---

🔧 Troubleshooting

"Cannot find module '@tursodatabase/database'"

npm install

"Permission denied"

chmod +x test-plugin.js

Database locked error

Make sure to close the plugin properly:

await plugin.close();

Or delete the lock file:

rm *.db-wal *.db-shm

Import errors

Ensure your package.json has "type": "module" or use .mjs extension.

---

🗑️ Uninstallation

Step 1: Stop Using the Plugin

If using in OpenClaw, remove or disable the tool/hook:

rm ~/.openclaw/tools/turso-memory.js
# or
rm ~/.openclaw/hooks/turso-memory-hook.js

Step 2: Remove Plugin Files

rm -rf ~/.openclaw/extensions/turso-memory

Step 3: Remove Database Files (Optional)

# Remove the database file
rm ~/.openclaw/workspace/*.db
rm ~/.openclaw/workspace/*.db-wal
rm ~/.openclaw/workspace/*.db-shm

Step 4: Remove Repository (Optional)

cd ~/.openclaw/workspace
rm -rf ai-memory-db

Step 5: Uninstall Dependency (Optional)

If you installed @tursodatabase/database globally or in your main project:

npm uninstall @tursodatabase/database

---

📁 Files

File	Description
turso-memory-plugin.js	Main plugin implementation
test-plugin.js	Test suite
package.json	Dependencies
README.md	This documentation
LICENSE	MIT License

---

🔗 API Reference

Constructor Options

Option	Type	Default	Description
dbName	string	'openclaw_memory_turso.db'	Database file name
enabled	boolean	true	Enable/disable plugin

Methods

initialize()

Connects to the database and creates schema. Must be called before other operations.

storeMemory(type, data)

Stores a memory entry.

Parameters:

• type: 'hot', 'short_term', 'long_term', or 'summary'
• data: Memory data object

queryMemories(type, filters)

Queries memories with optional filters.

Parameters:

• type: Memory type to query
• filters: Optional filters (session_id, category, limit, etc.)

searchMemories(term, options)

Searches across all memory types.

Parameters:

• term: Search term
• options: Search options including limit

getStatus()

Returns plugin status information.

close()

Closes database connection.

---

📦 Dependencies

• @tursodatabase/database: Turso embedded database JavaScript bindings

---

📄 License

MIT

---

🔗 Repository

https://git.actionbehind.com/ActionBehind/ai-memory-db