AI-Memory is a persistent context layer designed to give your agents institutional memory. By bridging LLMs with a high-performance vector database (Qdrant), this framework ensures your agents remember architectural decisions, project rules, and past interactions across every session.

Explore the Docs | Report a Bug | Request a Feature

• 💾 Long-Term Persistence: Stop re-explaining your codebase. Agents retrieve past context automatically at session start.
• 📂 Structured BMAD Integration: Purpose-built for BMAD workflows and multi-agent "Party Mode."
• 🔍 Semantic Retrieval: Uses vector embeddings to find relevant memories based on intent, not just keywords.
• ⚖️ Decision Tracking: Automatically captures "lessons learned" and integration rules during the dev cycle.

• 🗂️ Three Specialized Collections: code-patterns (HOW), conventions (WHAT), discussions (WHY)
• 🎯 17 Memory Types: Precise categorization for implementation, errors, decisions, Jira issues, and more
• ⚡ 6 Automatic Triggers: Smart context injection when you need it most
• 🔍 Intent Detection: Automatically routes queries to the right collection
• 💬 Conversation Memory: Turn-by-turn capture with post-compaction context continuity
• 🔁 Cascading Search: Falls back across collections for comprehensive results
• 📊 Monitoring: Prometheus metrics + Grafana dashboards
• 🛡️ Graceful Degradation: Works even when services are temporarily unavailable
• 👥 Multi-Project Isolation: group_id filtering keeps projects separate

New here? Jump to Quick Start to get running in 5 minutes.

Bring your work context into semantic memory with built-in Jira Cloud support:

• Semantic Search: Search Jira issues and comments by meaning, not just keywords
• Full & Incremental Sync: Initial backfill or fast daily updates via JQL
• ADF Conversion: Atlassian Document Format → plain text for accurate embeddings
• Rich Filtering: Search by project, issue type, status, priority, or author
• Issue Lookup: Retrieve complete issue context (issue + all comments, chronologically)
• Dedicated Collection: jira-data collection keeps Jira content separate from code memory
• Tenant Isolation: group_id based on Jira instance hostname prevents cross-instance leakage
• Two Skills: /jira-sync for synchronization, /search-jira for semantic search

See docs/JIRA-INTEGRATION.md for setup and usage guide.

When you ask "how should I..." or "what's the best way to...", AI-Memory's best-practices-researcher activates:

1. Search Local Knowledge - Checks the conventions collection first
2. Web Research - Searches 2024-2026 sources if needed
3. Save Findings - Stores to oversight/knowledge/best-practices/BP-XXX.md
4. Database Storage - Adds to Qdrant for future retrieval
5. Skill Evaluation - Determines if findings warrant a reusable skill

When research reveals a repeatable process, the skill-creator agent can generate a Claude Code skill:

User: "Research best practices for writing commit messages"
→ Best Practices Researcher finds patterns
→ Evaluates: "This is a repeatable process with clear steps"
→ User confirms: "Yes, create a skill"
→ Skill Creator generates .claude/skills/writing-commits/SKILL.md

The Result: Your AI agents continuously discover and codify knowledge into reusable skills.

Memory + Oversight = Reliable AI

Works with BMAD Method — Enhances BMAD workflows with persistent memory, but works standalone with any Claude Code project.

Claude Code Session
    ├── SessionStart Hooks (resume|compact) → Context injection on session resume and post-compaction
    ├── UserPromptSubmit Hooks → Unified keyword trigger (decisions/best practices/session history)
    ├── PreToolUse Hooks → Smart triggers (new file/first edit conventions)
    ├── PostToolUse Hooks → Capture code patterns + error detection
    ├── PreCompact Hook → Save conversation before compaction
    └── Stop Hook → Capture agent responses

