mnemOS

Sovereign voice-first memory engine for AI agents.

Local-first extraction, holographic vector search, and an esoteric oracle — no cloud dependency for core function.

Features

• Extraction pipeline — pulls facts from agent conversation history (Hermes state.db or any compatible SQLite)
• Voice bridge — spoken-format summaries via Edge TTS, with 120s LRU cache
• Oracle — esoteric/cryptic insight generation over your memory corpus
• Anticipatory prefetch — time-of-day context warming before queries arrive
• Multi-modal — audio/image/video facts as first-class types
• MCP stdio server — drop-in tool surface for any MCP-compatible agent
• MemoryProvider plugin — plugs into Hermes without core surgery
• Honcho cache loader — full-corpus import from Honcho JSON exports (70k+ conclusions)

Install

git clone https://github.com/YOUR_USERNAME/mnemos.git
cd mnemos
python3 scripts/init_db.py

Configuration

All paths are configurable via env vars. Defaults assume standalone install:

Env var	Default	Purpose
MNEMOS_HOME	~/.config/mnemos/	Root directory for DB + state
MNEMOS_DB	$MNEMOS_HOME/mnemos.db	SQLite database path
MNEMOS_HONCHO_CACHE	$MNEMOS_HOME/honcho_cache.json	Honcho corpus export
MNEMOS_TTS_VOICE	en-US-ChristopherNeural	Edge TTS voice
MNEMOS_TTS_RATE	+20%	TTS rate adjustment
MNEMOS_TTS_PYTHON	sys.executable	Python interpreter for edge-tts
FREelloM_URL	http://127.0.0.1:3000	FreeLLM gateway endpoint
FREelloM_MODEL	free	Model alias for synthesis
HERMES_HOME	~/.hermes	Hermes install root (optional)

Quick Start

Initialize database

python3 scripts/init_db.py

Start MCP server

python3 scripts/mcp_server.py

Run extraction

python3 scripts/extract.py

Voice context query

python3 scripts/mnemos_voice.py

Oracle divination

python3 scripts/mnemos_oracle.py

MCP Tools

Tool	Purpose
mnemos_search	Semantic search across local facts + Honcho cache
mnemos_recall	Increment recall count for a fact
mnemos_promote	Promote a fact to permanent storage
mnemos_forget	Soft-delete a fact
mnemos_status	Health check + fact counts
mnemos_voice_context	Spoken-format summary (text only)
mnemos_voice_context_tts	Spoken summary + TTS audio render
mnemos_prefetch_anticipate	Pre-warm voice cache for likely queries
mnemos_prefetch_status	Prefetch cache stats
mnemos_oracle_divinate	Esoteric insight from recent memory updates
mnemos_oracle_status	Oracle state

Architecture

mnemos_config.py    # Path resolution + env overrides
extract.py          # Extraction pipeline (Hermes state.db → mnemos.db)
mcp_server.py       # MCP stdio server (JSON-RPC)
mnemos_voice.py     # Voice context bridge + TTS
mnemos_oracle.py    # Esoteric insight engine
mnemos_prefetch.py  # Anticipatory context warming
mnemos_honcho.py    # Full-corpus Honcho cache loader
mnemos_hrr.py       # Holographic reduced representations
mnemos_entity.py    # Entity resolution + aliases
init_db.py          # Schema initialization

Hermes Integration

For Hermes users, mnemOS registers as a MemoryProvider plugin:

memory:
  provider: mnemos
  # mnemos MCP server auto-discovered

Slash commands: /mnemos push, /mnemos query <text>, /mnemos convo start, /mnemos convo end, /mnemos oracle divination

License

MIT