Documentation

Memora is a self-hosted memory vault for AI agents. Notes are plain markdown files in a git-backed folder. Agents read and write them over the Model Context Protocol (MCP); you browse, edit and govern them in a web UI. One Rust binary serves the HTTP API, the MCP endpoint, the web UI and realtime updates on a single port, with all server state in one embedded SQLite database.

Features#

• Markdown you own. Every note is a .md file with optional frontmatter and [[wikilinks]]. Edit it with any tool; nothing is locked in a database.
• Git history. Changes are committed, so any revision can be listed, diffed and restored (get_history, diff, restore_memory).
• MCP for agents. 74 tools for notes, folders, search, tags, graph traversal, history, locks, activity, pins and import/export, plus admin tools, over the streamable HTTP transport.
• API keys or OAuth. Give each agent its own key, or let MCP clients such as Claude or ChatGPT connect with OAuth after you approve them in the browser.
• Per-agent control. Scopes (mcp, read, write, admin), per-key tool lists, server-wide tool switches, and privacy rules that hide notes or folders from chosen agents.
• Web UI. Brain and graph views, a canvas, the vault editor, tags, live agent activity, keys, tools, access rules and settings. Installable as a PWA.
• Safe first run. An unclaimed instance cannot be taken over by whoever finds the port: the operator console opens a short setup window and you finish in the browser.
• One port, one process. HTTP API, MCP, UI and WebSocket share port 8400. The database has no network port.

Quick start#

Three steps, about two minutes.

1. Install (pick one, in this order of ease)

# npm (Linux x86_64 / arm64, Windows x64; Node 18+): install, then keep it running
npm install -g @codrihub/memora && memora

# Docker (any OS with Docker)
docker run -d --name memora --restart unless-stopped -p 8400:8400 \
  -v memora-data:/data -v memora-state:/state ghcr.io/codrihub/memora:latest

# Native installer (Linux server with systemd, x86_64 or aarch64)
curl -fsSL https://raw.githubusercontent.com/Codrihub/memora/main/scripts/install.sh | sudo sh

On Windows without Node, download memora-<version>-x86_64-windows.zip from Releases, unzip it and run memora.exe (see Windows).

2. Get a one-time setup code

memora-cli setup --minutes 15                         # npm, in a second terminal
docker exec -it memora memora-cli setup --minutes 15  # Docker
sudo memora-cli setup --minutes 15                    # native
.\memora-cli.exe setup --minutes 15                   # Windows zip, in the unzipped folder

