alaala

README

ᜀᜎᜀᜎ

"alaala" (Tagalog for "memory") - A semantic memory system for AI assistants

A high-performance Go implementation of a semantic memory system that enables AI assistants to maintain context across sessions using the Model Context Protocol (MCP). Built with Weaviate for vector search, SQLite for metadata, and Claude AI for intelligent memory curation.

Features

• MCP Protocol Integration - Works seamlessly with Cursor, Claude Desktop, and other MCP-compatible clients
• Hybrid Memory Injection - Auto-inject context at session start + dynamic updates on each prompt + on-demand searches
• AI-Powered Curation - Claude, OpenRouter, or Ollama analyzes conversation transcripts
• Multiple AI Providers - Anthropic (cloud), OpenRouter (multi-model), or Ollama (local/private)
• Real Embeddings - Ollama provides semantic vector embeddings locally
• Vector Search - Weaviate similarity search with real embeddings
• Memory Graph - Follow relationships between memories for richer context
• Multi-Project Workspaces - Automatic project isolation
• Session Management - Temporal context and continuity

Prerequisites

• Docker - Required for Weaviate vector database

  • macOS: Colima (recommended, lightweight) or Docker Desktop
  • Linux: Docker Engine
  • Windows: Docker Desktop

• Ollama - Optional, for local AI (embeddings + curation)

  • macOS: brew install ollama
  • Linux/Windows: https://ollama.ai/download

Quick Start

Installation

Homebrew (Recommended for macOS/Linux)

brew tap 0xGurg/distillery
brew install alaala

That's it! Homebrew handles everything.

Manual Binary Download

Download from GitHub Releases:

# macOS (ARM64)
curl -L https://github.com/0xGurg/alaala/releases/latest/download/alaala_darwin_arm64.tar.gz | tar xz
sudo mv alaala /usr/local/bin/

# macOS (AMD64)
curl -L https://github.com/0xGurg/alaala/releases/latest/download/alaala_darwin_amd64.tar.gz | tar xz
sudo mv alaala /usr/local/bin/

# Linux (AMD64)
curl -L https://github.com/0xGurg/alaala/releases/latest/download/alaala_linux_amd64.tar.gz | tar xz
sudo mv alaala /usr/local/bin/

# Linux (ARM64)
curl -L https://github.com/0xGurg/alaala/releases/latest/download/alaala_linux_arm64.tar.gz | tar xz
sudo mv alaala /usr/local/bin/

Build from Source

git clone https://github.com/0xGurg/alaala.git
cd alaala
go build -o bin/alaala ./cmd/alaala
sudo mv bin/alaala /usr/local/bin/

Setup Weaviate (Required for Vector Search)

Using Docker (Recommended)

# Start Weaviate container
docker run -d \
  --name weaviate \
  -p 8080:8080 \
  -e QUERY_DEFAULTS_LIMIT=25 \
  -e AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true \
  -e PERSISTENCE_DATA_PATH='/var/lib/weaviate' \
  weaviate/weaviate:latest

Or use embedded mode (experimental)

Set storage.mode: embedded in your config file.

Configuration

1. Initialize your first project:

cd /path/to/your/project
alaala init

This creates .alaala-project.json in your project directory.

1. Create configuration file:

The default config is created at ~/.alaala/config.yaml. Customize it:

storage:
  weaviate_url: http://localhost:8080
  sqlite_path: ~/.alaala/alaala.db

ai:
  provider: anthropic  # "anthropic", "openrouter", or "ollama"
  api_key: ${ANTHROPIC_API_KEY}  # or ${OPENROUTER_API_KEY}, not needed for ollama
  model: claude-3-5-sonnet-20241022  # provider-specific model name
  ollama_url: http://localhost:11434  # if using ollama
  openrouter_url: https://openrouter.ai/api/v1  # if using openrouter (optional)

embeddings:
  provider: local  # or "ollama" for local embeddings
  model: all-MiniLM-L6-v2  # or "nomic-embed-text" for ollama
  ollama_url: http://localhost:11434  # if using ollama

retrieval:
  max_memories: 5
  min_importance: 0.3
  include_graph_depth: 1

web:
  enabled: true
  port: 8766
  host: localhost

logging:
  level: info
  file: ~/.alaala/alaala.log

1. Set your AI provider:

Option A: Using Anthropic Claude (Cloud)

export ANTHROPIC_API_KEY="sk-ant-..."

Option B: Using OpenRouter (Multiple Models, Free Tier Available)

