Mem

Mem is a local autonomous agent framework. It is built around durable goals, persistent memory, provider-neutral model routing, and one shared tool interface for external capabilities.

Mem is not a persona, mood, avatar, or companion simulator. The runtime is designed to behave like an engineering-grade autonomous assistant: it remembers state across sessions, reminds itself of the active goal, and executes only through explicit tool adapters and permission boundaries.

Features

• Persistent agent state in db/agent_state.json
• SQLite-backed long-term memory in db/memories.sqlite
• Pure-Python memory fallback when optional vector dependencies are absent
• Local and cloud model routing through core/models
• One common tool contract through core/tools
• Registered tool categories for filesystem, terminal, GitHub, Python, browser, web search, database, AgentRQ, and future MCP servers
• FastAPI API server and CLI entry point
• Deterministic autonomy ticks that record goal reminders

Install

Requirements:

• Python 3.10+
• Optional: a local OpenAI-compatible model endpoint such as Ollama
• Optional: GitHub Models token for cloud fallback

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Optional high-quality vector memory:

pip install -r requirements-optional.txt

Configure Models

Mem never hardcodes a required LLM. Configure providers with environment variables:

export MEM_MODEL_PROVIDERS="local,github"
export MEM_MODEL_ROUTE_CHAT="local,github"
export MEM_LOCAL_MODEL_URL="http://127.0.0.1:11434/v1/chat/completions"
export MEM_LOCAL_MODEL="llama3.1"
export GITHUB_TOKEN="your_github_models_token"
export MEM_GITHUB_MODEL="meta/Meta-Llama-3.1-8B-Instruct"

If no provider is reachable, chat falls back to an offline response that still includes the persistent goal and relevant memory.

Run

CLI:

python cli_chat.py

Useful CLI commands:

/state
/goal <new primary goal>
/objective <objective>
/tick
/quit

API:

python -m uvicorn core.api_server:app --host 127.0.0.1 --port 8000

Useful endpoints:

• POST /chat
• GET /state
• POST /state/goal
• POST /state/objectives
• POST /state/objectives/complete
• POST /autonomy/tick
• GET /tools
• GET /memories/search

Project Layout

core/
  agent_state.py   Persistent goal/objective/session state.
  autonomy.py      Deterministic autonomous tick engine.
  brain.py         Neutral chat orchestration.
  memory_rag.py    Persistent memory and retrieval.
  models/          Provider-neutral model contract and routing.
  tools/           Shared tool contract and adapters.
  api_server.py    FastAPI surface.
  scheduler.py     Long-running autonomous tick loop.
docs/
  ARCHITECTURE.md  Design notes and phased roadmap.
scripts/
  sandbox_runner.sh
  show_agent_state.py

Runtime files are intentionally ignored by git:

• db/
• logs/*.log
• __pycache__/

Development Checks

python -m py_compile core/agent_state.py core/autonomy.py core/brain.py core/api_server.py core/scheduler.py core/memory_rag.py cli_chat.py scripts/show_agent_state.py
python -c "from core.autonomy import decide_action; print(decide_action()['action'])"

Architecture Direction

Keep the framework boundary stable:

• tools implement Tool.run(request, context) -> ToolResult
• models implement ModelProvider.complete(request) -> ChatResponse
• autonomy operates from durable state, not personality or mood
• performance migrations should target measured hot paths only

Python remains the host language because the API, memory, and ML ecosystem are Python-native. If profiling proves a bottleneck, move that isolated path to Rust behind the same Python interface.

License

MIT License