aiduMEI AGENTS.md

AGENTS.md — Deploy, Verify, Operate aiduMEI

aiduMEI is a self-hosted long-term memory and wisdom engine for AI agents. It stores extracted facts, raw records, core memory, and recall traces behind a local HTTP API. It works with your host's native memory as the durable long-term layer; the host remains responsible for short-term conversation state.

Choose your engine mode

Need	Mode	Requires	Effect
Lowest footprint	AIDUMEI_ENGINE_MODE=cloud	Cloud LLM + embedding keys	No local model; during an outage recall is honestly degraded
Default resilience	AIDUMEI_ENGINE_MODE=auto	Cloud keys + pip install .[local-embed] + model fetch	Cloud-first, automatic local fallback and recovery
Fully local	AIDUMEI_ENGINE_MODE=local	Local embed dependencies and model; no API keys	Zero cloud tokens and zero outbound model calls

One-Line Prompt (canonical)

Send the canonical deployment text (all of prompts/install.txt, 13 lines) to your Agent — do not paraphrase it. Every step is judged by script exit codes and JSON evidence only.

Changing mode requires a service restart. If you previously ran cloud, run the local-vector backfill before expecting the local gear to recall older memories.

Install and start

git clone https://github.com/monkey2jack/aiduMEI.git
cd aiduMEI
python3.12 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp mem0_config_local.json.example mem0_config_local.json
cp .env.example .env
# Edit mem0_config_local.json: set llm.config and embedder.config.
# Edit .env: set AIDUMEM_ENTITY_KEYWORDS and, if exposing beyond loopback, AIDUMEM_API_TOKEN.
python api_server.py

For auto or local, also run:

pip install .[local-embed]
python scripts/fetch_local_embed_model.py

Prove memory is actually working

Run the end-to-end smoke after the service starts:

python scripts/e2e_smoke.py --json

Expected output: JSON ending with "status": "PASS", zero failures, and zero warnings; process exit code 0. /health: ok alone is not sufficient — this script writes a nonce, recalls it from a new request, checks trace visibility, and cleans up its temporary tenant.