User message
     │
     ▼
┌─────────────────────────────────────────────────────┐
│                   Session graph                     │
│  Load working memory (Redis)                        │
│       → Retrieve episodic memories (pgvector)       │
│       → Retrieve long-term facts (pgvector)         │
│       → Inject memory block into system prompt      │
│       → Generate LLM response with memory context  │
└─────────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────────┐
│                  Ingestion graph                    │
│  LLM extracts key facts from conversation           │
│       → Auto-select chunk strategy                  │
│       → Embed chunks (OpenAI text-embedding-3)      │
│       → Store in pgvector + extracted facts as      │
│         long-term memories                          │
└─────────────────────────────────────────────────────┘

git clone <repo-url>
cd mnemosyne

cp .env.example .env

# Required: OpenAI key for embeddings (always needed)
OPENAI_API_KEY=sk-...

# Required: choose one LLM provider for generation
LLM_PROVIDER=gemini          # anthropic | openai | gemini | local
GEMINI_API_KEY=your-key      # or ANTHROPIC_API_KEY / OPENAI_API_KEY

# Optional but recommended: Cohere for reranking
COHERE_API_KEY=

# Optional: Langfuse for observability (get keys at cloud.langfuse.com)
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...

# Optional: encryption at rest for stored memories
ENCRYPT_KEY=

make up

pip install -e ".[dev]"
# or with uv:
uv pip install -e ".[dev]"

make migrate

python mcp/server.py

{
  "mcpServers": {
    "mnemosyne": {
      "command": "python",
      "args": ["/absolute/path/to/mnemosyne/mcp/server.py"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/mnemosyne"
      }
    }
  }
}

"Remember that I prefer dark mode in all my projects."
"What do you know about my coding preferences?"
"Forget everything about my old job."
"What did we discuss last week about the auth system?"

{
  "mcpServers": {
    "mnemosyne": {
      "command": "python",
      "args": ["/absolute/path/to/mnemosyne/mcp/server.py"]
    }
  }
}

import asyncio
from mnemosyne.agents.router import Intent, route

async def main():
    # Store a memory
    await route(
        Intent.INGEST,
        user_id="user-123",
        content="The user prefers Python over JavaScript and uses VS Code.",
        conversation_id="conv-abc",
        tier="long_term",
    )

    # Ask a question — memory is retrieved and injected automatically
    result = await route(
        Intent.CHAT,
        user_id="user-123",
        conversation_id="conv-abc",
        user_message="What editor should I set up for this project?",
    )
    print(result.response)
    # → "Based on your preference for VS Code, here's how to set it up..."

    # Retrieve raw memories without generating a response
    result = await route(
        Intent.RETRIEVE,
        user_id="user-123",
        query="programming language preferences",
    )
    for memory in result.final_memories:
        print(f"[{memory.tier.value}] {memory.content} (score: {memory.score:.3f})")

asyncio.run(main())

# Install Ollama from https://ollama.com, then pull a model
ollama pull llama3

LLM_PROVIDER=local
LOCAL_LLM_BASE_URL=http://localhost:11434
LOCAL_LLM_MODEL=llama3

# Decay old memories — reduces score of stale episodic/long-term memories
# Recommended: run nightly
python jobs/decay_sweep.py

# Rebuild BM25 keyword search index
# Recommended: run after bulk ingestion
python jobs/index_rebuild.py

make test    # run test suite
make lint    # ruff + mypy
make down    # stop Docker services

mnemosyne/
├── agents/          # LangGraph pipelines (ingestion, retrieval, session)
├── chunking/        # Auto-selecting text chunking strategies
├── config/          # Settings (pydantic-settings) and structured logging
├── embedding/       # OpenAI and local embedding providers, tiered routing
├── evals/           # Evaluation harness and golden set
├── infra/           # Dockerfile
├── jobs/            # Decay sweep and index rebuild cron jobs
├── llm/             # LLM providers: Anthropic, OpenAI, Gemini, Local (Ollama)
├── mcp/             # MCP server and tool definitions
├── memory/          # Memory types, decay, and access tracking
├── observability/   # Langfuse tracing, metrics, health check
├── prompts/         # YAML prompt templates
├── retrieval/       # Hybrid search, BM25, reranker, RRF, assembler
└── storage/         # Postgres (pgvector), Redis, S3, encryption, RLS