This section provides an overview of the development toolchain, automation workflows, and release processes for the Basic Memory project. The infrastructure is designed to support a local-first architecture while maintaining high reliability across dual database backends (SQLite and PostgreSQL) and multiple distribution channels (PyPI, NPM, Homebrew, and Docker).
The project utilizes uv for Python package management and just as a command runner to provide a consistent interface for development tasks.
uv handles virtual environments, dependency resolution, and builds Dockerfile8-17.justfile defines the canonical entry points for installation, testing, and linting justfile11-15.fast-check command to ensure code quality before commits justfile107-111.alembic manages schema evolution for both SQLite and Postgres backends, with a dedicated just migration command for developers AGENTS.md44.anthropics/claude-code-action .github/workflows/claude.yml53-57 .github/workflows/claude-review.yml29-33.The following diagram illustrates the transition from local development to automated CI/CD pipelines.
Development to CI Pipeline
Sources: justfile107-111, .github/workflows/test.yml12-13, .github/workflows/release.yml3-6, .github/workflows/test.yml217-224.
Basic Memory employs a three-tier testing strategy to ensure stability across its complex synchronization and search logic.
tests/): Focus on individual components with extensive mocking AGENTS.md92.test-int/): Test real-world scenarios, including actual filesystem I/O, MCP client interactions, and database persistence AGENTS.md93.testcontainers) justfile19-33.To optimize developer feedback loops, the project uses pytest-testmon to execute only those tests affected by recent code changes justfile79-80. A shared cache strategy (scripts/testmon_cache.py) allows PR builds to seed their test state from main to avoid redundant full-suite runs justfile88-90.
For details on fixtures, testcontainers, and mocking strategies, see [Testing Infrastructure (#9.1)].
The release process is highly automated, ensuring that version strings remain synchronized across the Python core, MCP server manifests, and various agent integrations (Claude Code, Hermes, OpenClaw, and Codex).
The release is orchestrated via just release <version>, which triggers quality checks, updates version strings across all manifests, and creates a release PR .claude/commands/release/release.md39-56. The versioning utility maps Python-style pre-releases to NPM-compatible semver where necessary for the OpenClaw integration .github/workflows/release.yml62-64.
The release.yml workflow handles multi-platform distribution:
basic-memory Python package .github/workflows/release.yml54-58.basic-memory.rb formula in the dedicated tap via a custom git and sed patching process that handles GitHub's authentication redirects .github/workflows/release.yml99-166.linux/amd64, linux/arm64) to GHCR using Depot .github/workflows/docker.yml50-60.Release Entity Mapping
Sources: .claude/commands/release/release.md44-56, .github/workflows/release.yml44-63, Dockerfile27-31, .github/workflows/release.yml71-98.
For details on the release validation and automated tag triggers, see [Release Process and CI Automation (#9.2)].
The repository contains a standalone benchmark suite located in benchmarks/ designed to evaluate retrieval quality and sync performance. It provides a CLI tool bm-bench for running evaluations against local and cloud providers. The suite includes datasets like LoCoMo, LongMemEval-S, and ConvoMem, and uses LLM-as-judge scoring for QA tasks.
For details on the benchmark CLI, scoring metrics, and supported providers, see [Benchmark Suite (#9.3)].
The project provides a Dockerfile based on python:3.12-slim-bookworm Dockerfile1. It is configured for production use with the following features:
appuser for security Dockerfile19-22.BASIC_MEMORY_HOME and BASIC_MEMORY_PROJECT_ROOT for volume mounting Dockerfile37-39.basic-memory --version to verify container health Dockerfile48-49.Sources: Dockerfile1-53, .github/workflows/docker.yml1-60, docker-compose.yml1-85.