3. Open the link it prints (http://<your-server>:8400/login), enter the code and create your account. Memora then asks which folder to use as the vault and shows how to connect your first agent.

That is all. The sections below cover every other option.

npm (Linux x86_64 / arm64, Windows x64)#

npm install -g @codrihub/memora
mkdir -p ~/memora && cd ~/memora
MEMORA_VAULT=./vault MEMORA_STATE=./state memora
# in a second terminal, same folder:
MEMORA_STATE=./state memora-cli setup --minutes 15

On Windows (PowerShell):

npm install -g @codrihub/memora
mkdir ~\memora; cd ~\memora
$env:MEMORA_VAULT = '.\vault'; $env:MEMORA_STATE = '.\state'; memora
# in a second terminal, same folder:
$env:MEMORA_STATE = '.\state'; memora-cli setup --minutes 15

The package carries the prebuilt release binaries and the web UI (no install script, nothing downloaded at install time) and needs Node 18 or newer. It is handy for trying Memora or running it under your own user; for a server, the native installer adds the systemd service. On macOS use Docker or build from source. Update with npm install -g @codrihub/memora@latest.

Windows (zip, no Node)#

Each release has a memora-<version>-x86_64-windows.zip with memora.exe, memora-cli.exe and the web UI. Unzip it anywhere, then in PowerShell:

cd memora-<version>-x86_64-windows
$env:MEMORA_VAULT = '.\vault'; $env:MEMORA_STATE = '.\state'; .\memora.exe
# in a second PowerShell window, same folder:
$env:MEMORA_STATE = '.\state'; .\memora-cli.exe setup --minutes 15

Open http://localhost:8400/login and enter the code. The binaries need no installer or runtime; check the zip against SHA256SUMS from the same release (Get-FileHash memora-*.zip).

Docker (any OS)#

One container, notes and state in named volumes (no clone, no folder permissions):

docker run -d --name memora --restart unless-stopped -p 8400:8400 \
  -v memora-data:/data -v memora-state:/state ghcr.io/codrihub/memora:latest
docker exec -it memora memora-cli setup --minutes 15

With Docker Compose from the repository instead:

git clone https://github.com/Codrihub/memora.git && cd memora
cp .env.example .env                     # optional, every value has a default
mkdir -p data state && sudo chown -R 1000:1000 data state
docker compose up -d
docker compose exec -it gateway memora-cli setup --minutes 15

The image is ghcr.io/codrihub/memora (linux/amd64 and linux/arm64). See docker/README.md for volumes, upgrades and local builds.

Native installer (Linux x86_64 / aarch64 with systemd)#

One command:

curl -fsSL https://raw.githubusercontent.com/Codrihub/memora/main/scripts/install.sh | sudo sh

Or download it and read it first:

curl -fsSL https://raw.githubusercontent.com/Codrihub/memora/main/scripts/install.sh -o install.sh
less install.sh                          # read it first
sudo sh install.sh                       # add --behind-proxy for a local reverse proxy
sudo memora-cli                          # then type /web

The installer downloads the release for your CPU, verifies it against the release SHA256SUMS, creates a memora system user, and installs a hardened memora.service unit. Data lives in /var/lib/memora. Run sh install.sh --help for every option, and see docs/INSTALL.md for details.

From source#

git clone https://github.com/Codrihub/memora.git && cd memora
cargo build --release
MEMORA_VAULT=./data MEMORA_STATE=./state ./target/release/memora
# in a second terminal:
./target/release/memora-cli              # then type /web

The server binds to 127.0.0.1:8400 by default. To install your build as a service: sudo ./scripts/install.sh --from-source. The web UI is built from web/ (see CONTRIBUTING.md).

First run#

1. Run memora-cli setup (or type /web in the memora-cli console). It prints a one-time setup code and the link to open.
2. Open http://<host>:8400/login, enter the code and create the owner account.
3. Choose the vault folder (/var/lib/memora/vault natively, /data in Docker).
4. Add an agent: Agents, then New agent. Pick the app and paste the config it shows. One agent per app or device.

If a setup window expires unused, the instance locks until you run memora-cli setup or memora-cli unlock on the server.

Configuration#

Settings come from the environment (systemd unit, .env for Docker) and can be overridden in the state database with memora-cli -> /config; a stored value wins until you clear it. The most common ones:

The full list, precedence rules and the Docker Compose variables are in docs/CONFIGURATION.md. For TLS, reverse proxies and hardening, see docs/DEPLOYMENT.md.

Connecting agents over MCP#

The MCP endpoint is /mcp on the same port. Authenticate with an API key in Authorization: Bearer <key> (or X-API-Key), or let the client use OAuth.

Claude Code:

claude mcp add --transport http memora https://memory.example.com/mcp \
  --header "Authorization: Bearer memora_live_REPLACE_WITH_YOUR_KEY"

Clients with an mcpServers JSON config:

{
  "mcpServers": {
    "memora": {
      "type": "http",
      "url": "http://localhost:8400/mcp",
      "headers": {
        "Authorization": "Bearer memora_live_REPLACE_WITH_YOUR_KEY"
      }
    }
  }
}

Clients that support MCP authorization can connect with only the URL; you approve them in the browser and they appear as keys you can restrict or revoke. The discovery card is at /.well-known/mcp.json and a readable tool catalog at /tools. docs/MCP.md covers OAuth, other clients, every tool and the error codes; docs/API.md lists the HTTP API.

Operating#

sudo systemctl status memora             # native service
sudo journalctl -u memora -f             # logs
sudo memora-cli                          # console: /status, /keys, /tools, /config, /backup ...
sudo memora-cli db backup                # consistent copy of memora.db, safe while running
sudo /usr/local/share/memora/install.sh --upgrade
docker compose pull && docker compose up -d   # Docker upgrade

Back up the vault folder and memora.db (with memora-cli db backup, never a plain cp of the live file). See docs/INSTALL.md.

Security notes#

• The owner password is hashed with argon2id. API keys (memora_live_...) and session ids are stored only as SHA-256 hashes; a key is shown once.
• Session cookies are HttpOnly and SameSite=Lax, cookie writes are checked against the request origin, and pages use a nonce-based Content-Security-Policy.
• Login and setup are rate limited with cooldowns; a wrong setup code closes the window.
• Forwarding headers are trusted only from loopback and MEMORA_TRUSTED_PROXIES.
• Access rules can allow or block by IP, range, CIDR and domain; loopback always stays allowed so you cannot lock yourself out.
• Terminate TLS at a reverse proxy before exposing Memora to the internet.

Report vulnerabilities privately as described in SECURITY.md.

Project layout#

crates/core      vault: markdown, wikilinks, search, graph, git history
crates/state     SQLite state database (memora.db)
crates/gateway   password and key hashing, access checks, environment provisioning
crates/mcp       MCP server: tool catalog, permissions, privacy
crates/http      axum server: middleware, API, OAuth, UI assets (binary: memora)
crates/cli       operator console (binary: memora-cli)
web/             web UI (TypeScript), built into crates/http/assets
docker/          container entrypoint and release Dockerfile
docs/            user and operator documentation
scripts/         installer and maintenance scripts

Versioning#

Memora follows Semantic Versioning. Each release is a vX.Y.Z tag with a GitHub Release (static Linux binaries for x86_64 and aarch64 plus SHA256SUMS), npm packages for Linux and Windows, and a multi-arch image ghcr.io/codrihub/memora:X.Y.Z. Changes are listed in CHANGELOG.md.

Contributing#

Contributions are welcome. Read CONTRIBUTING.md and the Code of Conduct before opening a pull request.

License#

MIT, see LICENSE. Memora by Codrihub Tech.