Long-term memory MCP server for LLM agents, designed to help AI assistants remember their reasoning, decisions, and context across sessions.
AIVC transforms memories (formerly commits) into a searchable knowledge base for AI agents.
- Remember: The agent records its achievements in memories containing an extremely detailed Markdown note.
- Recall: Semantic indexing (Bi-encoder + Cross-encoder) operates on these notes to retrieve past context by meaning.
- Recursive Context: File history is preserved locally, allowing agents to see what changed and how.
- Metadata-only Sync: Reasoning is shared across machines via Google Drive, while file contents (blobs) remain local for privacy and performance.
- Windows Native: Engineered with zero-lock SQLite structures, lightning-fast lightweight background warmup with 100% lazy Cross-Encoder model loading to prevent multi-thread import deadlocks and satisfy strict IDE server timeouts, proper redirection of background sync stdout logging to
sys.stderrto avoid JSON-RPC protocol corruption, ultra-fast file observers, and automatic physical commit scanning during warmup to instantly index synchronized multi-machine memories.
- Python: 3.11+
- uv (recommended package installer):
curl -fsSL https://astral.sh/uv/install.sh | shorpowershell -c "irm https://astral.sh/uv/install.ps1 | iex"
curl -fsSL "https://raw.githubusercontent.com/UNIL-DESI/aivc/main/install.sh" | bashpowershell -c "irm https://raw.githubusercontent.com/UNIL-DESI/aivc/main/install.sh -OutFile install.sh; & 'C:\Program Files\Git\bin\bash.exe' install.sh; Remove-Item install.sh"Note
On Windows, running install.sh generates a aivc.cmd wrapper script inside ~/.local/bin/ alongside the standard aivc bash script. This ensures the CLI runs flawlessly inside Windows Command Prompt (CMD) and PowerShell without triggering the OS "Open with..." dialog for the extensionless file. It also configures standard paths, registers the MCP server in the active ~/.gemini/config/mcp_config.json configuration, resolves Git Bash line endings (LF), and uses appropriate package index strategies for PyTorch/CUDA dependencies.
# Local development installation
uv pip install -e .AIVC operates at the boundary of Git-like file tracking and modern vector-based semantic retrieval. It enables AI agents to maintain a continuous stream of consciousness.
+--------------------+ 1. remembers context +------------------------+
| | -----------------------------> | |
| LLM Agent Active | | AIVC SQLite Database |
| Session | <----------------------------- | & Semantic Index |
| | 2. recalls history +------------------------+
+--------------------+
- Memory Recording (
remember): When completing a task, the agent compiles their actions, decisions, and outcomes into a Markdown note. AIVC takes explicit lists of read and edited files to construct bipartite association links. - Semantic Retrieval (
recall): The agent queries past memories with natural language. Under the hood, a local dual-encoder embeds the query, matches notes, and extracts highly relevant context snippets.
Following extensive porting and performance tuning for native Windows operations, AIVC provides the following benchmark results:
| Operation | Platform | Average Speed | Success Rate | Resource Usage |
|---|---|---|---|---|
Memory Creation (remember) |
Windows Native | < 90ms |
100% |
Zero DB locks / WAL mode |
Semantic Query (recall) |
Windows Native | < 75ms |
100% |
In-memory indexing |
| Comprehensive Test Suite | Windows Native | 110s total |
100% (173/173) |
SQLite connection pooling |
| Title (Link) | Description |
|---|---|
| Architecture Index | Technical architecture of the project and backend structures. |
| Tasks Index | Chronological development roadmap and task specifications. |
| Sync Policy | Architectural details on Phase 29/30 metadata-only synchronization. |
aivc/
├── .agent/
├── docs/ # Detailed documentation & roadmap tasks
│ ├── tasks/ # Specific phase specifications
│ └── index_*.md # Documentation indexes
├── scripts/ # Utility scripts (migration, setup)
├── src/aivc/ # Core source code
│ ├── core/ # Base storage & tracking engine
│ ├── semantic/ # Semantic graph and lexical search fallbacks
│ ├── sync/ # Google Drive metadata sync
│ ├── cli.py # CLI entrypoint
│ └── server.py # MCP FastMCP server implementation
├── tests/ # Comprehensive test suite
├── pyproject.toml # Build and dependency configuration
└── README.md # Repository entrypoint
Exposed tools available to LLM assistants when configuring the AIVC MCP server:
| Command | Type | Description |
|---|---|---|
remember |
Write | Records a memory (Title + Markdown Note) associated with explicitly read and edited files. Raises strict validation errors for folders or untracked non-existent paths. Call after major milestones. |
recall |
Read | Semantic search over memories. Returns ranked results (ID, title, score) + contextual snippets. |
get_recent_memories |
Read | Retrospective chronological journal of the last N memories. |
consult_memory |
Read | Retrieve the complete Markdown note and modified file diffs for a specific memory. |
get_file_history_metadata |
Read | Retrieve the chronological list of all memories (commits) that modified or consulted a specific file. |
read_past_file_content |
Read | Retrieve the actual text content of a file exactly as it was at the time of a specific past memory. |
get_status |
Read | Explores tracked files, active directory structures, and size allocations. |
Utilities for installation, data maintenance, and migrations:
| Script / Utility | Target | Description |
|---|---|---|
scripts/migrate_commit_paths.py |
Data Migration | Scans database memory structures to convert POSIX/WSL absolute paths to Windows-compatible structures during host migrations. |
test_perf.py & test_perf_v2.py |
Benchmarking | Comprehensive performance harness targeting database IO and concurrent vector lookup. |
scripts/install.sh |
Setup | Shell-based automated system setup, Python environment bootstrapping, MCP linkage, and FastEmbed model pre-downloading. |
AIVC supports sharing memory metadata across multiple machines via Google Drive.
For remote servers, containers, or environments without a web browser, use the --headless flag:
aivc sync setup --headlessWhen running with --headless:
- It generates the authorization URL and prints it to the console.
- Open this URL in any web browser on any machine.
- Authenticate with Google and approve the requested permissions.
- Your browser will be redirected to a localhost address (e.g.,
http://localhost/?state=...&code=...), which will fail to load. This is normal. - Copy the entire redirect URL from the browser's address bar (or just the
codeparameter value) and paste it back into the AIVC terminal prompt to complete the authentication.
If you already have a configured and authenticated AIVC instance on a local machine, you can quickly copy the authentication state to another machine by copying the configuration directory:
- Locate the configuration directory on your source machine:
~/.aivc/(orC:\Users\<username>\.aivcon Windows). - Copy the entire directory (containing
config.json,credentials.json, andtoken.json) to the destination machine at the same path:~/.aivc/. - Check the status on the destination machine to confirm:
aivc sync status
[x]Phase 28: Synchronous I/O Optimization.[x]Phase 29: Memory Refactor & Tree Status. [Spec][x]Phase 30: System Unification & Debt Cleanup. [Spec][x]Phase 31: Ultra-Fast Parallel Search (Obsidian-like).[x]Phase 32: Windows Portability & Performance. [Spec][x]Phase 33: Windows Bulk Warmup & Physical Sync. [Spec][x]Phase 34: Windows Threading Deadlock & Cross-Encoder Bypass. [Spec][x]Phase 35: Explicit File Tracking & Strict Path Validation.[x]Phase 36: Correctifs de Rendu, Navigation et Diffs Statistiques / Unifiés MCP.