A knowledge graph-powered AI chatbot with persistent long-term memory.

MyCelium combines the power of LLMs with a knowledge graph to create an AI assistant that truly remembers. It extracts entities and relationships from conversations, stores them in a graph database, and uses semantic search to retrieve relevant context for every interaction.

• Knowledge Graph Memory - Automatically extracts entities and relationships from conversations using NetworkX and ChromaDB
• Multi-Source Ingestion - Import knowledge from Wikipedia, Project Gutenberg, bioRxiv, web pages, and more
• Interactive Graph Visualization - Explore and chat with your knowledge graph directly with a force-directed 2D visualization
• Multiple Workspaces - Create isolated memory contexts for different topics or projects
• Notes System - Create, search, and manage notes with semantic search (RAG)
• Concept Clustering - Automatically identify themes and topics in your knowledge graph
• Hot Topics & Connectors - Discover the most important and bridging nodes in your graph
• Reddit Integration - Search and browse Reddit discussions
• Emotional State System - The bot has emotions that evolve based on interactions
• Text-to-Speech - Generate audio lessons from your knowledge
• Growth Engine - Let the bot explore and expand its knowledge autonomously
• theWay (Skills) - Teach the AI reusable skills it can look up and follow
• Chrome Extension - Browser sidebar for quick chat and one-click page ingestion

1. Open the application in your browser
2. Click the + button in the sidebar
3. Enter a name for your workspace
4. Click Create

You can add knowledge to your graph in several ways:

• Chat naturally - The bot automatically extracts entities and relationships from conversations
• Wikipedia - Ask the bot to ingest a Wikipedia article: "Ingest the Wikipedia article about quantum computing"
• Web pages - Ask the bot to read a URL: "Summarize https://example.com/article" (if the page is too long, it will automatically ingest it into the graph first, then summarize)
• Project Gutenberg - Ingest free ebooks: "Find and ingest 'Pride and Prejudice' from Gutenberg"

• Click the Graph tab to see your knowledge graph visualization
• Click on nodes to see their details and connections
• Ask the bot to explore connections: "Traverse the graph from 'Machine Learning' and show me related concepts"

• Click the Notes tab to manage your notes
• The bot can create notes for you: "Create a note about our discussion on machine learning"
• Search notes semantically: "Search my notes for neural networks"
• Add and edit notes directly in the Notes tab, or ask the bot to help

• Concepts - Automatically clusters your graph into themes
• Hot Topics - Shows the most connected nodes in your graph
• Connectors - Identifies bridge nodes that connect different topics

• Automated Research - The bot proactively searches for information to fill gaps in its knowledge
• Recursive Expansion - You set the depth and breadth, and the bot explores related concepts

• Dynamic Emotions - Adjust the bot's emotional baseline (Happiness, Trust, Anger)
• Motive System - The bot's responses change based on its current emotional state

• Magic Persona Generator - Describe a character, and the AI will hallucinate a backstory, system prompt, and initial memories for it.
• Roleplay Mode - The bot adopts the generated persona, including specific knowledge and emotional traits.

Teach the AI reusable skills that it can look up and follow when prompted:

1. Create a Skill - Go to the theWay tab (compass icon), click +, and define:

   • Title: e.g., "Email Writing"
   • Summary: Brief description for search (e.g., "Professional email format")
   • Instructions: Detailed step-by-step instructions the AI will follow

2. Use a Skill - In chat, ask the AI to apply your skill:

   • "Use your email writing skill to write an email about the project update"
   • "Apply your code review skill to analyze this function"
   • "Follow your data analysis skill to interpret these numbers"

The AI will search for matching skills and follow the instructions you provided.

Access Mycelium directly from your browser with the Chrome extension:

• Sidebar Chat - Click the extension icon to open a chat panel in your browser sidebar
• One-Click Ingestion - Ingest the current page into your knowledge graph with a single click
• Page Context - Toggle "Include page" to send page content with your messages (auto-ingests if content exceeds limit)
• Workspace & Thread Switching - Quickly switch between workspaces and threads without leaving your browser

git clone https://github.com/yourusername/graph-llm.git
cd graph-llm

1. Prerequisites: Ensure you have Docker Desktop installed.

2. Configure paths (Optional): Create a .env file to customize where your data is stored:

   cp .env.example .env
   # Edit .env to set custom paths for memory data, logs, and config

   Example .env configuration:

   # Store memory data in a custom location
   MEMORY_DATA_PATH=/path/to/your/memory-data
   
   # Store logs in a custom location
   LOGS_PATH=/path/to/your/logs
   
   # Store config in a custom location (directory containing llm_config.json)
   CONFIG_PATH=/path/to/your/config

   If you don't create a .env file, the default paths (./backend/memory_data, ./backend/logs, ./backend) will be used.

3. Ensure config file exists: Before first run, make sure llm_config.json exists:

   cd backend
   cp llm_config.example.json llm_config.json
   # Edit llm_config.json with your settings
   cd ..

4. Run the application:

   docker-compose up --build

5. Access the App:

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:8000/docs

