NeuAI Tutorial - Complete Guide to Getting Started

Your Progress

0% Complete

Prerequisites Install Configure Basics Memory Subjects Agent

What You'll Learn

1 Prerequisites & Requirements
2 Installation
3 Configuration
4 Basic Usage
5 Working with Memory
6 Multi-Subject System
7 Agent Bridge (Automation)
8 Quick Reference

1 Prerequisites & Requirements

Before you begin, make sure you have the following:

A Python 3.7 or higher

NeuAI uses only the Python standard library - no pip packages needed!

Check your Python version

python3 --version

B Azure OpenAI Resource

You need an Azure OpenAI resource with a deployed model. You'll need:

Endpoint URL - e.g., https://your-resource.openai.azure.com/
API Key - Found in Azure Portal under "Keys and Endpoint"
Deployment Name - The name of your deployed model (e.g., gpt-4)

💡

Don't have Azure OpenAI yet?

Apply for access at azure.microsoft.com/products/ai-services/openai-service

2 Installation

NeuAI installs to ~/.neuai/ in your home directory. Follow these steps:

1 Download the files

Clone the repository or download the NeuAI files:

Clone repository

git clone https://github.com/kody-w/localFirstTools.git
cd localFirstTools

2 Create the NeuAI directory

Create ~/.neuai

mkdir -p ~/.neuai

3 Copy the core files

Copy NeuAI files

cp neuai-cli.py ~/.neuai/
cp neuai-agent-bridge.py ~/.neuai/
chmod +x ~/.neuai/neuai-cli.py

4 (Optional) Add to PATH

Create a convenient command to run NeuAI from anywhere:

Create neuai command

mkdir -p ~/.local/bin
ln -sf ~/.neuai/neuai-cli.py ~/.local/bin/neuai

# Add to your shell profile (.bashrc, .zshrc, etc.)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

📁

Installation Location

All NeuAI files live in ~/.neuai/. Your credentials are stored in ~/.neuai/config.json with restricted permissions (chmod 600).

3 Configuration

The first time you run NeuAI, it will guide you through configuration:

Run NeuAI for the first time

python3 ~/.neuai/neuai-cli.py

You'll see the setup wizard:

First-time Setup

╔══════════════════════════════════════════════════════════════╗
║                     Welcome to NeuAI                         ║
║           Your Intelligent AI Assistant                      ║
╚══════════════════════════════════════════════════════════════╝

⚙️  First-time setup required

Please provide your Azure OpenAI credentials:

Azure OpenAI Endpoint: https://your-resource.openai.azure.com/
API Key: ••••••••••••••••
Deployment Name [gpt-4]: gpt-4
API Version [2024-02-15-preview]: 2025-01-01-preview

🔗 Testing connection...
✅ Connection successful!

Configuration saved to ~/.neuai/config.json

Configuration Options

Flag	Description
`--configure`	Re-run the setup wizard
`--test`	Test your Azure OpenAI connection
`--reset`	Reset all configuration
`--global`	Force use of global ~/.neuai (ignore local)

🔐

Security Note

Your API key is stored locally in ~/.neuai/config.json with file permissions set to 600 (owner read/write only). Never commit this file to git!

4 Basic Usage

Interactive Mode

Start NeuAI in interactive mode for a chat-like experience:

Start interactive mode

python3 ~/.neuai/neuai-cli.py

Interactive Commands

Command	What it does
`/help`	Show all available commands
`/new`	Start a new conversation (keeps memories)
`/memory`	View all stored memories
`/remember <text>`	Store a new memory
`/forget`	Clear all memories
`/status`	Show connection and config info
`/export`	Export conversation to file
`/exit`	Exit NeuAI

Single Message Mode

Send a message and get a response without entering interactive mode:

Single message

python3 ~/.neuai/neuai-cli.py --message "What is the capital of France?"

5 Working with Memory

NeuAI's killer feature is persistent memory. Memories survive across sessions and help the AI remember context about you and your work.

Memory Types

Type	Use for	Example
`fact`	General facts	"User's name is Alex"
`preference`	Likes/dislikes	"User prefers TypeScript over JavaScript"
`insight`	Observations	"User works better in the morning"
`task`	To-dos/reminders	"User has a meeting on Tuesday"

Importance Levels

Level	Meaning
`1`	Low - nice to know
`2`	Minor importance
`3`	Normal (default)
`4`	High importance
`5`	Critical - never forget

Storing Memories via Agent Bridge

Store a memory

# Basic memory
python3 ~/.neuai/neuai-agent-bridge.py remember "User's favorite color is blue"

