Memory OS AI

Adaptive memory for AI agents — FAISS search, chat extraction, cross-project linking

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "memory-os-ai": {
      "command": "npx",
      "args": [
        "-y",
        "memory-os-ai"
      ]
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

Memory OS AI

Adaptive memory system for AI agents — universal MCP server for Claude Code, Codex CLI, VS Code Copilot, ChatGPT, and any MCP-compatible client.

Concept

Memory OS AI transforms your local documents (PDF, DOCX, images, audio) into a semantic memory queryable by any AI model through the MCP (Model Context Protocol).

Code

┌──────────────────────────────────┐
│  AI Client (any MCP-compatible)  │
│  Claude Code / Codex / Copilot   │
│  ChatGPT / custom agents         │
├──────────────────────────────────┤
│         MCP Protocol             │
│   stdio / SSE / Streamable HTTP  │
├──────────────────────────────────┤
│      Memory OS AI Server         │
│  ┌────────┐  ┌───────────────┐   │
│  │ FAISS  │  │ Chat Extractor│   │
│  │ Index  │  │ (4 sources)   │   │
│  └────────┘  └───────────────┘   │
│  ┌────────────────────────────┐  │
│  │ Cross-Project Linking      │  │
│  └────────────────────────────┘  │
└──────────────────────────────────┘

Features

21 MCP tools for memory management, search, chat persistence, project linking, and cloud storage
Semantic search with FAISS + SentenceTransformers (all-MiniLM-L6-v2)
Multi-format ingestion: PDF, DOCX, TXT, images (OCR), audio (Whisper), PPTX
Chat extraction: auto-detects Claude, ChatGPT, Copilot, and terminal history
Cross-project linking: share memory across multiple workspaces
Cloud storage overflow: auto-backup to Google Drive, iCloud, Dropbox, OneDrive, S3, Azure, Box, B2
3 transports: stdio (default), SSE (--sse), Streamable HTTP (--http)
MCP Resources: memory://documents/*, memory://logs/conversation, memory://linked/*
Local-first: all data on your machine by default, cloud only when disk runs low

21 MCP Tools

Tool	Description
`memory_ingest`	Index a folder of documents into FAISS
`memory_search`	Semantic search across all indexed content
`memory_search_occurrences`	Count keyword occurrences across documents
`memory_get_context`	Get relevant context for the current task
`memory_list_documents`	List all indexed documents with stats
`memory_transcribe`	Transcribe audio files (Whisper)
`memory_status`	Engine status (index size, model, device)
`memory_compact`	Compact/deduplicate the FAISS index
`memory_chat_sync`	Sync messages from configured chat sources
`memory_chat_source_add`	Add a chat source (Claude, ChatGPT, etc.)
`memory_chat_source_remove`	Remove a chat source
`memory_chat_status`	Status of all chat sources
`memory_chat_auto_detect`	Auto-detect chat workspaces on disk
`memory_session_brief`	Full memory briefing for session start
`memory_chat_save`	Persist conversation messages to memory
`memory_project_link`	Link another project's memory
`memory_project_unlink`	Unlink a project
`memory_project_list`	List all linked projects
`memory_cloud_configure`	Configure cloud storage backend for overflow
`memory_cloud_status`	Show local disk + cloud storage status
`memory_cloud_sync`	Push/pull/auto-sync between local and cloud

Quick Start

Prerequisites

Python 3.10+
Optional: tesseract (OCR), ffmpeg (audio), antiword (legacy .doc)

bash

# macOS
brew install tesseract ffmpeg antiword

# Ubuntu/Debian
sudo apt-get install tesseract-ocr ffmpeg antiword

Install

bash

git clone https://github.com/romainsantoli-web/Memory-os-ai.git
cd Memory-os-ai
pip install -e ".[dev,audio]"

Auto-Setup (recommended)

bash

# Setup for your AI client:
memory-os-ai setup claude-code    # Claude Code
memory-os-ai setup codex          # Codex CLI
memory-os-ai setup vscode         # VS Code Copilot
memory-os-ai setup claude-desktop # Claude Desktop
memory-os-ai setup chatgpt        # ChatGPT (manual bridge)
memory-os-ai setup all            # All of the above

# Check status:
memory-os-ai setup status

Manual Start

bash

# stdio (default — Claude Code, VS Code, Codex)
memory-os-ai

# SSE transport (port 8765)
memory-os-ai --sse

# Streamable HTTP (port 8765)
memory-os-ai --http

Project Structure

server.ts

Memory-os-ai/
├── src/memory_os_ai/
│   ├── __init__.py          # Public API: MemoryEngine, ChatExtractor, TOOL_MODELS
│   ├── __main__.py          # python -m memory_os_ai entry point
│   ├── server.py            # MCP server — 21 tools, 3 transports, resources
│   ├── engine.py            # FAISS engine — indexing, search, compact, session brief
│   ├── cloud_storage.py     # 8 cloud backends (GDrive, iCloud, Dropbox, OneDrive, S3, Azure, Box, B2)
│   ├── storage_router.py    # Smart routing: local-first with cloud overflow
│   ├── models.py            # 21 Pydantic models + TOOL_MODELS registry
│   ├── chat_extractor.py    # 4 extractors: Claude, ChatGPT, Copilot, terminal
│   ├── instructions.py      # MEMORY_INSTRUCTIONS for AI clients
│   └── setup.py             # Auto-setup CLI for 5 AI clients
├── bridges/
│   ├── claude-code/         # CLAUDE.md with memory rules
│   ├── claude-desktop/      # config.json for Claude Desktop
│   ├── codex/               # AGENTS.md for Codex CLI
│   ├── vscode/              # mcp.json for VS Code
│   └── chatgpt/             # mcp-connection.json for ChatGPT
├── tests/                   # 410+ tests — 96% coverage
│   ├── test_memory.py       # Engine + models (60 tests)
│   ├── test_chat_extractor.py  # Chat extraction (39 tests)
│   ├── test_bridges.py      # Bridge configs (22 tests)
│   ├── test_gaps.py         # Compact, cross-project, resources (34 tests)
│   ├── test_server_dispatch.py # Server dispatch + async (61 tests)
│   ├── test_setup.py        # Setup CLI targets
│   ├── test_z_coverage_boost.py # Coverage boost (35 tests)
│   └── test_zz_full_coverage.py # Full coverage (97 tests)
├── pyproject.toml           # v3.1.0 — deps, scripts, coverage config + cloud optional deps
├── Dockerfile               # Container deployment
└── README.md

Cloud Storage (v3.1.0)

When local disk runs low (< 500 MB free by default), memory data automatically overflows to a configured cloud backend.

Supported Providers

Provider	Install	Credentials
Google Drive	`pip install memory-os-ai[cloud-gdrive]`	`credentials_json` or `token_json` + `folder_id`
iCloud Drive	(macOS native, no extra deps)	`container` name (default: `memory-os-ai`)
Dropbox	`pip install memory-os-ai[cloud-dropbox]`	`access_token` + `folder`
OneDrive	(auto-detects mount) or Graph API	`mount_path` or `access_token`
Amazon S3	`pip install memory-os-ai[cloud-s3]`	`bucket`, `aws_access_key_id`, `aws_secret_access_key`
Azure Blob	`pip install memory-os-ai[cloud-azure]`	`connection_string` + `container`
Box	`pip install memory-os-ai[cloud-box]`	`access_token` + `folder_id`
Backblaze B2	`pip install memory-os-ai[cloud-b2]`	`application_key_id`, `application_key`, `bucket_name`
All providers	`pip install memory-os-ai[cloud-all]`	—

Usage

server.ts

# Configure via environment (auto-activates on server start)
export MEMORY_CLOUD_PROVIDER=icloud
export MEMORY_CLOUD_CONFIG='{"container": "memory-os-ai"}'
memory-os-ai

# Or configure at runtime via MCP tool:
#   memory_cloud_configure(provider="s3", credentials={"bucket": "my-bucket", ...})
#   memory_cloud_status()       → local disk + cloud usage
#   memory_cloud_sync("push")   → backup to cloud
#   memory_cloud_sync("pull")   → restore from cloud
#   memory_cloud_sync("auto")   → offload if disk low

Configuration

Environment Variables

Variable	Default	Description
`MEMORY_CACHE_DIR`	`~/.memory-os-ai`	Cache / FAISS index directory
`MEMORY_MODEL`	`all-MiniLM-L6-v2`	SentenceTransformer model name
`MEMORY_API_KEY`	(none)	Optional API key for SSE/HTTP auth
`MEMORY_CLOUD_PROVIDER`	(none)	Cloud provider name (see table above)
`MEMORY_CLOUD_CONFIG`	(none)	JSON credentials or path to JSON file
`MEMORY_DISK_THRESHOLD`	`524288000`	Bytes free before cloud overflow (500 MB)

Development

bash

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
python -m pytest tests/ -v

# Run with coverage
python -m pytest tests/ --cov=memory_os_ai --cov-report=term-missing

# Coverage threshold: 80% (enforced in pyproject.toml)

License

GNU Lesser General Public License v3.0 (LGPL-3.0). See LICENSE for details.

For commercial licensing, contact romainsantoli@gmail.com.

Part of the OpenClaw Ecosystem

Memory OS AI is designed to work alongside the OpenClaw agent infrastructure:

Repo	Description
setup-vs-agent-firm	Factory for AI agent firms — 28 SKILL.md, 5 SOUL.md, 15 sectors
mcp-openclaw-extensions	115 MCP tools — security audit, A2A bridge, fleet management
Memory OS AI (this repo)	Semantic memory + chat persistence — universal MCP bridge

Read the full README →View source on GitHub →

Related MCP Servers

View all in Knowledge & Memory View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Memory OS AI

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "memory-os-ai": { "command": "npx", "args": ["-y", "Memory OS AI"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/memory-os-ai?style=directory)](https://allmcps.com/mcp/memory-os-ai)

HTML Embed

<a href="https://allmcps.com/mcp/memory-os-ai"><img src="https://allmcps.com/api/badge/memory-os-ai?style=directory" alt="Memory OS AI on AllMCPs" /></a>

Technical Specs & Signals

CategoryKnowledge & Memory

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.

★ Featured

Moxie Docs MCP

MCP & Agent Skills for Automated Documentation, and codebase conventions + context

Explore Server →

Own this project?

This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge and attach your website — proof is checked automatically, then reviewed by our team.

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 🧠 Knowledge & Memory →Best MCP servers for Memory & Knowledge →Alternatives to Memory OS AI →Install in Claude Desktop Install in Cursor Install in VS Code

Memory OS AI

Adaptive memory for AI agents — FAISS search, chat extraction, cross-project linking

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "memory-os-ai": {
      "command": "npx",
      "args": [
        "-y",
        "memory-os-ai"
      ]
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

Memory OS AI

Adaptive memory system for AI agents — universal MCP server for Claude Code, Codex CLI, VS Code Copilot, ChatGPT, and any MCP-compatible client.

Concept

Memory OS AI transforms your local documents (PDF, DOCX, images, audio) into a semantic memory queryable by any AI model through the MCP (Model Context Protocol).

Code

┌──────────────────────────────────┐
│  AI Client (any MCP-compatible)  │
│  Claude Code / Codex / Copilot   │
│  ChatGPT / custom agents         │
├──────────────────────────────────┤
│         MCP Protocol             │
│   stdio / SSE / Streamable HTTP  │
├──────────────────────────────────┤
│      Memory OS AI Server         │
│  ┌────────┐  ┌───────────────┐   │
│  │ FAISS  │  │ Chat Extractor│   │
│  │ Index  │  │ (4 sources)   │   │
│  └────────┘  └───────────────┘   │
│  ┌────────────────────────────┐  │
│  │ Cross-Project Linking      │  │
│  └────────────────────────────┘  │
└──────────────────────────────────┘

Features

21 MCP tools for memory management, search, chat persistence, project linking, and cloud storage
Semantic search with FAISS + SentenceTransformers (all-MiniLM-L6-v2)
Multi-format ingestion: PDF, DOCX, TXT, images (OCR), audio (Whisper), PPTX
Chat extraction: auto-detects Claude, ChatGPT, Copilot, and terminal history
Cross-project linking: share memory across multiple workspaces
Cloud storage overflow: auto-backup to Google Drive, iCloud, Dropbox, OneDrive, S3, Azure, Box, B2
3 transports: stdio (default), SSE (--sse), Streamable HTTP (--http)
MCP Resources: memory://documents/*, memory://logs/conversation, memory://linked/*
Local-first: all data on your machine by default, cloud only when disk runs low

21 MCP Tools

Tool	Description
`memory_ingest`	Index a folder of documents into FAISS
`memory_search`	Semantic search across all indexed content
`memory_search_occurrences`	Count keyword occurrences across documents
`memory_get_context`	Get relevant context for the current task
`memory_list_documents`	List all indexed documents with stats
`memory_transcribe`	Transcribe audio files (Whisper)
`memory_status`	Engine status (index size, model, device)
`memory_compact`	Compact/deduplicate the FAISS index
`memory_chat_sync`	Sync messages from configured chat sources
`memory_chat_source_add`	Add a chat source (Claude, ChatGPT, etc.)
`memory_chat_source_remove`	Remove a chat source
`memory_chat_status`	Status of all chat sources
`memory_chat_auto_detect`	Auto-detect chat workspaces on disk
`memory_session_brief`	Full memory briefing for session start
`memory_chat_save`	Persist conversation messages to memory
`memory_project_link`	Link another project's memory
`memory_project_unlink`	Unlink a project
`memory_project_list`	List all linked projects
`memory_cloud_configure`	Configure cloud storage backend for overflow
`memory_cloud_status`	Show local disk + cloud storage status
`memory_cloud_sync`	Push/pull/auto-sync between local and cloud

Quick Start

Prerequisites

Python 3.10+
Optional: tesseract (OCR), ffmpeg (audio), antiword (legacy .doc)

bash

# macOS
brew install tesseract ffmpeg antiword

# Ubuntu/Debian
sudo apt-get install tesseract-ocr ffmpeg antiword

Install

bash

git clone https://github.com/romainsantoli-web/Memory-os-ai.git
cd Memory-os-ai
pip install -e ".[dev,audio]"

Auto-Setup (recommended)

bash

# Setup for your AI client:
memory-os-ai setup claude-code    # Claude Code
memory-os-ai setup codex          # Codex CLI
memory-os-ai setup vscode         # VS Code Copilot
memory-os-ai setup claude-desktop # Claude Desktop
memory-os-ai setup chatgpt        # ChatGPT (manual bridge)
memory-os-ai setup all            # All of the above

# Check status:
memory-os-ai setup status

Manual Start

bash

# stdio (default — Claude Code, VS Code, Codex)
memory-os-ai

# SSE transport (port 8765)
memory-os-ai --sse

# Streamable HTTP (port 8765)
memory-os-ai --http

Project Structure

server.ts

Memory-os-ai/
├── src/memory_os_ai/
│   ├── __init__.py          # Public API: MemoryEngine, ChatExtractor, TOOL_MODELS
│   ├── __main__.py          # python -m memory_os_ai entry point
│   ├── server.py            # MCP server — 21 tools, 3 transports, resources
│   ├── engine.py            # FAISS engine — indexing, search, compact, session brief
│   ├── cloud_storage.py     # 8 cloud backends (GDrive, iCloud, Dropbox, OneDrive, S3, Azure, Box, B2)
│   ├── storage_router.py    # Smart routing: local-first with cloud overflow
│   ├── models.py            # 21 Pydantic models + TOOL_MODELS registry
│   ├── chat_extractor.py    # 4 extractors: Claude, ChatGPT, Copilot, terminal
│   ├── instructions.py      # MEMORY_INSTRUCTIONS for AI clients
│   └── setup.py             # Auto-setup CLI for 5 AI clients
├── bridges/
│   ├── claude-code/         # CLAUDE.md with memory rules
│   ├── claude-desktop/      # config.json for Claude Desktop
│   ├── codex/               # AGENTS.md for Codex CLI
│   ├── vscode/              # mcp.json for VS Code
│   └── chatgpt/             # mcp-connection.json for ChatGPT
├── tests/                   # 410+ tests — 96% coverage
│   ├── test_memory.py       # Engine + models (60 tests)
│   ├── test_chat_extractor.py  # Chat extraction (39 tests)
│   ├── test_bridges.py      # Bridge configs (22 tests)
│   ├── test_gaps.py         # Compact, cross-project, resources (34 tests)
│   ├── test_server_dispatch.py # Server dispatch + async (61 tests)
│   ├── test_setup.py        # Setup CLI targets
│   ├── test_z_coverage_boost.py # Coverage boost (35 tests)
│   └── test_zz_full_coverage.py # Full coverage (97 tests)
├── pyproject.toml           # v3.1.0 — deps, scripts, coverage config + cloud optional deps
├── Dockerfile               # Container deployment
└── README.md

Cloud Storage (v3.1.0)

When local disk runs low (< 500 MB free by default), memory data automatically overflows to a configured cloud backend.

Supported Providers

Provider	Install	Credentials
Google Drive	`pip install memory-os-ai[cloud-gdrive]`	`credentials_json` or `token_json` + `folder_id`
iCloud Drive	(macOS native, no extra deps)	`container` name (default: `memory-os-ai`)
Dropbox	`pip install memory-os-ai[cloud-dropbox]`	`access_token` + `folder`
OneDrive	(auto-detects mount) or Graph API	`mount_path` or `access_token`
Amazon S3	`pip install memory-os-ai[cloud-s3]`	`bucket`, `aws_access_key_id`, `aws_secret_access_key`
Azure Blob	`pip install memory-os-ai[cloud-azure]`	`connection_string` + `container`
Box	`pip install memory-os-ai[cloud-box]`	`access_token` + `folder_id`
Backblaze B2	`pip install memory-os-ai[cloud-b2]`	`application_key_id`, `application_key`, `bucket_name`
All providers	`pip install memory-os-ai[cloud-all]`	—

Usage

server.ts

# Configure via environment (auto-activates on server start)
export MEMORY_CLOUD_PROVIDER=icloud
export MEMORY_CLOUD_CONFIG='{"container": "memory-os-ai"}'
memory-os-ai

# Or configure at runtime via MCP tool:
#   memory_cloud_configure(provider="s3", credentials={"bucket": "my-bucket", ...})
#   memory_cloud_status()       → local disk + cloud usage
#   memory_cloud_sync("push")   → backup to cloud
#   memory_cloud_sync("pull")   → restore from cloud
#   memory_cloud_sync("auto")   → offload if disk low

Configuration

Environment Variables

Variable	Default	Description
`MEMORY_CACHE_DIR`	`~/.memory-os-ai`	Cache / FAISS index directory
`MEMORY_MODEL`	`all-MiniLM-L6-v2`	SentenceTransformer model name
`MEMORY_API_KEY`	(none)	Optional API key for SSE/HTTP auth
`MEMORY_CLOUD_PROVIDER`	(none)	Cloud provider name (see table above)
`MEMORY_CLOUD_CONFIG`	(none)	JSON credentials or path to JSON file
`MEMORY_DISK_THRESHOLD`	`524288000`	Bytes free before cloud overflow (500 MB)

Development

bash

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
python -m pytest tests/ -v

# Run with coverage
python -m pytest tests/ --cov=memory_os_ai --cov-report=term-missing

# Coverage threshold: 80% (enforced in pyproject.toml)

License

GNU Lesser General Public License v3.0 (LGPL-3.0). See LICENSE for details.

For commercial licensing, contact romainsantoli@gmail.com.

Part of the OpenClaw Ecosystem

Memory OS AI is designed to work alongside the OpenClaw agent infrastructure:

Repo	Description
setup-vs-agent-firm	Factory for AI agent firms — 28 SKILL.md, 5 SOUL.md, 15 sectors
mcp-openclaw-extensions	115 MCP tools — security audit, A2A bridge, fleet management
Memory OS AI (this repo)	Semantic memory + chat persistence — universal MCP bridge

Read the full README →View source on GitHub →

Related MCP Servers

View all in Knowledge & Memory View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Memory OS AI

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "memory-os-ai": { "command": "npx", "args": ["-y", "Memory OS AI"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/memory-os-ai?style=directory)](https://allmcps.com/mcp/memory-os-ai)

HTML Embed

<a href="https://allmcps.com/mcp/memory-os-ai"><img src="https://allmcps.com/api/badge/memory-os-ai?style=directory" alt="Memory OS AI on AllMCPs" /></a>

Technical Specs & Signals

CategoryKnowledge & Memory

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

★ Featured

Moxie Docs MCP

MCP & Agent Skills for Automated Documentation, and codebase conventions + context

Explore Server →

Own this project?

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 🧠 Knowledge & Memory →Best MCP servers for Memory & Knowledge →Alternatives to Memory OS AI →Install in Claude Desktop Install in Cursor Install in VS Code