How nevamind-ai/memu works
Project type and purpose
• MemU is an open-source “memory framework” specialized for AI companions. It provides:
• SDKs (Python & JavaScript/TypeScript) for client integration
• A self-hostable server (FastAPI) exposing REST endpoints
• A pluggable memory engine that organizes, retrieves, and evolves conversation memories
• Multiple LLM client adapters (OpenAI, Azure, OpenRouter, Deepseek, etc.)
File structure to infer architecture
• Top-level: Docker/Docker-Compose files, CI workflows, Makefile, README, licenses
• memu/ directory:
• config/ → YAML/prompt configs for activities, events, profiles
• llm/ → adapter implementations for various LLM providers
• memory/ → core memory engine (agents, actions, embeddings, file manager)
• sdk/ → language-specific client libraries (python & javascript)
• server/ → FastAPI-based HTTP server (routers, services, CLI entrypoint)
• utils/ → logging helper
• example/ demonstrates client usage and a test server
• docs/ contains API reference
README insights
• Confirms layering: client → API → memory engine → LLM backends
• Mentions “memory as file system,” “knowledge graph,” “self-reflection,” “adaptive forgetting” → memory engine responsibilities
• Highlights cloud (hosted) vs. self-hosting (local) modes
Main components & interactions
A. Client Layer
• Your application + SDK (Python/JS)
• Calls MemU REST API (HTTPS)
B. API Layer (Server)
• FastAPI router (memory endpoints, task endpoints)
• Middleware (auth via API_KEY, logging)
• Service layer (MemoryService, TaskService)
C. Core Memory Engine
• MemoryAgent & RecallAgent coordinate actions
• Actions pipeline (add_activity_memory, cluster_memories, link_related_memories, update_memory_with_suggestions, run_theory_of_mind, generate_suggestions)
• Embedding module & FileManager (folder/file store for documents)
• Config loader (prompts, thresholds from YAML/TXT)
D. LLM & Vector Backends
• LLMClient adapters (openai_client, azure_openai_client, openrouter_client, deepseek_client, custom_client)
• Embedding store (in-memory or external vector DB if configured)
E. Infrastructure & Orchestration
• Docker container(s) for memu-server
• docker-compose for full stack (server + optional vector DB)
• CLI entrypoint for self-hosted setup
Architectural patterns & principles
• Layered architecture: clear separation of Client, API, Services, Engine, Backends
• Plugin/Adapter pattern for LLM providers and memory actions
• Command/Action pipeline in memory engine for extensibility
• Configuration-driven prompts and behaviors (YAML/TXT)
• File-system–based “database” abstraction with pluggable persistence
Elements
• Blue: external systems (OpenAI, Azure, vector DB)
• Green: core MemU modules (memory engine, services)
• Yellow: SDK boundaries
• Gray: configuration & file storage