# With type and importance
python3 ~/.neuai/neuai-agent-bridge.py remember "User prefers dark mode" --type preference --importance 5

Retrieving Memories

Retrieve memories

# Get all memories
python3 ~/.neuai/neuai-agent-bridge.py memories

# Search by keyword
python3 ~/.neuai/neuai-agent-bridge.py recall "dark mode" "preferences"

6 Multi-Subject System

NeuAI lets you organize memories by subject (project, topic, client, etc.). Memories can be shared across multiple subjects without duplication.

Project Alpha

3 memories

Shared Memory

"API rate limit"

Project Beta

5 memories

Shared memories exist once but are linked to multiple subjects

Setting Up Project-Local Memory

Create local .neuai in your project

# Navigate to your project
cd ~/my-project

# Create local .neuai directory
mkdir -p .neuai/data

# Create project identity
cat > .neuai/identity.json << 'EOF'
{
  "user_guid": "my-project-001",
  "project": "my-project",
  "scope": "project"
}
EOF

# Initialize data files
echo '{"memories": {}, "subjects": {}}' > .neuai/data/memories.json

# Add to .gitignore
echo '.neuai/data/' >> .gitignore
echo '.neuai/identity.json' >> .gitignore

Multi-Subject Commands

Working with multiple subjects

# Store memory to multiple subjects
python3 ~/.neuai/neuai-agent-bridge.py remember "API uses OAuth 2.0" --subjects project-alpha,project-beta

# Query across subjects (auto-deduplicates)
python3 ~/.neuai/neuai-agent-bridge.py memories --subjects project-alpha,project-beta,global

# Smart store - links to existing if content matches
python3 ~/.neuai/neuai-agent-bridge.py remember "API uses OAuth 2.0" --subjects project-gamma --smart

# Link existing memory to new subject
python3 ~/.neuai/neuai-agent-bridge.py link memory-id-here new-subject-id

# List all subjects
python3 ~/.neuai/neuai-agent-bridge.py subjects

⚡

Smart Deduplication

When you query multiple subjects, shared memories appear only once. The shared_count field tells you how many subjects share that memory.

7 Agent Bridge (Automation)

The Agent Bridge (neuai-agent-bridge.py) provides a JSON API for automation and integration with AI agents like Claude Code.

All Bridge Commands

Command	Description
`chat <message>`	Send a message, get response
`memories`	List all memories
`recall <keywords>`	Search memories
`remember <content>`	Store a memory
`link <id> <subject>`	Link memory to subject
`unlink <id> <subject>`	Unlink memory from subject
`subjects`	List all subjects
`status`	Connection/config info
`new`	Start new conversation
`clear`	Clear all memories
`history [n]`	Get last n messages
`test`	Test connection

Example Output

                    JSON response format
                
{
  "success": true,
  "command": "memories",
  "count": 2,
  "queried_subjects": ["project-alpha", "global"],
  "deduplicated": true,
  "memories": [
    {
      "id": "abc123",
      "content": "User prefers dark mode",
      "type": "preference",
      "importance": 5,
      "subjects": ["project-alpha", "global"],
      "shared_count": 2
    }
  ]
}

Claude Code Integration

If you use Claude Code, there's a pre-configured agent at .claude/agents/neuai-assistant.md. It can:

Chat with NeuAI on your behalf
Store and recall memories
Manage subjects and contexts
Automate repetitive tasks

8 Quick Reference

📋 Command Cheat Sheet

python3 ~/.neuai/neuai-cli.py

Start interactive mode

neuai-agent-bridge.py test

Test connection

neuai-agent-bridge.py chat "Hi"

Send a message

neuai-agent-bridge.py memories

List all memories

remember "fact" --importance 5

Store important memory

remember "fact" --subjects a,b

Store to multiple subjects

memories --subjects a,b,c

Query across subjects

remember "fact" --smart

Auto-deduplicate

Directory Structure

                    File locations
                
~/.neuai/                      # Global installation
├── config.json                # API credentials (chmod 600)
├── identity.json              # User/global identity
├── neuai-cli.py               # Main CLI application
├── neuai-agent-bridge.py      # JSON API for automation
└── data/
    ├── memories.json          # Normalized memory storage
    └── conversations.json     # Conversation history

~/my-project/.neuai/           # Project-local (optional)
├── identity.json              # Project-specific ID
└── data/
    └── memories.json          # Project memories

🎉

You're all set!

You now know everything you need to use NeuAI effectively. Start storing memories and watch how the AI learns about you over time!