Skip to main content

Memory Storage Tutorial

Learn how to use Soul Kernel’s memory storage system to persist and query memories.

Prerequisites

  • Rust 1.79+ installed
  • Basic understanding of async Rust
  • Soul Kernel workspace set up

Overview

In this tutorial, you’ll learn how to:
  1. Initialize the storage system
  2. Store memory events
  3. Query memories using vector similarity
  4. Filter and retrieve specific memories
  5. Handle synchronization scenarios

Setting Up

First, add the storage crate to your Cargo.toml:

Basic Memory Storage

Let’s start with a simple example that stores and retrieves memories:

Working with Embeddings

In a real application, you’ll generate embeddings using an LLM. Here’s a more realistic example:
Find memories similar to a query:

Advanced Filtering

Filter memories by type, author, or time range:

Memory Context Building

Build context from related memories:

Synchronization Support

Implement basic sync functionality:

Performance Optimization

Tips for optimal performance:

Error Handling

Properly handle storage errors:

Complete Example

Here’s a complete example that demonstrates all concepts:

Next Steps

Troubleshooting

Common Issues

  1. Database locked errors: Ensure you’re not opening multiple connections to the same SQLite file
  2. Performance issues: Check embedding dimensions and consider using batch operations
  3. Memory growth: Implement retention policies and use compact() regularly

Performance Tips

  • Keep embeddings under 1024 dimensions
  • Use batch inserts for bulk operations
  • Index frequently queried fields
  • Run compact() during off-peak hours

Change Log

  • 2025-06-13: Initial tutorial created with storage implementation examples