Python Core (src/memory/)
    ├── config.py         → Environment configuration
    ├── storage.py        → Qdrant CRUD operations
    ├── search.py         → Semantic search + cascading
    ├── intent.py         → Intent detection + routing
    ├── triggers.py       → Automatic trigger configuration
    ├── embeddings.py     → Jina AI embeddings (768d)
    └── deduplication.py  → Hash + similarity dedup

Docker Services
    ├── Qdrant (port 26350)
    ├── Embedding Service (port 28080)
    ├── Classifier Worker (LLM reclassification)
    ├── Streamlit Dashboard (port 28501)
    └── Monitoring Stack (--profile monitoring)
        ├── Prometheus (port 29090)
        ├── Pushgateway (port 29091)
        └── Grafana (port 23000)

Note: The jira-data collection is conditional — it is only created when Jira sync is enabled (JIRA_SYNC_ENABLED=true).

The memory system automatically retrieves relevant context:

• Error Detection: When a command fails, retrieves past error fixes
• New File Creation: Retrieves naming conventions and structure patterns
• First Edit: Retrieves file-specific patterns on first modification
• Decision Keywords: "Why did we..." triggers decision memory retrieval
• Best Practices Keywords: "How should I..." triggers convention retrieval
• Session History Keywords: "What have we done..." triggers session summary retrieval

The following keywords automatically activate memory retrieval when detected in your prompts:

Note: Keywords are case-insensitive. Only structured patterns trigger retrieval to avoid false positives on casual conversation.

The optional LLM Classifier automatically reclassifies captured memories into more precise types:

• Rule-based first: Fast pattern matching (free, <10ms)
• LLM fallback: AI classification when rules don't match
• Provider chain: Primary provider with automatic fallback

Quick Setup:

# Configure in docker/.env
MEMORY_CLASSIFIER_ENABLED=true
MEMORY_CLASSIFIER_PRIMARY_PROVIDER=ollama    # or: openrouter, claude, openai
MEMORY_CLASSIFIER_FALLBACK_PROVIDERS=openrouter

# For Ollama (free, local)
OLLAMA_BASE_URL=http://host.docker.internal:11434
OLLAMA_MODEL=sam860/LFM2:2.6b

# For OpenRouter (free tier available)
OPENROUTER_API_KEY=sk-or-v1-your-key
OPENROUTER_MODEL=google/gemma-2-9b-it:free

See docs/llm-classifier.md for complete setup guide, provider options, and troubleshooting.

# Core services (Qdrant + Embedding)
docker compose -f docker/docker-compose.yml up -d

# With monitoring (adds Prometheus, Grafana, Pushgateway)
docker compose -f docker/docker-compose.yml --profile monitoring up -d

# Check Qdrant (port 26350)
curl http://localhost:26350/health

# Check Embedding Service (port 28080)
curl http://localhost:28080/health

# Check Grafana (port 23000) - if monitoring enabled
open http://localhost:23000  # admin/admin

./scripts/install.sh /path/to/your-project

# With convention seeding (recommended)
SEED_BEST_PRACTICES=true ./scripts/install.sh /path/to/your-project

Expected Output:

═══════════════════════════════════════════════════════════
  AI Memory Module Health Check
═══════════════════════════════════════════════════════════

[1/3] Checking Qdrant (localhost:26350)...
  ✅ Qdrant is healthy

[2/3] Checking Embedding Service (localhost:28080)...
  ✅ Embedding service is healthy

[3/3] Checking Monitoring API (localhost:28000)...
  ✅ Monitoring API is healthy

═══════════════════════════════════════════════════════════
  All Services Healthy ✅
═══════════════════════════════════════════════════════════

• Python 3.10+ (3.11+ required for AsyncSDKWrapper)
• Docker 20.10+ (for Qdrant + embedding service)
• Claude Code (target project where memory will be installed)

See INSTALL.md for detailed installation instructions including:

• System requirements with version compatibility
• Step-by-step installation for macOS, Linux, and Windows (WSL2)
• Automated installer and manual installation methods
• Post-installation verification
• Configuration options
• Uninstallation procedures

