DOCSEARCHbyAlgolia
Submit Docs

SelfMemory Documentation

website·Indexed 31 days ago

https://docs.selfmemory.com

Long-term memory for AI Agents featuring zero-setup simplicity. SelfMemory provides a dual architecture for direct library usage or a FastAPI-based server with MongoDB integration. The documentation covers quick start guides, configuration management following Clean Code principles, CSRF protection implementation, and security best practices for production deployment.

Tokens
23.6K
Snippets
174
Records
231
Agent score
50%

What's inside SelfMemory

  1. Overview of SelfMemory Key Features

    SelfMemory provides a memory management system for LLMs with the following core capabilities:

    • Zero Setup: Immediate usability upon installation without requiring initial configuration.
    • Dual Architecture: Supports both direct library integration and a managed client via a REST API.
    • Advanced Search: Implements semantic similarity using vector embeddings for retrieval.
    • Flexible Storage: Supports both file-based storage and MongoDB backends.
    • NVIDIA NeMo Integration: Compatible with Mem0, Redis, or Zep as memory backends through the NeMo Agent Toolkit.
    • Production Readiness: Includes built-in support for authentication, API keys, and dashboard integration.

  2. Overview of SelfMemory MCP Server capabilities

    The SelfMemory MCP server is a Model Context Protocol (MCP) implementation that allows LLMs to manage memories. It features:

    • MCP Compliance: Full implementation of the MCP API specification.
    • Authentication: Secure access utilizing OAuth 2.1 and RFC 9728 Protected Resource Metadata.
    • Transport: Supports remote server access via Streamable HTTP Transport.
    • Memory Management: Provides standardized MCP tools to search for and add memories.

  3. Use SelfMemory in Claude Desktop

    In Claude Desktop, SelfMemory is integrated via tools. You can interact with your memories naturally through conversation. For example, asking about a topic triggers the search tool to retrieve relevant memories, and stating a preference or fact triggers the add tool to store new information.

    User: "What do I know about Python projects?" Claude: Uses the search tool to find relevant memories

    User: "Remember that I prefer using pytest for testing" Claude: Uses the add tool to store this preference

  4. Integrate NeMo Agent Toolkit memory with SelfMemory

    SelfMemory provides a NeMo adapter that wraps NVIDIA's async MemoryEditor interface into the standard MemoryBase API. This allows developers to switch between native SelfMemory and NeMo-backed memory systems via configuration changes without altering the core application logic.

  5. Choose between SelfMemory Direct Library or Client/Server mode

    SelfMemory can be integrated into applications using two distinct architectural modes:

    1. Direct Library Usage: Import and instantiate the SelfMemory class directly within a Python application for local or embedded memory management.
    2. Client/Server Mode: Deploy a standalone REST API server and interact with it using the SelfMemoryClient for distributed access.

    Regardless of the mode chosen, both support semantic search (via Ollama or OpenAI), vector storage (via Qdrant or ChromaDB), metadata tagging, and user isolation.

  6. Understand SelfMemory configuration principles

    SelfMemory implements a centralized configuration system based on Clean Code principles to ensure predictability and type safety. The system is designed around five core tenets:

    1. Single Source of Truth: All configuration logic is centralized in server/config.py.
    2. Environment-Driven: No values are hardcoded; all settings are managed via environment variables.
    3. Type Safety: Configuration is handled through typed classes.
    4. Early Validation: The system validates configurations during startup to prevent runtime failures.
    5. Explicit Failures: The system avoids silent fallbacks, opting for explicit errors when configuration is missing or invalid.

  7. Connect SelfMemory to AI applications via Model Context Protocol (MCP)

    SelfMemory implements the Model Context Protocol (MCP) specification. This allows the SelfMemory system to be connected as a server to MCP-compatible clients, including Claude Desktop and VS Code, enabling these AI applications to interact with your memory system.

  9. Connect to a SelfMemory server using SelfMemoryClient

    The SelfMemoryClient is used to establish a connection to a running SelfMemory server. It handles authentication and API key management, making it suitable for production deployments, multi-user applications, remote memory access, and dashboard integrations.

  10. Understand the SelfMemory Architecture and NemoMemoryAdapter

    SelfMemory uses a layered architecture where the application interacts with the NemoMemoryAdapter (which inherits from MemoryBase), which in turn communicates with the async NeMo MemoryEditor. The NeMo MemoryEditor serves as the interface to various memory backends including Mem0, Redis, and Zep.

    The NemoMemoryAdapter is responsible for three primary functions:

    1. Sync-to-async bridging: Since NeMo MemoryEditor is fully asynchronous, the adapter manages the execution of async operations using asyncio.run() or ThreadPoolExecutor to ensure compatibility with synchronous environments or existing event loops (such as FastAPI).
    2. Data model translation: It handles the conversion between SelfMemory's string-based tags and NeMo's list-based tags, maps metadata fields, and extracts content from conversation lists.
    3. User isolation: It ensures per-user memory isolation by passing the user_id to all NeMo operations.
    +---------------------+      +-------------------+      +------------------+
|   Your Application  | ---> | NemoMemoryAdapter | ---> | NeMo MemoryEditor|
|                     |      | (MemoryBase)      |      | (async)          |
+---------------------+      +-------------------+      +------------------+
                                      |                         |
                              sync-to-async bridge       +------+------+
                              (asyncio.to_thread /       |      |      |
                               ThreadPoolExecutor)     Mem0  Redis   Zep

  11. Compare SelfMemory and SelfMemoryClient classes

    The selfmemory SDK provides two primary classes depending on the deployment architecture:

    • SelfMemory: Used for direct library usage where no server is required.
    • SelfMemoryClient: Used as a REST API client to connect to a remote or local running server.

  12. Understand the SelfMemory authentication and request architecture

    The SelfMemory architecture uses an MCP (Model Context Protocol) client (such as VS Code or Claude) that authenticates via an OAuth2 flow involving a backend, Ory Hydra, and a dashboard. The sequence is as follows:

    1. The MCP Client requests /.well-known/oauth-protected-resource from the SelfMemory Backend.
    2. The Backend directs the client to discover Ory Hydra.
    3. The client initiates an OAuth flow, performing a login via the Dashboard (which uses Kratos).
    4. A token is issued to the client.
    5. The MCP Client sends requests to the Backend using the Bearer token.
    6. The Backend validates the token via Hydra introspection before granting access to memory operations.
    graph TD
    A[MCP Client VS Code/Claude] -->|1. Request /.well-known/oauth-protected-resource| B[SelfMemory Backend Port 8081]
    B -->|2. Client discovers Ory Hydra| C[Ory Hydra Port 4444/4445]
    C -->|3. OAuth flow login via dashboard| D[Dashboard Port 3000 - Kratos login]
    D -->|4. Token issued| A
    A -->|5. Token validated via Hydra introspection| B
    B --> E[Access granted to memory operations]