CloudMem

CloudMem is a local-first memory layer for AI-assisted work. It mines project files or conversation exports into a hierarchical ChromaDB-backed “palace,” makes that memory available through a CLI and MCP server, and can move portable JSON snapshots between machines with Git.

Repository proof

The current package declares Python 3.9+, ships a cloudmem console command, and registers 24 mempalace_* MCP tools plus 24 cloudmem_* aliases from the same source registry. Focused tests cover onboarding, mining, normalization, search, sync failure behavior, MCP errors, snapshots, session finalization, and the thread ledger.

project files / conversation exports
                 ↓ mine
       Wing → Room → Closet → Drawer
                 ↓
    local search · MCP tools · wake-up context
                 ↓
      JSON snapshot ↔ private Git remote

Install and prove the first path

git clone https://github.com/raydocs/cloudmem.git
cd cloudmem
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

cloudmem --help
cloudmem init ~/projects/my-app
cloudmem mine ~/projects/my-app
cloudmem status
cloudmem search "where is authentication configured?"

init may scan for people and project entities and writes project setup data; review detected entities before accepting them. Use --yes only in controlled automation.

For development:

python -m pip install -e '.[dev]'
pytest -q

Two ingestion paths

# Source code, docs, and notes
cloudmem mine ~/projects/my-app

# Exported Claude, ChatGPT, or Slack-style conversations
cloudmem mine ~/exports --mode convos

# Preview without filing
cloudmem mine ~/exports --mode convos --dry-run

Large concatenated transcript files can be split first:

cloudmem split ~/exports --dry-run
cloudmem split ~/exports

CloudMem stores original drawer text and metadata in the local palace. cloudmem compress creates a separate compressed collection; the ratio depends on the content and configured dialect, so this README does not promise a fixed reduction.

Connect the MCP server

claude mcp add cloudmem -- python -m cloudmem.mcp_server

The MCP surface includes status/taxonomy, semantic search, duplicate checks, drawer writes/deletes, diary operations, graph traversal, temporal knowledge-graph operations, sync, and thread-ledger reads. The cloudmem_* names are aliases of the canonical mempalace_* handlers.

To smoke-test the process itself:

python -m cloudmem.mcp_server
# waits for JSON-RPC on stdin; Ctrl+C to stop

Portable sync

Use an empty private Git repository for memory data:

cloudmem sync-init git@github.com:you/my-palace.git
cloudmem push
cloudmem sync-status

# on another machine
cloudmem clone git@github.com:you/my-palace.git

Cross-machine portability uses exported JSON snapshots; the ChromaDB cache is rebuilt locally rather than copied as raw database files.

You can also manage snapshots directly:

cloudmem export --output palace.json
cloudmem import palace.json --dry-run
cloudmem import palace.json

Memory snapshots can contain source code, personal details, credentials copied from files, or private conversations. Review ignore rules and the exported JSON before the first push. A private repository reduces exposure but is not a substitute for data minimization or secret scanning.

Optional hooks and thread ledger

The Node installer registers Claude Code hooks that finalize sessions, create checkpoint prompts, and save before compaction:

npm ci
node bin/install.mjs

This mutates ~/.claude/settings.json; inspect the generated hook entries and scripts before enabling them. Git sync still requires a configured remote and valid credentials.

Thread commands:

cloudmem thread list --limit 20
cloudmem thread show <thread-id>
cloudmem thread serve --host 127.0.0.1 --port 8788

An optional Cloudflare Worker + D1 + R2 backend is documented in docs/thread_cloudflare.md.

Data and architecture

cloudmem/cli.py                CLI parser and dispatch
cloudmem/miner.py              project ingestion
cloudmem/convo_miner.py        conversation ingestion
cloudmem/storage.py            ChromaDB collection access
cloudmem/searcher.py           semantic search and ranking
cloudmem/dialect.py            AAAK compression dialect
cloudmem/knowledge_graph.py    SQLite temporal entity graph
cloudmem/snapshot.py           portable JSON export/import
cloudmem/sync.py               Git-backed sync operations
cloudmem/mcp_server.py         JSON-RPC MCP tool registry
cloudmem/session_finalizer.py  hook-driven session ingestion
cloudmem/thread_ledger.py      per-session records

State defaults to ~/.cloudmem/, including the palace cache, identity/entity files, graph database, snapshots, session manifests, and hook state. See docs/INSTALL.md for platform notes and troubleshooting.

Platform notes

• Python 3.9+ is required; CI targets Python 3.11.
• Node.js 18+ is needed only for the hook installer.
• Git is needed only for sync.
• The shell hooks are designed for macOS/Linux; Windows users should use WSL for that path.
• Cloudflare storage is optional and not required for local memory or MCP use.

License

pyproject.toml and package.json declare MIT, but this repository currently does not contain a standalone LICENSE file. Distributors should add the full license text before release.