Aivectormemory

🌐 简体中文 | 繁體中文 | English | Español | Deutsch | Français | 日本語

<p align="center"> <img src="docs/logo.png" alt="AIVectorMemory Logo" width="200"> </p> <p align="center"> <img src="docs/image.png" alt="AI Vector Memory Architecture" width="100%"> </p> <h1 align="center">AIVectorMemory</h1> <p align="center"> <strong>Give your AI coding assistant a memory — Cross-session persistent memory MCP Server</strong> </p> <p align="center"> <a href="https://pypi.org/project/aivectormemory/"><img src="https://img.shields.io/pypi/v/aivectormemory?color=blue&label=PyPI" alt="PyPI"></a> <a href="https://pypi.org/project/aivectormemory/"><img src="https://img.shields.io/pypi/pyversions/aivectormemory" alt="Python"></a> <a href="https://github.com/Edlineas/aivectormemory/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache_2.0-green" alt="License"></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-purple" alt="MCP"></a> </p>

---

Still using CLAUDE.md / MEMORY.md as memory? This Markdown-file memory approach has fatal flaws: the file keeps growing, injecting everything into every session and burning massive tokens; content only supports keyword matching — search "database timeout" and you won't find "MySQL connection pool pitfall"; sharing one file across projects causes cross-contamination; there's no task tracking, so dev progress lives entirely in your head; not to mention the 200-line truncation, manual maintenance, and inability to deduplicate or merge.

AIVectorMemory is a fundamentally different approach. Local vector database storage with semantic search for precise recall (matches even when wording differs), on-demand retrieval that loads only relevant memories (token usage drops 50%+), automatic multi-project isolation with zero interference, and built-in issue tracking + task management that lets AI fully automate your dev workflow. All data is permanently stored on your machine — zero cloud dependency, never lost when switching sessions or IDEs.

✨ Core Features

| Feature | Description | |---------|-------------| | 🧠 Cross-Session Memory | Your AI finally remembers your project — pitfalls, decisions, conventions all persist across sessions | | 🔍 Hybrid Smart Search | FTS5 full-text + vector semantic dual-path search, RRF fusion ranking + composite scoring (recency × frequency × importance), far more precise than pure vector search | | 🐛 Issue Tracking | Built-in Issue Tracker — discover → investigate → fix → archive, full lifecycle. AI manages bugs automatically | | 📋 Task Management | Spec → task breakdown → nested subtasks → status sync → linked archival. AI drives the complete dev workflow | | 🚦 Session State | Blocking management + breakpoint resume + progress tracking, seamless handoff across sessions and context compaction | | 🪝 Hooks + Steering | Auto-inject workflow rules + behavior guard hooks, consistent AI behavior guaranteed — no need to repeat instructions | | 🧬 Memory Evolution | Contradiction detection auto-supersedes stale knowledge + short-term → long-term auto-promotion + 90-day auto-archive, self-evolving memory | | 📊 Desktop App + Web Dashboard | Native desktop app (macOS/Windows/Linux) + Web dashboard, 3D vector network reveals knowledge connections at a glance | | 💰 Save 50%+ Tokens | Stop copy-pasting project context every conversation. Semantic retrieval on demand, no more bulk injection | | 🏠 Fully Local | Zero cloud dependency. ONNX local inference, no API Key, data never leaves your machine | | 🔌 11 IDEs Covered | Cursor / Kiro / Claude Code / Windsurf / VSCode / Copilot / OpenCode / Trae / Codex / Antigravity / OpenClaw — one-click install & uninstall | | 📁 Multi-Project Isolation | One DB for all projects, auto-isolated with zero interference, seamless project switching | | 🔄 Smart Dedup | Similarity > 0.95 auto-merges updates, keeping your memory store clean — never gets messy over time | | 🌐 7 Languages | 简体中文 / 繁體中文 / English / Español / Deutsch / Français / 日本語, full-stack i18n for dashboard + Steering rules |

<p align="center"> QQ群：1085682431 &nbsp;|&nbsp; 微信：changhuibiz<br> 共同参与项目开发加QQ群或微信交流 </p> <p align="center"> <img src="docs/003.png" alt="Login" width="100%"> <br> <em>Login</em> </p> <p align="center"> <img src="docs/001.png" alt="Project Selection" width="100%"> <br> <em>Project Selection</em> </p> <p align="center"> <img src="docs/002.png" alt="Overview & Vector Network" width="100%"> <br> <em>Overview & Vector Network</em> </p>

🏗️ Architecture