export OPENROUTER_API_KEY="sk-or-v1-..."
# Get your key from https://openrouter.ai
# Free models available: meta-llama/llama-3.1-8b-instruct:free

MCP Configuration

For Cursor

Add this to your Cursor settings (Cursor Settings > Features > Model Context Protocol):

{
  "mcpServers": {
    "alaala": {
      "command": "/usr/local/bin/alaala",
      "args": ["serve"],
      "env": {
        "ANTHROPIC_API_KEY": "your-api-key-here"
      }
    }
  }
}

For Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "alaala": {
      "command": "/usr/local/bin/alaala",
      "args": ["serve"]
    }
  }
}

Usage

Basic Commands

# Start MCP server (for Cursor/Claude Desktop)
alaala serve

# Start web UI
alaala web

# Initialize project
alaala init

# Show version
alaala version

Using with Cursor

Once configured, alaala runs automatically in the background. The AI can:

1. Automatic Context Injection - Relevant memories are injected at session start and updated on each prompt
2. Search Memories - Use the search_memories tool:

   Search memories about authentication
   

3. Save Important Insights - Use the save_memory tool:

   Remember that I prefer JWT tokens over session cookies
   

4. Curate Sessions - After a conversation, the AI can call curate_session to extract key insights

MCP Tools Available

Tool	Description	Example
search_memories	Search for relevant memories	Find memories about "database schema"
save_memory	Manually save a memory	Save "Project uses PostgreSQL 15"
curate_session	Extract memories from transcript	Analyze this conversation
list_projects	List all projects	Show all my projects

MCP Resources

Resource	Description
memory://session-context	Current session context with relevant memories
memory://project-memories	All memories for the current project

Architecture

alaala/
├── cmd/alaala/          # CLI entry point
├── internal/
│   ├── mcp/             # MCP protocol server
│   ├── memory/          # Core memory engine
│   ├── storage/         # SQLite + Weaviate
│   ├── ai/              # Claude AI client
│   ├── embeddings/      # Embedding service
│   └── web/             # Web UI (coming soon)
├── pkg/config/          # Configuration
└── examples/            # Example configs

How It Works

1. Session Start - alaala injects a session primer with:

   • Last session timestamp
   • Top relevant memories
   • Unresolved items

2. During Conversation - On each prompt:

   • Dynamic memory resource updates with relevant context
   • AI can search for specific memories
   • AI can save important insights

3. Session End - Optionally:

   • AI analyzes full transcript
   • Extracts meaningful memories with metadata
   • Creates relationship graph between memories

Memory Structure

Each memory contains:

{
  content: "User prefers functional programming style",
  importance: 0.9,
  semanticTags: ["preference", "coding-style"],
  contextType: "PREFERENCE",
  triggerPhrases: ["coding style", "how to write code"],
  questionTypes: ["what style does user prefer"],
  temporalRelevance: "persistent",
  actionRequired: false,
  reasoning: "Important for future code suggestions"
}

Current Limitations

What works:

• ✅ MCP protocol integration (Cursor, Claude Desktop)
• ✅ AI-powered memory curation (Claude, OpenRouter)
• ✅ SQLite storage with full metadata
• ✅ Session management and project isolation
• ✅ Homebrew distribution

With Ollama (optional):

• ✅ Real semantic embeddings (nomic-embed-text)
• ✅ Fully local and private AI
• ✅ No API costs

See docs/STATUS.md for detailed status.

Uninstallation

Using Homebrew

brew uninstall alaala
brew untap 0xGurg/distillery  # Optional

To also remove data:

rm -rf ~/.alaala
docker stop weaviate && docker rm weaviate  # If you set up Weaviate

Manual Uninstall

# Remove binary
sudo rm /usr/local/bin/alaala

# Remove data and config
rm -rf ~/.alaala

# Remove Weaviate container
docker stop weaviate && docker rm weaviate

Development

# Clone repository
git clone https://github.com/0xGurg/alaala.git
cd alaala

# Install dependencies
go mod download

# Run tests (coming soon)
go test ./...

# Build
go build -o bin/alaala ./cmd/alaala

# Run
./bin/alaala serve

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Acknowledgments

• Inspired by RLabs-Inc/memory
• Built with Weaviate for vector search
• Powered by Claude for AI curation
• Designed with Kanagawa color palette

Documentation

• Quick Start Guide - Get started in 5 minutes
• Contributing Guide - Help improve alaala
• Development Status - Current implementation status
• OpenRouter Testing - Test different AI models
• Homebrew Setup - Set up distillery tap
• Implementation Plan - Original design document

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made by George Pagarigan