All services use 2XXXX prefix to avoid conflicts:

Jira Cloud Integration (Optional):

See docs/JIRA-INTEGRATION.md for complete Jira setup guide.

Override Example:

export QDRANT_PORT=16333  # Use custom port
export MEMORY_LOG_LEVEL=DEBUG  # Enable verbose logging

Memory capture happens automatically via Claude Code hooks:

1. SessionStart (resume/compact only): Injects relevant memories when resuming a session or after context compaction
2. PostToolUse: Captures code patterns (Write/Edit/NotebookEdit tools) in background (<500ms)
3. PreCompact: Saves session summary before context compaction (auto or manual /compact)
4. Stop: Optional per-response cleanup

No manual intervention required - hooks handle everything.

The "Aha Moment": Claude remembers your previous sessions automatically. Start a new session and Claude will say "Welcome back! Last session we worked on..." without you reminding it.

Use slash commands for manual control:

# Check system status
/memory-status

# Manually save current session
/save-memory

# Search across all memories
/search-memory <query>

# Jira Cloud Integration (requires JIRA_SYNC_ENABLED=true)
/jira-sync              # Incremental sync from Jira
/jira-sync --full       # Full sync (all issues and comments)
/search-jira "query"    # Semantic search across Jira content
/search-jira --issue PROJ-42  # Lookup issue + all comments

See docs/HOOKS.md for hook documentation, docs/COMMANDS.md for commands, docs/llm-classifier.md for LLM classifier setup, and docs/JIRA-INTEGRATION.md for Jira integration guide.

The AsyncSDKWrapper provides full async/await support for building custom Agent SDK agents with persistent memory.

Features:

• Full async/await support compatible with Agent SDK
• Rate limiting with token bucket algorithm (Tier 1: 50 RPM, 30K TPM)
• Exponential backoff retry with jitter (3 retries: 1s, 2s, 4s ±20%)
• Automatic conversation capture to discussions collection
• Background storage (fire-and-forget pattern)
• Prometheus metrics integration

Basic Usage:

import asyncio
from src.memory import AsyncSDKWrapper

async def main():
    async with AsyncSDKWrapper(cwd="/path/to/project") as wrapper:
        # Send message with automatic rate limiting and retry
        result = await wrapper.send_message(
            prompt="What is async/await?",
            model="claude-sonnet-4-5-20250929",
            max_tokens=500
        )

        print(f"Response: {result['content']}")
        print(f"Session ID: {result['session_id']}")

asyncio.run(main())

Streaming Responses (Buffered):

Note: Current implementation buffers the full response for retry reliability. True progressive streaming planned for future release.

async with AsyncSDKWrapper(cwd="/path/to/project") as wrapper:
    async for chunk in wrapper.send_message_buffered(
        prompt="Explain Python async",
        model="claude-sonnet-4-5-20250929",
        max_tokens=800
    ):
        print(chunk, end='', flush=True)

Custom Rate Limits:

async with AsyncSDKWrapper(
    cwd="/path/to/project",
    requests_per_minute=100,   # Tier 2
    tokens_per_minute=100000   # Tier 2
) as wrapper:
    result = await wrapper.send_message("Hello!")

Examples:

• examples/async_sdk_basic.py - Basic async/await usage, context manager pattern, session ID logging, rate limiting demonstration
• examples/async_sdk_streaming.py - Streaming response handling (buffered), progressive chunk processing, retry behavior
• examples/async_sdk_rate_limiting.py - Custom rate limit configuration, queue depth/timeout settings, error handling for different API tiers

Configuration:

Set ANTHROPIC_API_KEY environment variable before using AsyncSDKWrapper:

export ANTHROPIC_API_KEY=sk-ant-api03-...

Rate Limiting:

The wrapper implements token bucket algorithm matching Anthropic's rate limits:

Circuit breaker protections:

