Your personal, private & interactive AI companion

View Demo · Documentation · Report Bug · Request Feature

:notebook_with_decorative_cover: Table of Contents

• About The Project
  • Philosophy
  • Screenshots
  • Tech Stack
  • Features
• Roadmap
• Getting Started
  • Prerequisites
  • Installation
  • Environment Variables
  • Run Locally
• Usage
• Contributing
  • Code of Conduct
• FAQ
• License
• Contact
• Acknowledgements
• Official Team

:star2: About The Project

:thought_balloon: Philosophy

We at Existence believe that AI won't simply die as a fad or remain limited to an assistant. Instead, it will evolve to be a true companion of humans and our aim with Sentient is to contribute to that future. Building a true companion requires excellent automation which in turn requires deep personalization. And if we want the AI to be completely context aware of the user, privacy is non-negotiable. Hence, our goal is to build a completely private, personal & interactive AI companion. And we want to build it in the open, not behind closed doors

:camera: Screenshots

Agents in Sentient

Memories in Sentient

Local inference in Sentient

:space_invader: Tech Stack

Sentient Desktop App

• ElectronJS
• Next.js
• TailwindCSS
• FastAPI
• Ollama
• Neo4j
• PRAW Reddit API
• LinkedIn Scraper
• Nitter for X
• Google Workspace APIs
• Brave Search API

:dart: Features

• Local-first, with support for Ollama
• Multi-Model Support (Switch between multiple Ollama/Cloud models)
• MBTI Personality Test (Used to collect initial information about the user and their personality to personalize responses)
• LinkedIn, Reddit and X Integration for Personal Context
• Self-Managed Graph Memory - Sentient can learn about the user from their interactions with it. Memories are saved in a knowledge-graph.
• Agentic integrations for GSuite - Gmail, GCalendar, GDrive, GDocs, GSheets, GSlides support. Sentient can perform actions with all these tools.
• Web Search capabilities - Sentient can search the web for additional context to answer queries (if required).
• Multi-chat functionality (Context is maintained across chats)
• Auto-updates for the app (App automatically updates to newer versions)

:compass: Roadmap

• [x] Solving stability issues with model inference - improving structured outputs, better error handling, and more
• [ ] Dual Memory - Sentient will have a short-term memory and a long-term memory. The short-term memory will be stored in a relational DB and used to maintain reminders and other short-term information. Longer-term facts about the user will persist in the knowledge graph.
• [ ] Intent - Sentient will be able to perform actions autonomously based on triggers from the short-term memory.
• [ ] Tool-specific UI - for example, a tool that retrieves stock prices will also show a graph of the past trend of that particular ticker.
• [ ] Better Internet Search - Internet search will include images, citations, direct links to sources and more.
• [ ] More tools! - More tools will be added in the order of user requests. Current requests - Notion, LinkedIn, GitHub and WhatsApp.
• [ ] Advanced Voice Mode - Users will be able to talk to Sentient!
• [ ] Browser Use - Sentient will be able to control the browser and interact with websites to perform tasks
• [ ] Mobile Companion App - Mobile app will be added to pull context about the user and what is going on in their life. Notifications and other data will be synced between the desktop and mobile apps.
• [ ] Various options to host and use Sentient: Users will be able to use Sentient as only a desktop app (maximum privacy, no mobile app), self-hosted server (the desktop app acts a self-hosted server backend for the mobile app) or full cloud-hosted (Mobile app can be used independent of desktop app - server will be hosted and managed by the Sentient Team)
• [ ] Full integration at the OS level - integrate context from what you are doing right now by sharing your screen with Sentient
• [ ] Customizable Agentic Actions - users can create their own integrations using an easy-to-use interface. Users should also be able to trade custom Actions on a Marketplace.

:toolbox: Getting Started

:gear: Installation (Users)

If you're not interested in contributing to the project and simply want to use Sentient, download the latest release from our website.. All dependencies are packaged into our installer - you do not need to download anything else. You can find installation instructions in our docs.

:bangbang: Prerequisites (Contributors)

The following instructions are for Linux based machines, but they remain fundamentally same for Windows & Mac

Clone the project

  git clone https://github.com/existence-master/Sentient.git

Go to the project directory

  cd Sentient

Install the following to start contributing to Sentient:

• npm: The ElectronJS frontend of the Sentient desktop app uses npm as its package manager.

  Install the latest version of NodeJS and npm from here.

  After that, install all the required packages.

  bash cd ./src/interface && npm install

• python: Python will be needed to run the backend. Install Python from here. We recommend Python 3.11.

  After that, you will need to create a virtual environment and install all required packages. This venv will need to be activated whenever you want to run any scripts on the Python backend.

  bash cd src/model && python3 -m venv venv cd venv/bin && source activate cd ../../ && pip install -r requirements.txt

• Ollama: Download and install the latest version of Ollama from here.

  After that, pull the model you wish to use from Ollama. For example,

  bash ollama pull llama3.2:3b

