aivectormemory
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@aivectormemory remember we're using FastAPI for backend and PostgreSQL"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
๐ ็ฎไฝไธญๆ | ็น้ซไธญๆ | English | Espaรฑol | Deutsch | Franรงais | ๆฅๆฌ่ช
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 |
๐ Semantic Search | No need to recall exact wording โ search "database timeout" and find "MySQL connection pool issue" |
๐ฐ Save 50%+ Tokens | Stop copy-pasting project context every conversation. Semantic retrieval on demand, no more bulk injection |
๐ Task-Driven Dev | Issue tracking โ task breakdown โ status sync โ linked archival. AI manages the full dev workflow |
๐ Desktop App + Web Dashboard | Native desktop app (macOS/Windows/Linux) + Web dashboard, visual management for memories and tasks, 3D vector network reveals knowledge connections at a glance |
๐ Fully Local | Zero cloud dependency. ONNX local inference, no API Key, data never leaves your machine |
๐ All IDEs | Cursor / Kiro / Claude Code / Windsurf / VSCode / OpenCode / Trae โ one-click install, works out of the box |
๐ 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 |
Related MCP server: io.github.cdnsteve/sugar
๐๏ธ Architecture
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ AI IDE โ
โ OpenCode / Claude Code / Cursor / Kiro / ... โ
โโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 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 installrun 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-environmenterror, add--break-system-packagesIf you get
enable_load_extensionerror, 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 installRequires uv to be installed.
uvxauto-downloads and runs the package โ no manual installation needed.
Option 3: Manual configuration
{
"mcpServers": {
"aivectormemory": {
"command": "run",
"args": ["--project-dir", "/path/to/your/project"]
}
}
}IDE | Config Path |
Kiro |
|
Cursor |
|
Claude Code |
|
Windsurf |
|
VSCode |
|
Trae |
|
OpenCode |
|
๐ ๏ธ 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 5Vector similarity matching โ finds related memories even with different wording.
forget โ Delete memories
memory_id (string) Single ID
memory_ids (string[]) Batch IDsstatus โ 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 contenttask โ 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 / depsAuto-generates README content from TOOL_DEFINITIONS / pyproject.toml, multi-language support.
auto_save โ Auto save preferences
preferences (string[]) User-expressed technical preferences (fixed scope=user, cross-project)
extra_tags (string[]) Additional tagsAuto-extracts and stores user preferences at end of each conversation, smart dedup.
๐ Web Dashboard
run web --port 9080
run web --port 9080 --quiet # Suppress request logs
run web --port 9080 --quiet --daemon # Run in background (macOS/Linux)Visit http://localhost:9080 in your browser. Default username admin, password admin123 (can be changed in settings after first login).
Multi-project switching, memory browse/search/edit/delete/export/import
Semantic search (vector similarity matching)
One-click project data deletion
Session status, issue tracking
Tag management (rename, merge, batch delete)
Token authentication protection
3D vector memory network visualization
๐ Multi-language support (็ฎไฝไธญๆ / ็น้ซไธญๆ / English / Espaรฑol / Deutsch / Franรงais / ๆฅๆฌ่ช)
โก Pairing with Steering Rules
AIVectorMemory is the storage layer. Use Steering rules to tell AI when and how to call these tools.
Running run install auto-generates Steering rules and Hooks config โ no manual setup needed.
IDE | Steering Location | Hooks |
Kiro |
|
|
Cursor |
|
|
Claude Code |
|
|
Windsurf |
|
|
VSCode |
|
|
Trae |
| โ |
OpenCode |
|
|
# AIVectorMemory - Workflow Rules
## 1. New Session Startup (execute in order)
1. `recall` (tags: ["project-knowledge"], scope: "project", top_k: 100) load project knowledge
2. `recall` (tags: ["preference"], scope: "user", top_k: 20) load user preferences
3. `status` (no state param) read session state
4. Blocked โ report and wait; Not blocked โ enter processing flow
## 2. Message Processing Flow
- Step A: `status` read state, wait if blocked
- Step B: Classify message type (chat/correction/preference/code issue)
- Step C: `track create` record issue
- Step D: Investigate (`recall` pitfalls + read code + find root cause)
- Step E: Present plan to user, set blocked awaiting confirmation
- Step F: Modify code (`recall` pitfalls before changes)
- Step G: Run tests to verify
- Step H: Set blocked awaiting user verification
- Step I: User confirms โ `track archive` + clear block
## 3. Blocking Rules
Must `status({ is_blocked: true })` when proposing plans or awaiting verification.
Only clear after explicit user confirmation. Never self-clear.
## 4-9. Issue Tracking / Code Checks / Spec Task Mgmt / Memory Quality / Tool Reference / Dev Standards
(Full rules auto-generated by `run install`)Auto-save on session end removed. Dev workflow check (.kiro/hooks/dev-workflow-check.kiro.hook):
{
"enabled": true,
"name": "Dev Workflow Check",
"version": "1",
"when": { "type": "promptSubmit" },
"then": {
"type": "askAgent",
"prompt": "Core principles: verify before acting, no blind testing, only mark done after tests pass"
}
}๐จ๐ณ Users in China
The embedding model (~200MB) is auto-downloaded on first run. If slow:
export HF_ENDPOINT=https://hf-mirror.comOr add env to MCP config:
{
"env": { "HF_ENDPOINT": "https://hf-mirror.com" }
}๐ฆ Tech Stack
Component | Technology |
Runtime | Python >= 3.10 |
Vector DB | SQLite + sqlite-vec |
Embedding | ONNX Runtime + intfloat/multilingual-e5-small |
Tokenizer | HuggingFace Tokenizers |
Protocol | Model Context Protocol (MCP) |
Web | Native HTTPServer + Vanilla JS |
๐ Changelog
v1.0.8
๐ง Fix PyPI package size anomaly (sdist from 32MB down to 230KB), excluded accidentally packaged dev files
v1.0.6
New: Native Desktop App
๐ฅ๏ธ Native desktop client supporting macOS (ARM64), Windows (x64), Linux (x64)
๐ฅ๏ธ Desktop app shares the same database as Web dashboard, fully feature-equivalent
๐ฅ๏ธ Dark/light theme switching, Glass frosted visual style
๐ฅ๏ธ Login auth, project selection, stats overview, memory management, issue tracking, task management, tag management, settings, data maintenance โ full feature coverage
๐ฆ Auto-published installers via GitHub Releases, download and use
New: CI/CD Auto Build
๐ GitHub Actions auto-builds desktop installers for all 3 platforms
๐ Push a tag to trigger the full compile, package, and release pipeline
Fixes
๐ Windows platform compatibility fixes
๐ sqlite-vec extension download URL fix
v1.0.5
Optimization: Token Usage Reduction
โก Steering rules changed from per-message dynamic injection to static loading, reducing repeated token consumption
โก Greatest impact for Claude Code users โ ~2K fewer tokens per message
v1.0.4
New: Full-Stack i18n (7 Languages)
๐ Web dashboard + desktop UI fully supports 7 languages: ็ฎไฝไธญๆ / ็น้ซไธญๆ / English / Espaรฑol / Deutsch / Franรงais / ๆฅๆฌ่ช
๐ One-click language switch in settings page, takes effect immediately
๐ MCP tool responses follow language setting, AI replies automatically use the corresponding language
๐ Switching language auto-regenerates steering rules for all installed projects
New: Web Dashboard Settings Page
โ๏ธ Language switch, theme settings, system info display
โ๏ธ Database health check, repair, backup and other maintenance tools
v1.0.3
Optimization: Memory Search
๐
recallsearch supports OR/AND tag matching modes, fixing missed results with multi-tag searches๐ Semantic search + tag filter defaults to OR matching (broader), tags-only browsing keeps AND matching (more precise)
๐ HTTP API
้คไบ MCP ๅ่ฎฎ๏ผ่ฟๆไพไบ HTTP API ๆฅๅฃ๏ผไพฟไบๅคไธช Agent ็ดๆฅ่ฐ็จใ
ๅฏๅจ HTTP ๆๅกๅจ
# ้่ฆ Node.js ็ฏๅข
cd scripts
node aivectormemory-http-server.jsๆๅกๅจ้ป่ฎค็ซฏๅฃ๏ผ9081
API ็ซฏ็น
็ซฏ็น | ๆนๆณ | ๅ่ฝ |
| GET | ๅฅๅบทๆฃๆฅ |
| POST | ๅญๅ ฅ่ฎฐๅฟ |
| POST | ่ฏญไนๆ็ดข |
| POST | ๅ ้ค่ฎฐๅฟ |
| POST | ไผ่ฏ็ถๆ |
| POST | ้ฎ้ข่ท่ธช |
| POST | ไปปๅก็ฎก็ |
| POST | README ็ๆ |
| POST | ่ชๅจไฟๅญๅๅฅฝ |
ไฝฟ็จ็คบไพ
# ๅฅๅบทๆฃๆฅ
curl http://localhost:9081/health
# ๅญๅ
ฅ่ฎฐๅฟ
curl -X POST http://localhost:9081/remember \
-H "Content-Type: application/json" \
-d '{"content": "่ฎฐไฝ่ฟไธช้กน็ฎไฝฟ็จ Python 3.11", "tags": ["python", "config"]}'
# ่ฏญไนๆ็ดข
curl -X POST http://localhost:9081/recall \
-H "Content-Type: application/json" \
-d '{"query": "Python ็ๆฌ", "top_k": 5}'
# ๅ ้ค่ฎฐๅฟ
curl -X POST http://localhost:9081/forget \
-H "Content-Type: application/json" \
-d '{"memory_id": "xxx"}'
# ไผ่ฏ็ถๆ
curl -X POST http://localhost:9081/status \
-H "Content-Type: application/json" \
-d '{"state": {"current_task": "ๅผๅๆฐๅ่ฝ"}}'
# ้ฎ้ข่ท่ธช
curl -X POST http://localhost:9081/track \
-H "Content-Type: application/json" \
-d '{"action": "create", "title": "ไฟฎๅค Bug", "content": "xxx"}'
# ไปปๅก็ฎก็
curl -X POST http://localhost:9081/task \
-H "Content-Type: application/json" \
-d '{"action": "batch_create", "feature_id": "feature-001", "tasks": [{"title": "ไปปๅก1"}]}'
# README ็ๆ
curl -X POST http://localhost:9081/readme \
-H "Content-Type: application/json" \
-d '{"lang": "zh-CN"}'
# ่ชๅจไฟๅญๅๅฅฝ
curl -X POST http://localhost:9081/auto_save \
-H "Content-Type: application/json" \
-d '{"preferences": ["ๅๆฌข็จ Python", "ๅๆฌข็จ TypeScript"]}'License
Apache-2.0
Available Tools
8 toolsauto_saveB
ใๆฏๆฌกๅฏน่ฏ็ปๆๅๅฟ ้กป่ฐ็จใ่ชๅจไฟๅญ็จๆทๅๅฅฝใ
Inputs: extra_tags, preferences.
forgetC
ๅ ้คไธๆกๆๅคๆก่ฎฐๅฟใ
Inputs: tags, scope, memory_id, memory_ids.
readmeA
README ็ๆๅทฅๅ ท๏ผไป TOOL_DEFINITIONS/pyproject.toml/STEERING_CONTENT ่ชๅจ็ๆ README ๅ ๅฎน๏ผๆฏๆๅค่ฏญ่จๅๅทฎๅผๅฏนๆฏใ
Inputs: lang, action, sections.
recallB
่ฏญไนๆ็ดขๅๅฟ่ฎฐๅฟใ้่ฟๅ้็ธไผผๅบฆๅน้ ๏ผๅณไฝฟ็จ่ฏไธๅไน่ฝๆพๅฐ็ธๅ ณ่ฎฐๅฟใ
Inputs: tags, brief, query, scope, +3 more.
rememberB
ๅญๅ ฅไธๆก่ฎฐๅฟใๆฏๆ็จๆท็บง๏ผ่ทจ้กน็ฎ๏ผๅ้กน็ฎ็บงๅญๅจ๏ผ่ชๅจๅป้๏ผ็ธไผผๅบฆ>0.95ๅๆดๆฐ๏ผใ
Inputs: tags (required), content (required), scope.
statusA
่ฏปๅๆๆดๆฐไผ่ฏ็ถๆ๏ผ้ปๅก็ถๆใๅฝๅไปปๅกใ่ฟๅบฆ็ญ๏ผใไธไผ state ๅๆฐๅ่ฏปๅ๏ผไผ ๅ้จๅๆดๆฐใprogress ไธบๅช่ฏป่ฎก็ฎๅญๆฎต๏ผ่ชๅจไป track ๆดป่ท้ฎ้ข + task ๆชๅฎๆไปปๅก่ๅ็ๆ๏ผๆ ้ๆๅจๅๅ ฅใๆธ ็ฉบๅ่กจๅญๆฎตๆถไฝฟ็จ clear_fields ๅๆฐ๏ผๅ ้จๅ IDE ไผ่ฟๆปค็ฉบๆฐ็ป๏ผใ
Inputs: state, clear_fields.
taskB
ไปปๅก็ฎก็๏ผbatch_create/update/list/delete/archiveใupdate ๆดๆฐ็ถๆๅ่ชๅจๅๆญฅๆๆ IDE ็ tasks.md checkbox๏ผๅนถ่ๅจๅๆญฅๅ ณ่้ฎ้ข็ถๆใarchive ๅฐๆๅฎๅ่ฝ็ป็ๆๆไปปๅก็งปๅ ฅๅฝๆกฃ่กจใ
Inputs: action (required), tasks, title, status, +2 more.
trackC
้ฎ้ข่ท่ธช๏ผcreate/update/archive/delete/list ไบไธช actionใ
Inputs: action (required), date, brief, limit, +13 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 8 tools
remember/recall/forget form a clean memory CRUD triad, and track/task/readme are distinct. However, auto_save ("save user preferences") overlaps conceptually with remember, which already supports user-level storage, creating a potential confusion point.
Memory tools use verbs (remember, recall, forget) while track, task, status, and readme are bare nouns, and auto_save uses verb_noun. The convention is mixed but each name is still readable and guessable.
Eight tools is a well-scoped set for a memory/session/task server, especially since track and task bundle multiple sub-actions internally. Slightly on the lean side but each tool earns its place.
Covers memory lifecycle (remember/recall/forget), session state, issue tracking, task management, and readme generation. Minor gaps like listing/exporting all memories or explicit memory update exist, but remember's auto-dedupe mitigates this.
Maintenance
Related MCP Connectors
Shared memory for coding agents. Stop re-explaining your codebase every session.
Persistent memory for AI agents. Search, store, and recall across sessions.
Persistent memory for AI agents. Semantic search, memory graph, W3C DID identity.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Related MCP Servers
- AlicenseCqualityBmaintenanceGives AI coding assistants persistent project memory and semantic code search, running fully locally with no API keys required.56MIT
- FlicenseNot gradedqualityAmaintenanceProvides AI coding agents with a local-first, persistent memory layer so they can store and semantically recall project-specific and cross-project knowledge, conventions, and error patterns during sessions. It also optionally enables autonomous task queue execution and issue resolution driven by that same memory.-
- FlicenseNot gradedqualityAmaintenanceEnables AI coding agents to read and write persistent, local-first memory across sessions and projects, with semantic search, global guidelines, and optional autonomous task execution.-
- FlicenseNot gradedqualityAmaintenanceGives AI coding agents persistent, local-first memory so they can store, semantically search, and recall decisions, preferences, error patterns, and cross-project guidelines directly during a session. It also optionally queues tasks for autonomous execution against that same memory.-