Note: Config changes made through the UI or by editing llm_config.json will persist across container restarts.

Prerequisites:

• Python 3.10+
• Node.js 18+

cd backend

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Ensure you have Node.js and npm installed:

• Mac (Homebrew): brew install node
• Windows: Download from nodejs.org
• Linux (Ubuntu/Debian): sudo apt install nodejs npm

Then run the frontend:

cd frontend

# Install dependencies
npm install

Copy the example config and customize it:

cd backend
cp llm_config.example.json llm_config.json
# Edit llm_config.json with your settings

See the Configuration section for provider-specific examples.

1. Open Chrome and navigate to chrome://extensions/
2. Enable Developer mode (toggle in top right)
3. Click Load unpacked
4. Select the extension/ directory from this repository
5. The Mycelium icon will appear in your browser toolbar
6. Click the icon to open the sidebar chat panel

Note: The extension connects to http://localhost:8000 by default. Make sure the backend is running.

Tip: You can configure these settings through the Global Settings menu in the application UI instead of manually editing the JSON file.

Edit backend/llm_config.json with your preferred provider:

You can customize where MyCelium stores its data by creating a .env file in the project root:

cp .env.example .env

Then edit the .env file to set custom paths:

• MEMORY_DATA_PATH: Where knowledge graphs, embeddings, and notes are stored (default: ./backend/memory_data)
• LOGS_PATH: Where application logs are stored (default: ./backend/logs)
• CONFIG_PATH: Directory containing llm_config.json (default: ./backend)

This is particularly useful when running with Docker, as it allows you to persist data outside the project directory or on different drives.

{
  "provider": "ollama",
  "embedding_provider": "ollama",
  "ollama_base_url": "http://localhost:11434",
  "ollama_chat_model": "llama3.2",
  "ollama_embedding_model": "nomic-embed-text",
  "temperature": 0.7,
  "tts_enabled": false
}

Setup Ollama:

# Install Ollama from https://ollama.ai/
# Pull required models
ollama pull llama3.2
ollama pull nomic-embed-text

⚠️ Running with Docker? When running MyCelium in Docker while Ollama runs on your host machine, use host.docker.internal instead of localhost:

"ollama_base_url": "http://host.docker.internal:11434"

This is because localhost inside Docker refers to the container itself, not your host machine.

{
  "provider": "lmstudio",
  "embedding_provider": "lmstudio",
  "chat_base_url": "http://localhost:1234/v1",
  "chat_api_key": "lm-studio",
  "chat_model": "your-model-name",
  "embedding_base_url": "http://localhost:1234/v1",
  "embedding_api_key": "lm-studio",
  "embedding_model": "text-embedding-nomic-embed-text-v1.5",
  "temperature": 0.7,
  "tts_enabled": false
}

⚠️ Running with Docker? Use host.docker.internal instead of localhost:

"chat_base_url": "http://host.docker.internal:1234/v1",
"embedding_base_url": "http://host.docker.internal:1234/v1"

{
  "provider": "openai",
  "embedding_provider": "openai",
  "chat_base_url": "https://api.openai.com/v1",
  "chat_api_key": "sk-your-api-key",
  "chat_model": "gpt-4o",
  "embedding_base_url": "https://api.openai.com/v1",
  "embedding_api_key": "sk-your-api-key",
  "embedding_model": "text-embedding-3-small",
  "temperature": 0.7,
  "tts_enabled": false
}

You can use different providers for chat (LLM) and embeddings. For example, use OpenAI for chat and Ollama for embeddings:

{
  "provider": "openai",
  "embedding_provider": "ollama",
  "chat_base_url": "https://api.openai.com/v1",
  "chat_api_key": "sk-your-api-key",
  "chat_model": "gpt-4o",
  "ollama_base_url": "http://host.docker.internal:11434",
  "ollama_embedding_model": "nomic-embed-text",
  "temperature": 0.7,
  "tts_enabled": false
}

If you prefer to run without Docker:

cd backend
source venv/bin/activate  # If using virtual environment
uvicorn app.main:app --reload --port 8000

The API will be available at http://localhost:8000

cd frontend
npm run dev

The UI will be available at http://localhost:5173

The LangGraph agent has access to various tools:

• Notes: create_note, read_note, update_note, delete_note, search_notes, list_notes
• Graph: add_graph_node, update_graph_node, delete_graph_node, add_graph_edge, update_graph_edge, delete_graph_edge, search_graph_nodes, traverse_graph_node
• Search: duckduckgo_search, search_images, search_concepts
• Web: visit_page, ingest_web_page
• Wikipedia: search_wikipedia, ingest_wikipedia_page
• Books: search_books, search_gutenberg_books, ingest_gutenberg_book
• Reddit: search_reddit, browse_subreddit, read_reddit_thread, get_reddit_user
• Research: search_biorxiv, read_biorxiv_abstract, search_arxiv, read_arxiv_abstract, ingest_arxiv_paper
• Learning: generate_lesson
• Skills (theWay): lookup_skill, create_skill