• Neo4j Community: Download Neo4j Community Edition from here.

  Next, you will need to enable the APOC plugin. After extracting Neo4j Community Edition, navigate to the labs folder. Copy the apoc-x.x.x-core.jar script to the plugins folder in the Neo4j folder. Edit the neo4j.conf file to allow the use of APOC procedures:

  bash sudo nano /etc/neo4j/neo4j.conf

  Uncomment or add the following lines:

  ini dbms.security.procedures.unrestricted=apoc.* dbms.security.procedures.allowlist=apoc.* dbms.unmanaged_extension_classes=apoc.export=/apoc

  You can run Neo4j community using the following commands

  bash cd neo4j/bin && ./neo4j console

  While Neo4j is running, you can visit http://localhost:7474/ to run Cypher Queries and interact with your knowledge graph.

  ⚠️ On your first run of Neo4j Community, you will need to set a username and password. Remember this password as you will need to add it to the .env file on the Python backend.

🔒: Environment Variables (Contributors)

You will need the following environment variables to run the project locally. For sensitive keys like Auth0, GCP, Brave Search you can create your own accounts and populate your own keys or comment in the discussion titled 'Request Environment Variables (.env) Here' if you want pre-setup keys

For the Electron Frontend, you will need to create a .env file in the src/interface folder. Populate that .env file with the following variables (examples given).

  ELECTRON_APP_URL= "http://localhost:3000"
  APP_SERVER_URL= "http://127.0.0.1:5000"
  APP_SERVER_LOADED= "false"
  APP_SERVER_INITIATED= "false"
  NEO4J_SERVER_URL= "http://localhost:7474"
  NEO4J_SERVER_STARTED= "false"
  BASE_MODEL_REPO_ID= "llama3.2:3b"
  AUTH0_DOMAIN = "abcdxyz.us.auth0.com"
  AUTH0_CLIENT_ID = "abcd1234"

For the Python Backend, you will need to create a .env file and place it in the src/model folder. Populate that .env file with the following variables (examples given).

  NEO4J_URI=bolt://localhost:7687
  NEO4J_USERNAME=neo4j
  NEO4J_PASSWORD=abcd1234
  EMBEDDING_MODEL_REPO_ID=sentence-transformers/all-MiniLM-L6-v2
  BASE_MODEL_URL=http://localhost:11434/api/chat
  BASE_MODEL_REPO_ID=llama3.2:3b
  LINKEDIN_USERNAME=email@address.com
  LINKEDIN_PASSWORD=password123
  BRAVE_SUBSCRIPTION_TOKEN=YOUR_TOKEN_HERE
  BRAVE_BASE_URL=https://api.search.brave.com/res/v1/web/search
  GOOGLE_CLIENT_ID=YOUR_GOOGLE_CLIENT_ID_HERE
  GOOGLE_PROJECT_ID=YOUR_PROJECT_ID
  GOOGLE_AUTH_URI=https://accounts.google.com/o/oauth2/auth
  GOOGLE_TOKEN_URI=https://oauth2.googleapis.com/token
  GOOGLE_AUTH_PROVIDER_CERT_URL=https://www.googleapis.com/oauth2/v1/certs
  GOOGLE_CLIENT_SECRET=YOUR_SECRET_HERE
  GOOGLE_REDIRECT_URIS=http://localhost
  AES_SECRET_KEY=YOUR_SECRET_KEY_HERE (256 bits or 32 chars)
  AES_IV=YOUR_IV_HERE (256 bits or 32 chars)
  AUTH0_DOMAIN=abcdxyz.us.auth0.com
  AUTH0_MANAGEMENT_CLIENT_ID=YOUR_MANAGEMENT_CLIENT_ID
  AUTH0_MANAGEMENT_CLIENT_SECRET=YOUR_MANAGEMENT_CLIENT_SECRET
  OPENAI_API_KEY=sk-proj-YOUR-API-KEY-HERE
  GEMINI_API_KEY=YOUR_API_KEY_HERE
  CLAUDE_API_KEY=sk-ant-api03-YOUR_API_KEY_HERE
  OPENAI_API_URL=https://api.openai.com/v1/chat/completions
  GEMINI_API_URL=https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent
  CLAUDE_API_URL=https://api.anthropic.com/v1/messages
  APP_SERVER_PORT=5000
  AGENTS_SERVER_PORT=5001
  MEMORY_SERVER_PORT=5002
  CHAT_SERVER_PORT=5003
  SCRAPER_SERVER_PORT=5004
  UTILS_SERVER_PORT=5005
  COMMON_SERVER_PORT=5006
  AUTH_SERVER_PORT=5007

:running: Run Locally (Contributors)

Install dependencies

Ensure that you have installed all the dependencies as outlined in the Prerequisites Section.

Start Neo4j

Start Neo4j Community Edition first.

cd neo4j/bin && ./neo4j console

Start the Python servers

Example: Agents Server

  cd src/model/venv/bin/ && source activate
  cd ../../agents && sudo ./startserv.sh

⚠️ Be sure to modify the startserv.sh script with the absolute paths to your scripts and your venv.

⚠️ You will need to run al