readme.md

The server-side of Memobase

Get started

Setup

config.yaml

Memobase uses a single config.yaml to initialize the server. It contains the configs of:

• LLM: llm_base_url, llm_api_key, best_llm_model,...
• Embedding: enable_event_embedding, embedding_api_key...
• Memory: max_pre_profile_token_size, max_profile_subtopics, additional_user_profiles...

By default, Memobase enables user profile and event memory with filter ability. That means running a Memobase server requires you to have below things:

• LLM API: You must fill the OpenAI API Key in llm_api_key of config.yaml.Or you can change llm_base_url to any OpenAI-SDK-Compatible service(via vllm, Ollama,...). Alternatively, you can set llm_api_key and llm_base_url using environment variables MEMOBASE_LLM_API_KEY and MEMOBASE_LLM_BASE_URL
• Embedding API: Memobase supports OpenAI-Compatible SDK, Jina Embedding and Ollama Embedding. Memobase uses embedding API to retrieve related user events. If you don't have a embedding API, you can set enable_event_embedding: false in config.yaml

We have some example config.yaml in examplel_config:

• profile_for_assistant, profile_for_education, profile_for_companion are three similar configs in term of structure, but for different user cases.
• event_tag is a feature to tracking temporal attributes of users. doc
• only_strict_profile: disable all other features, only collect the profiles you design.
• jina_embedding uses Jina exmbedding for event search.
• ollama_embedding uses Ollama exmbedding for event search.

environment variables

Check ./.env.example for necessary vars. You can configure the running port and access token in here. Also, anything in config.yaml can be override in env(doc), just starts with MEMOBASE_

Launch

1. Make sure you have docker-compose installed.

2. Prepare the configs:

   cd src/server
   cp .env.example .env
   cp ./api/config.yaml.example ./api/config.yaml

   1. .env contains the service configs, like running port, secret token...
   2. config.yaml contains the Memobase configs, like LLM model, profile slots. docs

3. Run docker-compose build && docker-compose up to start the services.

Check out the docs of how to use Memobase client or APIs.

Use Memobase core only

1. If you have existing postgres and reids, you can only launch the Memobase core

2. Find and download the docker image of Memobase:

   docker pull ghcr.io/memodb-io/memobase:latest

3. Setup your config.yaml and an env.list file, the env.list should look like this:

4. Run the service:

   docker run --env-file env.list -v ./api/config.yaml:/app/config.yaml -p 8019:8000 ghcr.io/memodb-io/memobase:main

Development

1. Start a local DB first by sh script/up-dev.sh
2. Open a new terminal window and cd ./api
3. Install python deps: uv sync
4. To test if you got everything right, run uv run pytest to see if all the tests are passed.
5. Launch Memobase Server in dev mode: uv run -m fastapi dev --port 8019

fastapi dev has hot-reload, so you can just modify the code and test it without relaunch the service.

Migrations

Memobase may introduce breaking changes in DB schema, here is a guideline of how to migrate your data to latest Memobase:

1. Install alembic: pip install alembic

2. Modify ./api/alembic.ini. Find the field called sqlalchemy.url in alembbic.ini, change it to your Postgres DB of Memobase

3. Run below commands to prepare the migration plan:

   cd api
   mkdir migrations/versions
   alembic upgrade head
   alembic revision --autogenerate -m "memobase changes"

4. ⚠️ Run the command alembic upgrade head again to migrate your current Memobase DB to the latest one.