┌─────────────────────────────────────────────────┐
│                   AI IDE                         │
│  OpenCode / Codex / Claude Code / Cursor / ...  │
└──────────────────────┬──────────────────────────┘
                       │ MCP Protocol (stdio)
┌──────────────────────▼──────────────────────────┐
│              AIVectorMemory Server               │
│                                                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│  │ remember │ │  recall   │ │   auto_save      │ │
│  │ forget   │ │  task     │ │   status/track   │ │
│  └────┬─────┘ └────┬─────┘ └───────┬──────────┘ │
│       │            │               │             │
│  ┌────▼────────────▼───────────────▼──────────┐  │
│  │         Embedding Engine (ONNX)            │  │
│  │      intfloat/multilingual-e5-small        │  │
│  └────────────────────┬───────────────────────┘  │
│                       │                          │
│  ┌────────────────────▼───────────────────────┐  │
│  │     SQLite + sqlite-vec (Vector Index)     │  │
│  │     ~/.aivectormemory/memory.db            │  │
│  └────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────┘

🚀 Quick Start

Option 1: pip install (Recommended)

# Install
pip install aivectormemory

# Upgrade to latest version
pip install --upgrade aivectormemory

# Navigate to your project directory, one-click IDE setup
cd /path/to/your/project
run install

run install interactively guides you to select your IDE, auto-generating MCP config, Steering rules, and Hooks — no manual setup needed.

macOS users note:

• If you get externally-managed-environment error, add --break-system-packages
• If you get enable_load_extension error, your Python doesn't support SQLite extension loading (macOS built-in Python and python.org installers don't support it). Use Homebrew Python instead:

  brew install python
  /opt/homebrew/bin/python3 -m pip install aivectormemory
  

Option 2: uvx (zero install)

No pip install needed, run directly:

cd /path/to/your/project
uvx aivectormemory install

Requires uv to be installed. uvx auto-downloads and runs the package — no manual installation needed.

Option 3: Manual configuration

{
  "mcpServers": {
    "aivectormemory": {
      "command": "run",
      "args": ["--project-dir", "/path/to/your/project"]
    }
  }
}

<details> <summary>📍 IDE Configuration File Locations</summary>

| IDE | Config Path | |-----|------------| | Kiro | .kiro/settings/mcp.json | | Cursor | .cursor/mcp.json | | Claude Code | .mcp.json | | Windsurf | .windsurf/mcp.json | | VSCode | .vscode/mcp.json | | Trae | .trae/mcp.json | | OpenCode | opencode.json | | Codex | .codex/config.toml |

</details>

For Codex, use project-scoped TOML instead of JSON:

[mcp_servers.aivectormemory]
command = "run"
args = ["--project-dir", "/path/to/your/project"]

Codex only loads project-scoped .codex/config.toml after the repository is marked as a trusted project.

🛠️ 8 MCP Tools

remember — Store a memory

content (string, required)   Memory content in Markdown format
tags    (string[], required)  Tags, e.g. ["pitfall", "python"]
scope   (string)              "project" (default) / "user" (cross-project)

Similarity > 0.95 auto-updates existing memory, no duplicates.

recall — Semantic search

query   (string)     Semantic search keywords
tags    (string[])   Exact tag filter
scope   (string)     "project" / "user" / "all"
top_k   (integer)    Number of results, default 5

Vector similarity matching — finds related memories even with different wording.

forget — Delete memories

memory_id  (string)     Single ID
memory_ids (string[])   Batch IDs

status — Session state

state (object, optional)   Omit to read, pass to update
  is_blocked, block_reason, current_task,
  next_step, progress[], recent_changes[], pending[]

Maintains work progress across sessions, auto-restores context in new sessions.

track — Issue tracking

action   (string)   "create" / "update" / "archive" / "list"
title    (string)   Issue title
issue_id (integer)  Issue ID
status   (string)   "pending" / "in_progress" / "completed"
content  (string)   Investigation content

task — Task management

action     (string, required)  "batch_create" / "update" / "list" / "delete" / "archive"
feature_id (string)            Linked feature identifier (required for list)
tasks      (array)             Task list (batch_create, supports subtasks)
task_id    (integer)           Task ID (update)
status     (string)            "pending" / "in_progress" / "completed" / "skipped"

Links to spec docs via feature_id. Update auto-syncs tasks.md checkboxes and linked issue status.

readme — README generation

action   (string)    "generate" (default) / "diff" (compare differences)
lang     (string)    Language: en / zh-TW / ja / de / fr / es
sections (string[])  Specify sections: header / tools / deps
`