Alaz

Long-term memory for AI coding assistants.

---

The Problem

AI coding assistants forget everything between sessions. Every new conversation starts from zero — you re-explain your stack, repeat your preferences, and watch the assistant rediscover things you solved last week.

The Solution

Alaz gives your AI assistant a persistent memory. It runs as a background server and does two things:

1. Learns automatically. When a coding session ends, Alaz reads the transcript and extracts what matters — patterns you use, decisions you made, bugs you hit, workflows that work.

2. Remembers automatically. When a new session starts, Alaz injects the most relevant context — unresolved issues, proven procedures, your preferences — so the assistant picks up where you left off.

Everything is searchable, versioned, and gets smarter over time. If you told your assistant something once, you never need to tell it again.

How It Works

Session ends → Alaz reads the transcript
                 → Extracts patterns, decisions, errors, procedures
                 → Detects contradictions with existing knowledge
                 → Builds a knowledge graph
                 → Embeds everything for semantic search

Session starts → Alaz injects relevant context
                   → Unresolved bugs from last time
                   → Your coding conventions
                   → Proven workflows for the current project
                   → Insights from your other projects

What It Remembers

Type	Example
Preferences	"Always use Bun instead of npm"
Facts	"Database runs on port 5437"
Patterns	Error handling pattern used across 3 projects
Procedures	Step-by-step deploy workflow (with success rate)
Decisions	"Chose SQLx over Diesel because of async support"
Episodes	"Fixed the auth bug by adding token refresh"

Quick Start

Prerequisites

• Rust (2024 edition)
• Docker
• Ollama with qwen3-embedding:8b

Setup

# Start PostgreSQL + Qdrant
docker compose up -d

# Pull the embedding model
ollama pull qwen3-embedding:8b

# Configure
cp .env.example .env
# Edit .env — at minimum set JWT_SECRET

# Run migrations and start
cargo run -- migrate
cargo run -- serve

Create an API Key

cargo run -- owner create --username admin
cargo run -- apikey create --owner <OWNER_ID>
# Save this key — it's shown only once

Connect to Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "alaz": {
      "type": "streamableHttp",
      "url": "http://localhost:3456/mcp",
      "headers": { "X-API-Key": "<your-api-key>" }
    }
  },
  "hooks": {
    "SessionStart": [{ "type": "command", "command": "alaz hook start", "timeout": 10 }],
    "Stop": [{ "type": "command", "command": "alaz hook stop", "timeout": 120 }]
  }
}

That's it. Alaz starts learning from your sessions and injecting context into new ones.

---

Under the Hood

Search

When you or your assistant search for something, Alaz doesn't just do a keyword match. It runs 6 different retrieval strategies in parallel and merges the results:

Signal	What it does
Full-text search	PostgreSQL tsvector — fast keyword matching
Dense vector	4096-dim semantic similarity via Qdrant
ColBERT	Token-level matching for precise multi-word queries
Graph expansion	Finds related knowledge through the knowledge graph
RAPTOR	Searches hierarchical concept clusters
Memory decay	Boosts recently accessed, frequently used items

Results are fused, then optionally reranked by a cross-encoder for higher precision.

Learning Pipeline

When a session ends, Alaz processes the transcript through 9 stages:

1. Parse and chunk the transcript (~24KB boundaries)
2. Extract patterns, episodes, procedures, and memories via LLM
3. Deduplicate against existing knowledge
4. Detect and resolve contradictions
5. Embed for semantic search
6. Enrich the knowledge graph
7. Promote patterns found across 3+ projects to global scope
8. Generate a session reflection
9. Mine tool usage sequences

Architecture

Single Rust binary, 9 internal crates. Connects to PostgreSQL (structured data + full-text search), Qdrant (vector search), and Ollama (embeddings).

crates/
├── alaz-core       Types, errors, config, circuit breaker
├── alaz-db         PostgreSQL via SQLx, migrations, repositories
├── alaz-vector     Qdrant — dense + ColBERT vector operations
├── alaz-graph      Knowledge graph, causal chains, cross-project promotion
├── alaz-intel      LLM client, embeddings, learning pipeline, RAPTOR
├── alaz-search     6-signal hybrid search, fusion, reranking
├── alaz-auth       JWT, API keys, Argon2 hashing, AES-256-GCM vault
├── alaz-server     Axum HTTP server + MCP protocol
└── alaz-cli        CLI entry point

Resilience

Every external service has a circuit breaker. If something goes down, Alaz degrades gracefully:

Service Down	What Happens
Qdrant	Text search + graph + RAPTOR still work
Ollama	Embeddings queue and retry automatically
Reranker	Returns results without reranking
LLM API	Learning pipeline queues for later

MCP Tools

38 tools available via MCP protocol

Knowledge: save, get, search, hybrid_search, list, update, delete, similar, cross_project, supersede

Graph: relate, unrelate, relations, graph_explore

Memory: episodes, procedures, core_memory, cue_search, episode_chain, episode_link

Sessions: sessions, reflections, create_reflection, reflection_insights, timeline

Infrastructure: checkpoint_save, checkpoint_list, checkpoint_restore, raptor_rebuild, raptor_status, compact_restore, context_budget, optimize_context, search_feedback

Vault: vault_store, vault_get, vault_list, vault_delete

Configuration

All settings via environment variables. Copy .env.example and adjust.

Variable	Required	Description
DATABASE_URL	Yes	PostgreSQL connection string
JWT_SECRET	Yes	Secret for JWT signing
ZHIPUAI_API_KEY	For learning	LLM API key for knowledge extraction

See .env.example for all options and defaults.

License

MIT