README.md

metadata

title: Universal Memory Agent
sdk: gradio
app_file: app.py
python_version: '3.10'

Universal Memory Agent

Universal Memory Agent is a production-ready, continuously learning AI assistant that turns every user interaction into durable business memory, then answers with strict evidence from what it has learned, not hallucinated guesses. It is powerful because it combines tool-calling autonomy, hybrid retrieval, and conflict-aware memory updates (newest fact wins), so knowledge stays accurate in fast-changing domains like sales, support, operations, and compliance. For business, this means faster onboarding, consistent answers across teams, better personalization, and lower knowledge-loss risk when people or processes change. It is cheaper than fine-tuning because you avoid retraining cycles, GPU-heavy experimentation, model versioning overhead, and repeated deployment costs every time information changes; you simply update memory in real time. It is better than classic RAG for dynamic workflows because it does not only retrieve static documents, it actively maintains structured, evolving, user-specific knowledge with explicit write/update behavior and deterministic recency handling. In short, it delivers enterprise-grade adaptability, traceability, and ROI with startup-level simplicity.

Features

• Tool-calling agent using langchain-mistralai (ChatMistralAI)
• Two tools:
  • store_knowledge: stores/updates memory in FAISS-backed memory
  • answer_from_knowledge: answers strictly from stored memory
• Hybrid retrieval: BM25Plus + dense embeddings (mistral-embed via Mistral API)
• Latest fact wins for conflicting updates (PI=4, PI=7 => PI=7)
• Strict prompt separation:
  • system prompt: prompts/system_prompt.txt
  • user prompt: prompts/user_prompt.txt
• Gradio frontend with per-user namespace isolation

Required Environment Variables

• API_KEY (or MISTRAL_API_KEY)

Optional:

• MEMORY_DATA_DIR (default: ./data/faiss)
• APP_PORT (default: 8501)
• MISTRAL_MODEL (default: mistral-small-latest)
• EMBEDDING_MODEL (default: mistral-embed)
• MISTRAL_MAX_RETRIES (default: 6)
• MISTRAL_MAX_CONCURRENT_REQUESTS (default: 1)
• MISTRAL_TIMEOUT_SECONDS (default: 120)
• RATE_LIMIT_BASE_DELAY_SECONDS (default: 1.0)
• RATE_LIMIT_MAX_DELAY_SECONDS (default: 16.0)
• DENSE_WEIGHT (default: 0.55)
• SPARSE_WEIGHT (default: 0.45)
• TOP_K (default: 6)

Simplest Run (No Docker)

1. Open app.py in your IDE.
2. Run the file directly (Run button / Debug button).

app.py auto-starts Gradio and opens the app server.

Local Python Run (Manual)

pip install -r requirements.txt
python app.py

Optional CLI run:

python main.py

Behavior Contract

• LLM decides which tool to call (store_knowledge or answer_from_knowledge) every turn.
• Fact-only user message -> stores memory and responds exactly: understood
• If user message has both update + question -> store first, then answer from memory.
• Conflicting facts -> newest value must replace older value.
• Greetings/small talk/onboarding -> model may respond directly without tools.
• Tool choice and conversational style are controlled by prompt policy (not hardcoded keyword routing).
• Unknown memory-based answer -> asks user to share domain facts so the agent can learn.

Hugging Face Spaces Deployment

1. Create a new Gradio Space.
2. Push this repository.
3. Add Space secrets/variables:
   • API_KEY
   • MEMORY_DATA_DIR=./data/faiss
   • EMBEDDING_MODEL=mistral-embed
   • MISTRAL_MAX_RETRIES=6
   • MISTRAL_MAX_CONCURRENT_REQUESTS=1
4. Space starts app.py automatically (configured in front matter).

Notes for Spaces:

• No external Postgres is needed anymore.
• FAISS data is local to the Space filesystem. If the Space restarts or rebuilds, memory may reset unless persistent storage is configured.

Rate Limit Notes

• If Mistral returns 429 rate_limited, the app now retries with exponential backoff.
• If retries still fail, Gradio/CLI returns a friendly message instead of crashing.
• If you still hit limits often, reduce request bursts or move to a higher Mistral quota tier.