Installation¶

MemCastle is a single self-contained binary, memcastle. It embeds its database, so there is nothing else to install and no service to set up. Pick the method that suits your platform.

Standalone binary or native package¶

There are two ways to have MemCastle, and they run the same daemon.

• A standalone binary is one file, wherever you put it. It embeds everything the daemon needs to start, including the database schema and the data migrations, so it works offline and needs no directory of assets. Nothing is downloaded when it first starts.
• A native package (the AUR package, or a Linux distribution's own) installs the same binary into the system, and may also install read-only files that belong to the package rather than to the binary, such as the web UI or a service unit. Your package manager owns and updates them.

Your configuration and your data are never part of either. They stay under your home directory, whichever way MemCastle was installed:

Package assets and your data directories never overlap, so removing or upgrading a package cannot touch a palace. The daemon looks for assets in a fixed order: a directory you name with --assets-dir, then the installed share/memcastle, then what is built in. See Runtime assets for the rule, and ADR-013 for why. Core's packaged share/memcastle/sources/ and share/memcastle/integrations/ are empty: sources and agent integrations come from separately installed provider plugins. Package assets include the shared skills under share/memcastle/skills/. The standalone binary has no accompanying asset directory; install a provider plugin or supply assets separately. memcastle plugin install anthropic makes the Claude Code integration available; memcastle integration install claude-code copies it to your home and registers it with the agent (see Agent integrations). The last package asset is the web UI, under share/memcastle/web/dist/, which the daemon serves only when you set web.enable.

Install¶

Homebrew (macOS)¶

brew install noirbizarre/homebrew-tap/memcastle

The formula ships macOS builds only (Apple silicon and Intel), shared skills and the web UI. Core's source and agent-integration directories are empty; install a provider plugin for Codex or Claude Code. Install the OpenCode provider plugin separately. On Linux, use one of the other methods, including under Linuxbrew.

Arch Linux (AUR)¶

paru -S memcastle-bin   # or your AUR helper of choice

The memcastle-bin package installs the release binary for x86_64 and aarch64, a systemd user unit, /usr/lib/systemd/user/memcastle.service, the bash, zsh and fish completion scripts, empty source and agent-integration directories under /usr/share/memcastle/, and the shared skills under /usr/share/memcastle/skills/.

The package owns only those files and its licence under /usr. Your configuration (~/.config/memcastle), palace (~/.local/share/memcastle) and state (~/.local/state/memcastle) stay yours, and so does any secret: the package never writes to them.

The unit runs as you, not as root, with your XDG environment. Authentication is off by default, so it starts without any provisioning:

systemctl --user start memcastle
systemctl --user status memcastle
systemctl --user restart memcastle
systemctl --user stop memcastle

To start it at every login, and now:

systemctl --user enable --now memcastle

Logs are in the journal: journalctl --user -u memcastle -f. To enable authentication under this unit, see Under systemd.

Debian, Ubuntu, Fedora and RHEL family (.deb, .rpm)¶

Each release carries packages for linux-amd64 and linux-arm64:

sudo apt install ./memcastle_<version>_linux-amd64.deb
sudo dnf install ./memcastle_<version>_linux-amd64.rpm

They install /usr/bin/memcastle, the systemd user unit /usr/lib/systemd/user/memcastle.service, the bash, zsh and fish completion scripts, /usr/share/doc/memcastle/, empty source and integration directories under /usr/share/memcastle/, the shared skills under /usr/share/memcastle/skills/, and nothing under your XDG directories, so removing the package leaves your configuration and palace alone. The unit is used as on Arch: systemctl --user start memcastle, as described in Arch Linux. The package does not enable or start it. Verify them like any other download, as in Verify a download.

The packages are unsigned, there is no apt or dnf repository so upgrades are manual, and no dependencies are declared: the binary needs the glibc of its build image, so a distribution older than that fails at run time rather than at install.

Release binary¶

Download the binary for your platform from the latest release, make it executable and put it on your PATH. The assets named memcastle_<version>_<platform> are the executable itself, not an archive:

chmod +x memcastle_*_linux-amd64
mv memcastle_*_linux-amd64 ~/.local/bin/memcastle

Release tarball (Linux and macOS)¶

Each Unix platform also has memcastle_<version>_<platform>.tar.gz, laid out the way a native package is:

memcastle-<version>-<platform>/
├── bin/memcastle
└── share/
    ├── doc/memcastle/{LICENSE,README.md}
    └── memcastle/{sources,integrations,skills,web}/

Unpack it at a prefix to install it in the same places a package would:

sudo tar -xzf memcastle_*_linux-amd64.tar.gz --strip-components=1 -C /usr/local

The tarball carries shared skills and the web UI under share/memcastle/; its source and agent-integration directories are empty, and provider plugins are installed separately. Do not unpack it at ~/.local: that would put the package's assets inside your data directory, which MemCastle ignores as an asset location on purpose. Use /usr/local, or a directory of your own together with --assets-dir.

Verify a download¶

Every release lists a SHA-256 checksum for each file in SHA256SUMS:

sha256sum --check --ignore-missing SHA256SUMS

The files are also attested: GitHub signs a statement that its Actions workflow built exactly these bytes from this repository at the release tag. With the GitHub CLI:

gh attestation verify memcastle_<version>_linux-amd64 --repo memcastle/memcastle

A software bill of materials, memcastle-<version>.cdx.json in CycloneDX format, lists every crate in the build. The releases are built to be reproducible: the toolchain and build environment are pinned and build paths are remapped, so rebuilding a tag on the same target should give the same bytes.

From source¶

You need a Rust toolchain, version 1.90 or newer.

git clone https://github.com/memcastle/memcastle
cd memcastle
cargo install --path .

The first build compiles the embedded database and takes a few minutes. The storage engine is pure Rust, but a TLS dependency compiles some C, so a C compiler is needed; cmake may be needed too on some hosts. MemCastle is not published on crates.io, so cargo install memcastle does not work.

Check the install¶

memcastle --version

memcastle 0.2.0

memcastle --help lists every command; the CLI reference describes them.

Shell completion¶

memcastle completions <shell> prints a completion script for bash, zsh, fish, powershell or elvish. Package installs already include the bash, zsh and fish scripts. For a binary download or a source build, generate one yourself, for example:

memcastle completions bash > ~/.local/share/bash-completion/completions/memcastle

The CLI reference has the install location for each shell.

Platform notes¶

• Linux and macOS follow the same Unix XDG layout for configuration, data and runtime state. macOS does not use ~/Library/Application Support. See Configuration.
• Windows builds are published and tested, but there is no package and no dedicated layout: the same dot-directories are used under your home directory.
• No external database is needed for local use. A remote SurrealDB server is optional, see Storage and data.

Next¶

Quickstart starts the daemon and stores your first memories.