• Max queue depth: 100 requests
• Queue timeout: 60 seconds
• Raises QueueTimeoutError or QueueDepthExceededError if exceeded

Retry Strategy:

Automatic exponential backoff retry (DEC-029):

• Max retries: 3
• Delays: 1s, 2s, 4s (with ±20% jitter)
• Retries on: 429 (rate limit), 529 (overload), network errors
• No retry on: 4xx client errors (except 429), auth failures
• Respects retry-after header when provided

Memory Capture:

All messages are automatically captured to the discussions collection:

• User messages → user_message type
• Agent responses → agent_response type
• Background storage (non-blocking)
• Session-based grouping with turn numbers

See src/memory/async_sdk_wrapper.py for complete API documentation.

For complete design rationale, see oversight/specs/tech-debt-035/phase-2-design.md.

Memories are automatically isolated by group_id (derived from project directory):

# Project A: group_id = "project-a"
# Project B: group_id = "project-b"
# Searches only return memories from current project

V2.0 Collection Isolation:

• code-patterns: Implementation patterns (per-project isolation)
• conventions: Coding standards and rules (shared across projects by default)
• discussions: Decisions, sessions, conversations (per-project isolation)

See TROUBLESHOOTING.md for comprehensive troubleshooting, including:

• Services won't start
• Health check failures
• Memories not captured
• Search not working
• Performance problems
• Data persistence issues

If hooks are misbehaving (e.g., after a failed install or upgrade), use the recovery script to scan and repair all project configurations:

# Dry-run: shows what would change (safe, no modifications)
python scripts/recover_hook_guards.py

# Apply fixes across all discovered projects
python scripts/recover_hook_guards.py --apply

# Scan only: list all discovered project settings.json files
python scripts/recover_hook_guards.py --scan

The recovery script automatically discovers projects via:

1. ~/.ai-memory/installed_projects.json manifest (primary)
2. Sibling directories of AI_MEMORY_INSTALL_DIR (fallback)
3. Common project paths (additional fallback)

It fixes: unguarded hook commands (BUG-066), broad SessionStart matchers (BUG-078), and other known configuration issues. Always run with dry-run first to review changes.

# Check all services
docker compose -f docker/docker-compose.yml ps

# Check logs
docker compose -f docker/docker-compose.yml logs

# Check health
python scripts/health-check.py

# Check ports
lsof -i :26350  # Qdrant
lsof -i :28080  # Embedding
lsof -i :28000  # Monitoring API

Symptom: docker compose up -d fails or services exit immediately

Solution:

1. Check port availability:

   lsof -i :26350  # Qdrant
   lsof -i :28080  # Embedding

2. Check Docker logs:

   docker compose -f docker/docker-compose.yml logs

3. Ensure Docker daemon is running:

   docker ps  # Should not error

Symptom: python scripts/health-check.py shows unhealthy services

Solution:

1. Check service status:

   docker compose -f docker/docker-compose.yml ps

2. Verify ports are accessible:

   curl http://localhost:26350/health  # Qdrant
   curl http://localhost:28080/health  # Embedding

3. Check logs for errors:

   docker compose -f docker/docker-compose.yml logs qdrant
   docker compose -f docker/docker-compose.yml logs embedding

Symptom: PostToolUse hook doesn't store memories

Solution:

1. Check hook configuration in .claude/settings.json:

   {
     "hooks": {
       "PostToolUse": [{
         "matcher": "Write|Edit",
         "hooks": [{"type": "command", "command": ".claude/hooks/scripts/post_tool_capture.py"}]
       }]
     }
   }

2. Verify hook script is executable:

   ls -la .claude/hooks/scripts/post_tool_capture.py
   chmod +x .claude/hooks/scripts/post_tool_capture.py

3. Check hook logs (if logging enabled):

   cat ~/.ai-memory/logs/hook.log

For more detailed troubleshooting, see TROUBLESHOOTING.md.

