Installation Guide

Installation Guide

Welcome to Actual Intelligent Memory, your context layer for the Gemini CLI. A.I.M. currently supports Linux and WSL (Ubuntu). macOS support is on the roadmap.

🚀 Installation & Setup

1. Prerequisites

Ensure you have the following basic tools installed on your system:

• Git
• Python 3 (with python3-venv)
• curl

(Note: See the Ubuntu/WSL Specifics section at the bottom if you are setting this up on a fresh Ubuntu installation).

2. Node.js & Gemini CLI

A.I.M. requires Node.js v20+ and the official Google Gemini CLI.

# 1. Install Node (using nvm — install nvm first if you don't have it: https://github.com/nvm-sh/nvm)
nvm install 20 && nvm use 20

# 2. Install Gemini CLI
npm install -g @google/gemini-cli

# 3. Authenticate (CRITICAL)
gemini login

OAuth Troubleshooting: If gemini login fails to open a browser (common in headless servers or WSL), use the direct API key method:

1. Get a key from Google AI Studio.
2. Run gemini --auth and select "Use a Gemini API key".

3. Local Infrastructure (Optional but Recommended)

Ollama (For Free Local Embeddings)
By default, A.I.M. uses nomic-embed-text via Ollama for zero-cost, private memory indexing.

curl -fsSL https://ollama.com/install.sh | sh
ollama pull nomic-embed-text

Obsidian (For Visualizing the Knowledge Graph)
A.I.M. synthesizes its memory into a standard Markdown folder (memory-wiki/) designed to be read as an Obsidian vault.

1. Download and install Obsidian for your OS.
2. Once A.I.M. is initialized (Step 4), open the generated memory-wiki/ directory in Obsidian using "Open folder as vault".

4. Install A.I.M.

You have two options for installing A.I.M. depending on your use case:

Option A: The Decoupled Exoskeleton (Recommended for New Projects)
This installs the A.I.M. engine globally so you can wrap it around any unique project without polluting your target repository.

# 1. Install the global engine
git clone https://github.com/BrianV1981/aim.git ~/.local/share/aim
cd ~/.local/share/aim
./setup.sh
source ~/.bashrc

# 2. Wrap your unique project
mkdir ~/my-new-project && cd ~/my-new-project
aim init
# (Select 'y' to perform a Clean Sweep to sever git history and wipe internal docs)

Option B: Core Framework Development (For Contributing to A.I.M.)
If you intend to contribute directly to the A.I.M. open-source codebase, clone it normally.

git clone https://github.com/BrianV1981/aim.git
cd aim
./setup.sh
source ~/.bashrc
aim init

5. Final Configuration

Launch the interactive dashboard to set your AI providers, configure your Subconscious Wiki Daemon, and secure your vault.

aim tui

---

🏗️ Provider Pre-requisites

• Google (Cloud): A valid Gemini API Key stored in your System Vault.
• Local (Ollama): Provider-Agnostic (Ollama is the default with the nomic-embed-text model, but you can swap to any OpenAI-compatible endpoint).
• OpenAI-Compat: A valid endpoint URL and API Key.

---

🛠️ Ubuntu/WSL Specifics & Troubleshooting

If you are running a fresh installation of Ubuntu (or WSL), you may need to apply these specific environment tweaks to get everything running smoothly:

1. Fixing the "Snap" Curl Bug
Ubuntu often ships with a sandboxed "Snap" version of curl that can interfere with installation scripts.
Remove it and install the native version alongside the required dependencies:

sudo snap remove curl
sudo apt update && sudo apt install -y curl git python3-venv libfuse2t64 xdg-utils

2. Running Obsidian AppImages in WSL
If you downloaded the .AppImage version of Obsidian on Linux/WSL, you must make it executable and run it with the --no-sandbox flag:

chmod +x ~/Downloads/Obsidian-*.AppImage
~/Downloads/Obsidian-*.AppImage --no-sandbox

Note: If the AppImage fails to launch with a libfuse.so.2 error, ensure you installed libfuse2t64 in the step above.

---

📖 Deep Dives & Philosophy

Looking for our raw benchmark logs, deep architectural maps, or the design history of A.I.M.?
👉 A.I.M. Knowledge Base (Public Obsidian Vault)

"I believe I've made my point." — A.I.M.