Metadata-Version: 2.4
Name: ai-iq
Version: 5.0.0
Summary: Persistent context system for AI coding assistants
Author-email: Kobus Wentzel <kobie@pop.co.za>
License: MIT
Project-URL: Homepage, https://github.com/kobie3717/ai-iq
Project-URL: Repository, https://github.com/kobie3717/ai-iq
Project-URL: Issues, https://github.com/kobie3717/ai-iq/issues
Project-URL: Discord, https://discord.gg/Y2jCXNGgE
Keywords: ai,memory,context,sqlite,rag,semantic-search,knowledge-graph,llm,claude,coding-assistant
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Database
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: full
Requires-Dist: numpy>=1.21.0; extra == "full"
Requires-Dist: onnxruntime>=1.14.0; extra == "full"
Requires-Dist: tokenizers>=0.13.0; extra == "full"
Requires-Dist: sqlite-vec>=0.1.0; extra == "full"
Requires-Dist: huggingface-hub>=0.14.0; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: pylint>=3.0; extra == "dev"
Dynamic: license-file

# AI-IQ

**AI doesn't need knowledge — it needs relevant context, relative to each situation.**

![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue)
![SQLite 3.37+](https://img.shields.io/badge/sqlite-3.37%2B-blue)
![License MIT](https://img.shields.io/badge/license-MIT-green)
[![GitHub](https://img.shields.io/github/stars/kobie3717/ai-iq?style=social)](https://github.com/kobie3717/ai-iq)
[![Discord](https://img.shields.io/badge/Discord-Join%20Chat-5865F2?logo=discord&logoColor=white)](https://discord.gg/Y2jCXNGgE)

## Philosophy

AI-IQ is a persistent context system for AI coding assistants. Large language models already know everything — they've been trained on the entire internet. What they lack is YOUR context: your decisions, your architecture, your patterns, your mistakes, your project history. AI-IQ gives them exactly the right context at exactly the right time.

Not a knowledge base. Not a RAG pipeline. A context intelligence system that understands what's relevant to each situation through hybrid search (keyword + semantic), graph intelligence, and automatic decay of stale information.

## What's New in v5

**Major upgrades** from previous versions:

- **Self-Learning Feedback Loop (Phase 6)** - Memory system learns from usage and improves over time
- **Run Tracking (Phase 5)** - Structured workflow tracking with steps, timing, and outcomes
- **Provenance System (Phase 6)** - Track memory derivation with `--derived-from`, `--citations`, `--reasoning`
- **Next Actions** - Smart suggestions for what needs attention (expiring memories, conflicts, stale items)
- **Enhanced Graph** - Spreading activation, auto-linking, OpenClaw import
- **Improved Hybrid Search** - Better RRF fusion, graph-aware semantic search
- **Configurable Paths** - Environment variables for all paths, no hardcoded values
- **Production Tested** - Managing 100+ memories across 7 real-world projects

## Core Features

AI-IQ gives your AI assistant persistent, searchable context that survives across sessions:

- **Persistent context across sessions** - SQLite-backed storage that never forgets
- **Hybrid search** - Combines keyword (FTS5), semantic embeddings, and graph traversal with RRF fusion
- **Self-learning feedback** - Tracks which memories are useful, boosts good ones, prunes noise automatically
- **Smart deduplication** - Blocks duplicates automatically, warns on similar entries
- **Graph intelligence** - Entities, relationships, facts, and spreading activation for context discovery
- **Automated hooks** - Auto-captures errors, generates snapshots, logs search feedback
- **Cross-tool sync** - Share context between Claude Code, OpenClaw, and other AI tools
- **Zero config, no cloud services** - No API keys, 100% local and private

## How It Compares

| Feature | AI-IQ | .claude/memory | Cursor Rules | Custom RAG |
|---------|-------|----------------|--------------|------------|
| Persists across sessions | ✅ | ✅ | ✅ | ✅ |
| Semantic search | ✅ | ❌ | ❌ | ✅ |
| Graph relationships | ✅ | ❌ | ❌ | ❌ |
| Auto error capture | ✅ | ❌ | ❌ | ❌ |
| Dream consolidation | ✅ | ❌ | ❌ | ❌ |
| Decay & expiry | ✅ | ❌ | ❌ | ❌ |
| Zero dependencies | ✅ | ✅ | ✅ | ❌ |
| Works with any AI tool | ✅ | Claude only | Cursor only | Varies |

## Quick Start

Get up and running in 60 seconds:

```bash
# Option 1: Install from PyPI (when published)
pip install ai-iq

# Option 2: Install from source
git clone https://github.com/kobie3717/ai-iq.git
cd ai-iq
pip install -e .

# Add your first memory
memory-tool add learning "React app uses Redux for state management" --project MyApp

# Search for it
memory-tool search "redux"
# Output: 1 result found
#   [1] learning | React app uses Redux for state management | MyApp

# List all memories
memory-tool list
# Output: 1 active memory

# View statistics
memory-tool stats
# Output: Memories: 1 active | Projects: 1 | Categories: learning (1)
```

See [INSTALLATION.md](INSTALLATION.md) for Claude Code integration and automation setup.

## Features

### 1. Hybrid Search (FTS + Semantic + RRF)

Combines three search strategies with Reciprocal Rank Fusion:

- **Keyword search** - Fast FTS5 full-text search
- **Semantic search** - all-MiniLM-L6-v2 embeddings (384-dim) via sqlite-vec
- **Graph traversal** - Spreading activation across entity relationships

```bash
memory-tool search "authentication flow"        # Hybrid (default)
memory-tool search "auth" --semantic            # Semantic-only
memory-tool search "jwt token" --keyword        # FTS-only
```

### 2. Graph Intelligence

Build a knowledge graph of entities (people, projects, tools, concepts) with relationships and facts.

```bash
# Add entities
memory-tool graph add project WhatsAuction "Real-time auction platform"
memory-tool graph add tool PostgreSQL "Primary database"

# Create relationships
memory-tool graph rel WhatsAuction uses PostgreSQL

# Set facts
memory-tool graph fact PostgreSQL version "14.5"

# Spreading activation (find related context)
memory-tool graph spread WhatsAuction --depth 2
```

### 3. Smart Ingestion with Conflict Detection

Automatically detects duplicates and conflicts using similarity scoring:

- **> 85% similar** - Blocks as duplicate
- **65-85% similar** - Warns and suggests merge/update
- **< 65% similar** - Adds as new memory

```bash
memory-tool conflicts                    # Find potential duplicates
memory-tool merge <id1> <id2>           # Merge similar memories
memory-tool supersede <old_id> <new_id> # Mark as superseded
```

### 4. Self-Learning Feedback Loop

The memory system learns from your usage and improves over time:

- **Tracks which memories are useful** - Every search logs which results you actually use
- **Boosts high-value memories** - >80% hit rate over 10+ searches → priority +1
- **Decays low-value memories** - <20% hit rate over 10+ searches → priority -1
- **Flags noise** - Retrieved 20+ times but never used → marked as stale
- **Runs automatically** - Feedback learning happens during nightly `memory-tool dream`

```bash
memory-tool search-quality    # View hit rates and helpful/unhelpful memories
memory-tool hot              # Show most accessed memories (immune to decay)
memory-tool feedback <search_id> <used_ids>  # Manual feedback logging
```

**Result**: Search quality improves over time without manual curation. See [docs/FEEDBACK_QUICKSTART.md](docs/FEEDBACK_QUICKSTART.md).

### 5. Automated Hooks (Claude Code Integration)

- **PostToolUse hook** - Auto-captures failed Bash commands as error memories
- **Search feedback hook** - Auto-logs which search results you actually use
- **Stop hook** - Generates session snapshot from git/file changes, runs decay, exports MEMORY.md
- **Daily cron** - Maintenance at 3:17 AM (decay, garbage collection, backup, feedback learning)

### 6. Cross-Tool Sync (OpenClaw Bridge)

Bidirectional sync with OpenClaw's workspace format:

```bash
memory-tool sync          # Two-way sync
memory-tool sync-to       # Claude Code → OpenClaw
memory-tool sync-from     # OpenClaw → Claude Code
```

Share context seamlessly between AI assistants.

## Command Reference

### Core Operations

```bash
memory-tool add <category> "<content>" [options]
  --project <name>         # Associate with project
  --tags <tag1,tag2>       # Add tags (auto-tags also applied)
  --priority <0-10>        # Priority (default: 0)
  --related <id>           # Link to related memory
  --expires <YYYY-MM-DD>   # Auto-expire date
  --key <topic-key>        # Upsert key for topics

memory-tool update <id> "<new content>"
memory-tool delete <id>
memory-tool get <id>                      # Full detail view
memory-tool tag <id> <tag1,tag2>
memory-tool relate <id1> <id2> [type]
```

**Categories**: `project`, `decision`, `preference`, `error`, `learning`, `pending`, `architecture`, `workflow`, `contact`

### Search & Discovery

```bash
memory-tool search "<query>" [--full] [--semantic] [--keyword]
memory-tool list [--category X] [--project X] [--tag X] [--stale] [--expired]
memory-tool projects                      # Project summary
memory-tool topics                        # Generate topic .md files
memory-tool pending                       # Show TODO items
memory-tool conflicts                     # Find duplicates
```

### Graph Operations

```bash
memory-tool graph                         # Show summary
memory-tool graph add <type> <name> [summary]
memory-tool graph rel <from> <rel_type> <to> [note]
memory-tool graph fact <entity> <key> <value>
memory-tool graph get <name>
memory-tool graph list [type]
memory-tool graph delete <name>
memory-tool graph spread <name> [depth]   # Spreading activation
memory-tool graph link <memory_id> <entity>
memory-tool graph auto-link               # Auto-link all memories
memory-tool graph import-openclaw
memory-tool graph stats
```

**Entity types**: `person`, `project`, `org`, `feature`, `concept`, `tool`, `service`

**Relationship types**: `knows`, `works_on`, `owns`, `depends_on`, `built_by`, `uses`, `blocks`, `related_to`

### Session Management

```bash
memory-tool snapshot "<summary>" [--project X]
memory-tool auto-snapshot                 # Auto-detect from git/file changes
memory-tool snapshots [--limit N]
memory-tool detect-project                # Auto-detect from cwd
```

### Maintenance

```bash
memory-tool decay                         # Flag stale, deprioritize, expire
memory-tool stale                         # Review stale memories
memory-tool gc [days]                     # Garbage collect (default: 180 days)
memory-tool reindex                       # Rebuild vector embeddings
memory-tool stats                         # Full statistics
memory-tool backup                        # Manual backup
memory-tool restore <file>
```

### Cross-Tool Sync

```bash
memory-tool sync                          # Bidirectional sync
memory-tool sync-to                       # Export to OpenClaw
memory-tool sync-from                     # Import from OpenClaw
```

### Import/Export

```bash
memory-tool export [--project X]          # Regenerate MEMORY.md
memory-tool import-md <file>              # Import session summary markdown
memory-tool log-error <command> <error>   # Log failed command
```

### Run Tracking

Track structured workflows and agent runs with steps, outcomes, and timing:

```bash
# Start a new run
memory-tool run start "Fix user authentication bug" --agent claude --project MyApp

# Add steps as you work
memory-tool run step 1 "Identified issue in JWT validation"
memory-tool run step 1 "Updated auth middleware"  
memory-tool run step 1 "Added unit tests"

# Complete the run
memory-tool run complete 1 "Fixed auth bug, all tests passing"

# List runs
memory-tool run list                      # Recent runs
memory-tool run list --status running    # Active runs only
memory-tool run list --project MyApp --limit 20

# View detailed run information
memory-tool run show 1                   # Full run details with all steps

# Manage runs
memory-tool run cancel 2                 # Cancel a run
memory-tool run fail 3 "Unable to reproduce bug" # Mark as failed
```

**Run statuses**: `running`, `completed`, `failed`, `cancelled`

**Use cases**:
- Track multi-step debugging sessions
- Document feature implementation workflows  
- Monitor agent task progress
- Capture development decision trails
- Generate workflow reports for team reviews

## Integration

### Claude Code

See [INSTALLATION.md](INSTALLATION.md) for full setup instructions.

1. Install hooks in `~/.claude/settings.json`:

```json
{
  "hooks": {
    "PostToolUse": "~/.claude/projects/-root/memory/error-hook.sh",
    "Stop": "~/.claude/projects/-root/memory/session-hook.sh"
  }
}
```

2. Add cron job for daily maintenance:

```bash
17 3 * * * /root/.claude/projects/-root/memory/daily-maintenance.sh >> /root/.claude/projects/-root/memory/cron.log 2>&1
```

3. The system auto-loads `MEMORY.md` at session start via project instructions.

### Other AI Tools

For generic integration:

1. Export memories to markdown: `memory-tool export --project YourProject`
2. Include `MEMORY.md` in your AI tool's context
3. Use `memory-tool add` to capture learnings during sessions
4. Use `memory-tool auto-snapshot` to summarize sessions

## Architecture

**Database**: SQLite 3.37+ with extensions
- **memories** - Core memory storage
- **memories_fts** - FTS5 full-text search index
- **memory_vec** - sqlite-vec vector embeddings (384-dim)
- **memory_relations** - Bidirectional memory links
- **session_snapshots** - Session summaries
- **runs** - Structured workflow/task tracking with steps and timing
- **graph_entities** - Knowledge graph nodes
- **graph_relationships** - Knowledge graph edges
- **graph_facts** - Entity key-value metadata

**Hybrid Search**: RRF fusion (k=60) of keyword + semantic + graph results

**Embedding Model**: all-MiniLM-L6-v2 (ONNX, 384 dimensions)

**Auto-Tagging**: Content analysis detects keywords (pm2, nginx, react, auth, etc.)

**Decay System**:
- Pending items stale after 30 days
- General memories stale after 90 days
- Priority decreases after 60 days without access
- Expired memories auto-deactivate

See [ARCHITECTURE.md](ARCHITECTURE.md) for technical details.

## Comparison

| Feature | AI-IQ | Mem0 | Engram | LedgerMind |
|---------|-------|------|---------|------------|
| Self-hosted | ✅ | ❌ (cloud) | ✅ | ✅ |
| Zero config | ✅ | ❌ | ✅ | ❌ |
| Hybrid search | ✅ | ✅ | ❌ | ❌ |
| Knowledge graph | ✅ | ❌ | ❌ | ❌ |
| Vector search | ✅ (optional) | ✅ | ✅ | ❌ |
| Auto-hooks | ✅ | ❌ | ❌ | ❌ |
| Cross-tool sync | ✅ | ❌ | ❌ | ❌ |
| Privacy | 100% local | Cloud API | 100% local | 100% local |

## Requirements

**Core** (zero dependencies):
- Python 3.8+
- SQLite 3.37+ (with FTS5)

**Optional** (for semantic search):
```bash
pip install -r optional-requirements.txt
```
- numpy >= 1.21.0
- onnxruntime >= 1.14.0
- tokenizers >= 0.13.0
- sqlite-vec >= 0.1.0
- huggingface-hub >= 0.14.0

Semantic search downloads all-MiniLM-L6-v2 model (~90MB) on first use.

## Project Status

**Active development.** Used in production for multi-project AI development workflows.

Real-world stats: 100+ memories, 7 projects, 17 entities, 21 relationships, 109 embeddings, zero data loss over 6 months of daily use.

## Credits

Inspired by research on 25+ open-source memory systems:

- **Engram** - Temporal decay and graph-based memory
- **LedgerMind** - Sequential memory with branching
- **Vestige** - Semantic clustering and decay
- **OpenClaw** - Multi-tool workspace sync
- **Sediment** - Layered memory architecture

Built for real-world use with Claude Code in production environments.

## License

MIT License - see [LICENSE](LICENSE)

## Community

Join our Discord for help, discussions, and sharing workflows:

- **Discord:** [https://discord.gg/Y2jCXNGgE](https://discord.gg/Y2jCXNGgE)

## Contributing

Issues and pull requests welcome. See [ARCHITECTURE.md](ARCHITECTURE.md) for implementation details.

---

**Give your AI the context it needs, when it needs it.**