Access Grafana at http://localhost:23000 (admin/admin):

All metrics use aimemory_ prefix (BP-045 compliant):

See docs/MONITORING.md for complete monitoring guide and docs/prometheus-queries.md for query examples.

Protect your AI memories with built-in backup and restore scripts.

# Setup (one-time)
cd /path/to/ai-memory
python3 -m venv .venv && source .venv/bin/activate
pip install httpx

# Get your Qdrant API key
cat ~/.ai-memory/docker/.env | grep QDRANT_API_KEY
export QDRANT_API_KEY="your-key-here"

# Run backup
python scripts/backup_qdrant.py

Backups are stored in backups/ directory with timestamped folders containing:

• Collection snapshots (discussions, conventions, code-patterns)
• Configuration files
• Verification manifest

python scripts/restore_qdrant.py backups/2026-02-03_143052

See docs/BACKUP-RESTORE.md for complete instructions including troubleshooting.

Coming soon: Backup and restore scripts will be updated in the next version to support the jira-data collection, including Jira database backup and reinstall.

• Hook overhead: <500ms (PostToolUse forks to background)
• Embedding generation: <2s (pre-warmed Docker service)
• SessionStart context injection: <3s
• Deduplication check: <100ms

1. Enable monitoring profile for production use:

   docker compose -f docker/docker-compose.yml --profile monitoring up -d

2. Adjust batch size for large projects:

   export MEMORY_BATCH_SIZE=100  # Default: 50

3. Increase cache TTL for stable projects:

   export MEMORY_CACHE_TTL=3600  # Default: 1800 seconds

# Run all tests
pytest tests/

# Run specific test file
pytest tests/test_storage.py -v

# Run integration tests only
pytest tests/integration/ -v

ai-memory/
├── src/memory/          # Core Python modules
├── .claude/
│   ├── hooks/scripts/   # Hook implementations
│   └── skills/          # Skill definitions
├── docker/              # Docker Compose and service configs
├── scripts/             # Installation and management scripts
├── tests/               # pytest test suite
└── docs/                # Additional documentation

• Python (PEP 8 Strict): Files snake_case.py, Functions snake_case(), Classes PascalCase, Constants UPPER_SNAKE
• Qdrant Payload Fields: Always snake_case (content_hash, group_id, source_hook)
• Structured Logging: Use logger.info("event", extra={"key": "value"}), never f-strings
• Hook Exit Codes: 0 (success), 1 (non-blocking error), 2 (blocking error - rare)
• Graceful Degradation: All components must fail silently - Claude works without memory

See CONTRIBUTING.md for complete development setup and coding standards.

We welcome contributions! To contribute:

1. Fork the repository and create a feature branch
2. Follow coding conventions (see Development section above)
3. Write tests for all new functionality
4. Ensure all tests pass: pytest tests/
5. Update documentation if adding features
6. Submit a pull request with a clear description

See CONTRIBUTING.md for detailed development setup and pull request process.

MIT License - see LICENSE for details.

This documentation follows WCAG 2.2 Level AA accessibility standards (ISO/IEC 40500:2025):

• ✅ Proper heading hierarchy (h1 → h2 → h3)
• ✅ Descriptive link text (no "click here")
• ✅ Code blocks with language identifiers
• ✅ Tables with headers for screen readers
• ✅ Consistent bullet style (hyphens)
• ✅ ASCII art diagrams for universal compatibility

For accessibility concerns or suggestions, please open an issue.

Documentation Best Practices Applied (2026):

This README follows current best practices for technical documentation:

• Documentation as Code (Technical Documentation Best Practices)
• Markdown standards with consistent formatting (Markdown Best Practices)
• Essential sections per README standards (Make a README)
• Quick value communication (README Best Practices - Tilburg Science Hub)
• WCAG 2.2 accessibility compliance (W3C WCAG 2.2 as ISO Standard)