Practical overview
When it fits
Use VoiceMem when building a voice agent that needs persistent context across interactions, particularly when the agent should retrieve relevant memory while a user is still speaking.
Who it is for
- Developers integrating persistent memory into voice agents.
- Teams that need both factual and emotion-related conversational context.
- Python practitioners building systems with offline or streaming audio workflows.
Documented uses
- Store facts extracted from audio or entered directly as text.
- Retrieve relevant stored context in response to a question.
- Start retrieval during an audio turn rather than waiting for the full utterance.
- Keep factual and emotion-related memories available as separate result tracks.
Requirements & limits
VoiceMem is self-hosted Python software. The repository identifies an Apache-2.0 license and documents Python 3.10 or later.
- The base package bundles speech recognition, speaker identification, scene and emotion processing, and local embedding components.
- The setup instructions include downloading a default model environment separately from installing the package.
- The examples configure an OpenAI API key; the optional voicemem[slm] extra adds the fine-tuned Qwen reply model.
- The repository describes components, including the underlying memory engine, as replaceable.
Check current requirements in the official documentation. Source-based guidance does not mean OpenViST has run or independently tested this project.
Install VoiceMem and download its model environment
Prepare the Python package and default model files for a VoiceMem integration.
Before you start
- Python 3.10 or later
- A working Python package installation environment
Steps
Clone the VoiceMem repository and change into its directory.
Install the memory system with pip install voicemem.
Install or upgrade huggingface_hub.
Download zhifeixie/VoiceMem_Default_Models_Env into a local models directory.
Expected outcome
The VoiceMem package is installed and the documented default model environment is downloaded locally.
Guide limitations
- These steps cover setup only; they do not configure or run an agent.
- The optional voicemem[slm] extra is for the fine-tuned Qwen reply model and is not included in the base installation.
Ingest and retrieve a factual memory
Use the documented Python interface to store a factual statement and search for it.
Before you start
- Python 3.10 or later
- VoiceMem installed and its default model environment downloaded
- An OpenAI API key configured for the example
Steps
Create a VoiceMem instance in normal mode with the API key and a top_k value.
Call warmup() to load local models before the first request.
Ingest an audio file or a factual text statement.
Call search() with a question about the stored information and inspect the returned memory results.
Expected outcome
The example returns search results from VoiceMem's factual and emotion-related memory tracks; factual text can also be stored in leftbrain_only mode.
Guide limitations
- The repository notes that ingestion performs fact extraction, tagging and graph construction, while search uses vector retrieval.
- The guide describes the package calls shown in the repository and does not establish compatibility with a particular agent framework.
Sources & review
Source record details
- Source availability
- Active
- Sources checked
- 10 October 2026
- Original website title
- xzf-thu/VoiceMem · Official homepage title · retained in its source language