Install local agent memory and verify retrieval.

zer0dex pairs a markdown memory index that people can inspect with local semantic retrieval for details an agent should look up before a model call.

View source ↗Install from PyPI ↗Product overview →

Local first resultafter zer0dex check passes

$ zer0dex seed --source MEMORY.md
$ zer0dex serve --background
$ zer0dex query "Where does Atlas deploy?"

§ 01

Prerequisites and install

The supported preview path

Use Python 3.11 or 3.12, Ollama serving locally at http://localhost:11434, and the nomic-embed-text and mistral:7b models. The package metadata accepts Python 3.11+, but only 3.11 and 3.12 are CI-tested for this preview.

$ python -m venv .venv
$ source .venv/bin/activate
$ pip install zer0dex==0.1.1
# In a separate terminal, if Ollama is not already running:
$ ollama serve
# Back in this terminal:
$ ollama pull nomic-embed-text
$ ollama pull mistral:7b
$ zer0dex check

check is read-only. Resolve every failed line before the first real seed or serve.

§ 02

Seed, query, and stop

One disposable project

CREATEInitialize one project-local store

$ mkdir demo-memory && cd demo-memory
$ printf '# Notes\n\n## Preference\nUse concise factual replies.\n' > notes.md
$ zer0dex init --port 18429

Creates the config and storage directory in this project.

RETRIEVEStart and inspect it

$ zer0dex seed --source notes.md
$ zer0dex serve --port 18429 --background
$ zer0dex query 'What reply style is preferred?' --port 18429

A matching memory prints with a score. No match prints No relevant memories found.

CLOSECheck and stop the managed server

$ zer0dex status --port 18429
$ zer0dex stop

status reports Status: ok. stop only signals a server that proves the recorded per-launch identity.

§ 03

Configuration and reference

Project-local defaults

init writes .zer0dex.json. Defaults are collection zer0dex, user ID agent, port 18420, storage .zer0dex, and the two Ollama models above. Choose a collection, storage path, port, or user ID with init; back up the configuration and Chroma directory before changing models, dependencies, a collection name, or a store location.

CLICommands and exit behaviorinit, seed, serve, stop, query, status, and add.HTTPRequest and response contracthealth, query, add, validation, and score threshold.0.1.xCompatibility and migrationSupported runtime and documented migration commitments.

§ 04

Troubleshooting

Start with the observable failure

check fails: start Ollama, pull the named models, and rerun it. seed --dry-run works but seed fails: dry-run only parses markdown; the real seed also needs the local runtime and models. Query cannot connect: start zer0dex serve for that project and port, then use status.

Moving or changing a store: use an explicit storage path and re-seed after an embedding-model change. A different embedding model is a migration boundary; do not assume vectors remain comparable.

§ 05

Limits that affect deployment

Keep the host in control

The server is loopback-only and unauthenticated. The package does not run a pre-message hook or decide which retrieved text reaches a model. It does not promise complete recall, safe or true memories, stable backend ordering, hosted operation, or benchmark results for another workload.