Memory‑OS 🧠

Memory‑OS is a local Personal Knowledge Operating System that automatically syncs, indexes, and retrieves information across your GitHub repositories, Gmail inbox messages, and Notion workspaces.

It provides both a command-line interface (CLI) and an interactive Terminal User Interface (TUI) powered by Hybrid RAG (Keyword + Vector + Knowledge Graph), local embeddings via SentenceTransformers, and ultra-fast LLM generation via the Groq API.

✨ Features

• 🌐 Multi-Source Ingestion: Sync repositories, issues, PRs, emails, and Notion pages via Composio OAuth connectors.
• ⚡ Hybrid RAG Retrieval: Combines SQLite (Keyword & Full-Text Search), Qdrant (Vector Similarity Search), and Neo4j / SQLite Graph (Knowledge Graph relationship lookups).
• 🤖 Groq LLM Integration: Uses Groq's high-speed LLM inference (llama-3.3-70b-versatile, llama-3.1-8b-instant) with streaming responses.
• 🎨 Interactive Terminal User Interface (TUI): Beautiful full-screen terminal app built with Textual, featuring chat streaming, live diagnostics, and sidebar navigation.
• 🛡️ Robust Offline Fallbacks: Gracefully degrades to local SQLite storage and local SQLite Graph when Docker database services or Neo4j are offline.
• 📁 Multi-Profile Workspaces: Easily create, list, and switch between separate knowledge profile contexts.
• 📦 Portability: Export and import complete knowledge bases into single compressed archive files.

🏗️ Architecture

flowchart TD
    subgraph Ingestion [1. Ingestion Layer]
        GH[GitHub Repos & Docs]
        GM[Gmail Inbox Messages]
        NT[Notion Page Contents]
        CP[Composio Integration Platform]
        GH --> CP
        GM --> CP
        NT --> CP
    end

    subgraph Storage [2. Multi-Model Storage Layer]
        DB[(SQLite: workspace.db)]
        QD[(Qdrant Vector DB)]
        N4J[(Neo4j Graph Database)]
        SQL_G[(SQLite Graph Fallback)]
        
        CP -->|Metadata & Docs| DB
        DB -->|Text Chunks| CH[Chunking Core]
        CH -->|Embeddings| EM["SentenceTransformer (all-MiniLM-L6-v2)"]
        EM -->|384d Vectors| QD
        
        DB -->|Graph Construction| N4J
        DB -->|Graph Construction| SQL_G
    end

    subgraph Retrieval [3. Hybrid RAG Layer]
        HS[Hybrid Search Router]
        QD -->|Vector Cosine Similarity| HS
        DB -->|FTS Keyword Matching| HS
        N4J -->|Graph Relationship Lookups| HS
        SQL_G -->|Graph Fallback Lookups| HS
        
        HR[Hybrid Ranker & Scorer]
        HS --> HR
        
        RAG[RAG Context Builder]
        HR -->|Merged Context| RAG
        
        LLM["Groq LLM Engine (Llama 3 Stream)"]
        RAG -->|Prompt Assembly| LLM
    end

    subgraph Interface [4. Interface Layer]
        TUI[Terminal User Interface App]
        CLI[Memory-OS CLI Commands]
        
        TUI -->|Search/Chat Queries| Retrieval
        CLI -->|Admin/Sync Commands| Ingestion
        CLI -->|Query Command| Retrieval
        LLM -->|Streamed Answer| TUI
        LLM -->|Formatted Output| CLI
    end

📦 Installation & Quick Start

1. Install via PyPI

pip install --upgrade cli-memory-os

2. Run the Onboarding Wizard

Initialize your workspace, set up database storage, configure API keys (Groq & Composio), and authorize connectors:

memory-os init

3. Sync Your Data

Import your documents, emails, and repositories:

memory-os sync

4. Ask Questions or Launch the Interactive TUI

Ask a quick question from the terminal:

memory-os ask "What was discussed in my latest emails about project deployment?"

Or launch the full interactive terminal application:

memory-os

🖥️ Interactive Terminal Application (TUI)

Launch the full-screen terminal interface by running memory-os without arguments.

Features of the TUI:

• 💬 Chat Panel: Ask questions with real-time token streaming and expandable source citations.
• 📊 Overview Dashboard: Monitor total indexed repositories, documents, emails, vectors, and active model configs.
• 🩺 Diagnostics Panel: Run line-by-line connection health checks for local databases, LLM APIs, and connectors.
• ⚙️ Config Manager: View and inspect active TOML configuration settings.

🗄️ Database Strategy

Memory-OS employs a multi-model storage strategy:

🚀 CLI Commands Reference

🔌 Plugin Connector Architecture

Every connector inherits from BaseConnector (connectors/base.py) and registers via @register (connectors/registry.py):

from connectors.base import BaseConnector
from connectors.registry import register

@register
class SlackConnector(BaseConnector):
    name = "Slack"
    slug = "slack"

    def authenticate(self) -> bool:
        # Perform OAuth or API validation
        return True

    def sync(self) -> dict:
        # Fetch messages and documents
        return {"synced": 42}

    def health(self) -> tuple[bool, str]:
        return True, "Connected"

🛠️ Configuration & Customization

Settings are managed under ~/.memory-os/config.toml:

[groq]
api_key = "gsk_..."
model = "llama-3.3-70b-versatile"

[composio]
api_key = "ak_..."

[vector]
provider = "qdrant"
host = "localhost"
port = 6333
embedding_model = "sentence-transformers/all-MiniLM-L6-v2"

To update settings directly from the terminal:

memory-os config set groq.model llama-3.1-8b-instant

🚀 CI/CD & Automated PyPI Releases

Memory-OS includes a complete GitHub Actions CI/CD pipeline (.github/workflows/ci-cd.yml).

Automated Workflow Actions:

1. Automated Testing: Runs pytest on every push and pull_request to main.
2. Automated PyPI Deployment: Automatically builds wheels and pushes the updated version to PyPI when changes are pushed to main or a new version tag (e.g. v0.1.16) is released.

Setup Instructions for PyPI Releases:

1. Option A: PyPI Trusted Publisher (Recommended / OIDC):
   • Go to PyPI Account Settings -> Publishers.
   • Add GitHub Publisher: Owner: anirudh-pedro (or your GitHub org/username), Repository: Memory-OS, Workflow name: ci-cd.yml.
2. Option B: GitHub Secret:
   • Create a PyPI API Token on PyPI Tokens.
   • In GitHub Repository -> Settings -> Secrets and variables -> Actions, add a repository secret named PYPI_API_TOKEN.

To release a new version:

1. Update version = "0.1.X" in pyproject.toml.
2. Commit and push to main (or push a tag git tag v0.1.X && git push origin v0.1.X).
3. GitHub Actions will run tests, build artifacts, and deploy to PyPI automatically.

📜 License

This project is licensed under the MIT License.