diff --git a/README.md b/README.md
index 15a85ba..a364704 100644
--- a/README.md
+++ b/README.md
@@ -1,333 +1,160 @@
-[English](README.md) | [δΈζ](README_CN.md)
+
+
-
+# CloudMem
-# ποΈ 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.
-**AI memory with cloud sync**
+## Repository proof
-*AAAK compression Β· Palace architecture Β· GitHub-backed persistence*
+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.
-[](https://www.python.org)
-[](https://opensource.org/licenses/MIT)
-[]()
-[]()
-[]()
-
-
-
----
-
-## The Problem
-
-AI assistants forget everything between sessions. Context windows are expensive and finite. You end up re-explaining your project, your preferences, and your decisions β every single time. **CloudMem** gives your AI a persistent, compressed, searchable memory that syncs to GitHub and follows you to any machine. It uses ~30Γ lossless AAAK compression so your entire knowledge base fits in a fraction of a context window, and any LLM can read it natively β no special decoder needed.
-
----
-
-## β¨ Key Features
-
-| | Feature | Description |
-|---|---------|-------------|
-| π§ | **AAAK Compression** | ~30Γ lossless compression β any LLM reads it natively |
-| ποΈ | **Palace Architecture** | Wing β Room β Closet β Drawer hierarchy, +34% retrieval accuracy |
-| π | **48 MCP Tools** | 24 `mempalace_*` + 24 `cloudmem_*` aliases β full read/write/search/graph access |
-| βοΈ | **GitHub Cloud Sync** | Push, pull, or clone your palace to any machine |
-| π | **4-Layer Memory Stack** | From always-on identity (50 tokens) to deep semantic search |
-| πͺ | **Auto Hooks** | SessionEnd, Stop, PreCompact β memory saves itself |
-| π | **Thread Ledger** | AMP-style per-session tracking with optional Cloudflare remote |
-| π | **Semantic Search** | ChromaDB vector store with local embeddings β no API key needed |
-| π¦ | **Portable Snapshots** | Export/import via JSON β not raw Chroma files |
-| 𧩠| **Knowledge Graph** | Temporal entity graph in SQLite for relationship tracking |
-
----
-
-## π Quick Start
+```text
+project files / conversation exports
+ β mine
+ Wing β Room β Closet β Drawer
+ β
+ local search Β· MCP tools Β· wake-up context
+ β
+ JSON snapshot β private Git remote
+```
-### 1. Install
+## Install and prove the first path
```bash
-pip install -e .
-
-# Dev/test dependencies
-pip install -e ".[dev]"
-
-# Node installer for hooks
-npm install
+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?"
```
-### 2. Initialize your palace
+`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.
-```bash
-# Generate palace config + scan project structure
-cloudmem init
+For development:
-# Mine project files into memory
-cloudmem mine
-
-# Interactive onboarding (identity, entities, AAAK)
-cloudmem onboard
+```bash
+python -m pip install -e '.[dev]'
+pytest -q
```
-### 3. Connect MCP server
+## Two ingestion paths
```bash
-claude mcp add cloudmem -- python -m cloudmem.mcp_server
-```
+# Source code, docs, and notes
+cloudmem mine ~/projects/my-app
-### 4. Link cloud sync
+# Exported Claude, ChatGPT, or Slack-style conversations
+cloudmem mine ~/exports --mode convos
-```bash
-# Create a private GitHub repo, then:
-cloudmem sync-init git@github.com:you/my-palace.git
+# Preview without filing
+cloudmem mine ~/exports --mode convos --dry-run
```
-### 5. Install hooks
+Large concatenated transcript files can be split first:
```bash
-node bin/install.mjs
+cloudmem split ~/exports --dry-run
+cloudmem split ~/exports
```
-That's it. Your AI now remembers everything and syncs to the cloud automatically.
+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.
----
-
-## ποΈ Architecture
-
-```
-βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-β Claude Code / LLM β
-ββββββββββββββββ¬ββββββββββββββββββββββββββββββββ¬βββββββββββββββββββ
- β MCP (48 tools) β Hooks
- βΌ βΌ
-ββββββββββββββββββββββββββββ ββββββββββββββββββββββββββββββββ
-β cloudmem.mcp_server β β SessionEnd Β· Stop Β· β
-β 24 mempalace_* tools β β PreCompact β
-β 24 cloudmem_* aliases β β β session-finalize β
-ββββββββββββββ¬ββββββββββββββ β β checkpoint save β
- β β β save before compact β
- βΌ ββββββββββββββββ¬ββββββββββββββββ
-ββββββββββββββββββββββββββββββββββββββββββββββββ
-β CloudMem Core β
-β β
-β βββββββββββ ββββββββββββ βββββββββββββββββ β
-β β AAAK β β Layers β β Knowledge β β
-β β Dialect β β L0βL3 β β Graph (SQLite)β β
-β ββββββ¬βββββ ββββββ¬ββββββ βββββββββ¬ββββββββ β
-β β β β β
-β βΌ βΌ βΌ β
-β ββββββββββββββββββββββββββββββββββββββββββ β
-β β ChromaDB Vector Store (local) β β
-β β Palace: Wing/Room/Closet/Drawer β β
-β ββββββββββββββββββββββββββββββββββββββββββ β
-ββββββββββββββββββββ¬ββββββββββββββββββββββββββββ
- β
- ββββββββββββΌβββββββββββ
- βΌ βΌ βΌ
-ββββββββββββ ββββββββββββ ββββββββββββββββββββ
-β JSON β β Git Sync β β Thread Ledger β
-β Snapshot β β push/pullβ β local + optional β
-β Export β β /clone β β Cloudflare remoteβ
-ββββββββββββ ββββββ¬ββββββ ββββββββββββββββββββ
- β
- βΌ
- ββββββββββββββββ
- β GitHub β
- β Private Repo β
- ββββββββββββββββ
-```
-
----
-
-## 𧱠Memory Stack
-
-| Layer | Content | Size | Loaded | Description |
-|:-----:|---------|:----:|--------|-------------|
-| **L0** | Identity | ~50 tokens | Always | Who you are β name, role, preferences |
-| **L1** | Critical Facts (AAAK) | ~120 tokens | Always | Key decisions, architecture choices, compressed losslessly |
-| **L2** | Room Recall | Variable | On demand | Full room contents when a relevant topic surfaces |
-| **L3** | Deep Semantic Search | Variable | On demand | Vector similarity search across entire palace |
-
-> L0 + L1 load automatically on wake-up (~170 tokens total). L2 and L3 activate only when the AI needs deeper context β keeping your token budget lean.
-
----
-
-## π» CLI Reference
-
-| Command | Description |
-|---------|-------------|
-| `cloudmem init ` | Detect rooms from folder structure, generate config |
-| `cloudmem mine ` | Mine files into the palace |
-| `cloudmem search ` | Semantic search across all memories |
-| `cloudmem compress ` | Compress a file using AAAK dialect |
-| `cloudmem wake-up` | Show L0 + L1 wake-up context |
-| `cloudmem split ` | Split oversized files into palace-friendly chunks |
-| `cloudmem status` | Show what's been filed |
-| `cloudmem onboard` | Interactive onboarding (identity, entities, AAAK) |
-| `cloudmem sync-init ` | Link storage to a private GitHub repo |
-| `cloudmem sync-status` | Show cloud sync status |
-| `cloudmem push` | Push palace to GitHub |
-| `cloudmem pull` | Pull latest palace from GitHub |
-| `cloudmem clone ` | Restore palace on a new machine |
-| `cloudmem export` | Export palace to portable JSON snapshot |
-| `cloudmem import ` | Import a JSON snapshot (rebuilds embeddings) |
-| `cloudmem thread list` | List recent thread summaries |
-| `cloudmem thread show ` | Show details for a specific thread |
-| `cloudmem thread serve` | Launch local web UI for threads (port 8788) |
-| `cloudmem session-finalize` | Ingest transcript + sync (called by hooks) |
-
----
-
-## π MCP Tools
-
-48 tools total β every `mempalace_*` tool has a `cloudmem_*` alias.
-
-| Group | Tools | Description |
-|-------|-------|-------------|
-| **Read** | `status`, `list_wings`, `list_rooms`, `get_taxonomy`, `search`, `check_duplicate` | Query palace structure and search memories |
-| **Write** | `add_drawer`, `delete_drawer` | File and remove memory entries |
-| **Graph** | `traverse`, `find_tunnels`, `graph_stats` | Navigate palace topology and cross-references |
-| **Knowledge Graph** | `kg_add_entity`, `kg_add_relation`, `kg_query`, `kg_timeline`, `kg_stats` | Temporal entity graph with relationships |
-| **Sync** | `sync_status`, `push`, `pull` | Cloud sync operations via MCP |
-| **Thread** | `thread_list`, `thread_show`, `thread_events` | Query thread ledger from within a session |
-| **Memory** | `wake_up`, `compress`, `layers_info` | AAAK compression and layer management |
+## Connect the MCP server
```bash
-# Connect to Claude Code
claude mcp add cloudmem -- python -m cloudmem.mcp_server
```
----
-
-## βοΈ Cloud Sync
+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.
-CloudMem syncs your palace to a private GitHub repository via portable JSON snapshots β not raw ChromaDB files. This means any machine can restore a full palace from the snapshot, rebuilding local embeddings on demand.
+To smoke-test the process itself:
```bash
-# Initial setup (once)
-cloudmem sync-init git@github.com:you/my-palace.git
-
-# Daily workflow (automatic via hooks, or manual)
-cloudmem push # push palace to GitHub
-cloudmem pull # pull latest on same machine
-cloudmem clone # restore on a new machine
+python -m cloudmem.mcp_server
+# waits for JSON-RPC on stdin; Ctrl+C to stop
```
-> **Auto-sync:** The SessionEnd hook runs `session-finalize` which ingests the session transcript and pushes to GitHub automatically. You don't need to remember to sync.
-
----
+## Portable sync
-## π Thread Ledger
-
-AMP-style per-session tracking β duration, prompts, token/cost stats, diff stats, tool usage, and sync status.
+Use an empty **private** Git repository for memory data:
```bash
-cloudmem thread list --limit 20 # recent threads
-cloudmem thread show # detailed view
-cloudmem thread serve --port 8788 # local web UI
+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
```
-### Optional: Cloudflare Remote
+Cross-machine portability uses exported JSON snapshots; the ChromaDB cache is rebuilt locally rather than copied as raw database files.
-Deploy a Cloudflare Worker + D1 + R2 for always-online thread storage:
+You can also manage snapshots directly:
```bash
-cd cloudflare && ./setup.sh
-source ~/.cloudmem/thread_remote.env
+cloudmem export --output palace.json
+cloudmem import palace.json --dry-run
+cloudmem import palace.json
```
-Configure via environment variables:
-
-| Variable | Purpose |
-|----------|--------|
-| `CLOUDMEM_THREAD_REMOTE_URL` | Worker endpoint URL |
-| `CLOUDMEM_THREAD_REMOTE_TOKEN` | Authentication token |
-| `CLOUDMEM_THREAD_REMOTE_HMAC_SECRET` | HMAC signing secret |
-
-See [`docs/thread_cloudflare.md`](docs/thread_cloudflare.md) for full setup.
-
----
+> 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.
-## πͺ Hooks
+## Optional hooks and thread ledger
-CloudMem registers three Claude Code hooks via `node bin/install.mjs`:
+The Node installer registers Claude Code hooks that finalize sessions, create checkpoint prompts, and save before compaction:
-| Hook | Script | What it does |
-|------|--------|--------------|
-| **SessionEnd** | `post-session.sh` | Ingests session transcript into palace, pushes to GitHub |
-| **Stop** | `mempal_save_hook.sh` | Checkpoint save β reminds AI to persist important findings |
-| **PreCompact** | `mempal_precompact_hook.sh` | Saves memory before context compaction to prevent loss |
-
-Hook state is stored in `~/.cloudmem/hook_state`.
-
----
-
-## π Data Paths
-
-All data lives under `~/.cloudmem`:
-
-```
-~/.cloudmem/
-βββ palace/ # Local ChromaDB vector cache (rebuildable from snapshot)
-βββ identity.txt # User identity description
-βββ entity_registry.json # Entity registry
-βββ knowledge_graph.sqlite3 # Temporal knowledge graph
-βββ sessions/ # Session manifests
-βββ palace_export.json # Portable sync snapshot
-βββ hook_state/ # Hook checkpoint state
+```bash
+npm ci
+node bin/install.mjs
```
-> **Portability:** Cross-machine sync uses the JSON snapshot (`palace_export.json`), not raw ChromaDB files. Embeddings are rebuilt locally on import.
-
----
-
-## π₯οΈ Platform Support
-
-| Platform | Status | Notes |
-|----------|--------|-------|
-| **macOS** | β
Fully supported | Primary development platform |
-| **Linux** | β
Fully supported | All features work |
-| **Windows** | β οΈ Via WSL | Hooks and shell scripts require WSL; native support planned |
-
-**Requirements:**
-- Python β₯ 3.9
-- `chromadb >= 0.4.0, < 1.0`
-- `pyyaml >= 6.0`
-- Node.js (for hook installer only)
-- Git (for cloud sync)
-
----
-
-## π Optional Integrations
+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.
-- **[claude-session-tracker](https://github.com/ej31/claude-session-tracker)** β Automatically link sessions to GitHub Issues for project tracking. If not installed, sessions still archive normally; issue metadata is simply empty.
-- **Cloudflare Worker + D1 + R2** β Remote thread storage with an always-online web UI. See [`docs/thread_cloudflare.md`](docs/thread_cloudflare.md).
-
----
-
-## π€ Contributing
+Thread commands:
```bash
-# Clone and install dev dependencies
-git clone https://github.com/raydocs/cloudmem.git
-cd cloudmem
-pip install -e ".[dev]"
-npm install
-
-# Run tests
-pytest
+cloudmem thread list --limit 20
+cloudmem thread show
+cloudmem thread serve --host 127.0.0.1 --port 8788
```
-49 tests, all passing. Please include tests for new features.
-
----
+An optional Cloudflare Worker + D1 + R2 backend is documented in [`docs/thread_cloudflare.md`](docs/thread_cloudflare.md).
+
+## Data and architecture
+
+```text
+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
+```
-## π Credits
+State defaults to `~/.cloudmem/`, including the palace cache, identity/entity files, graph database, snapshots, session manifests, and hook state. See [`docs/INSTALL.md`](docs/INSTALL.md) for platform notes and troubleshooting.
-- **[MemPalace](https://github.com/milla-jovovich/mempalace)** β Palace structure, AAAK dialect, MCP server foundation
-- **[claude-session-tracker](https://github.com/ej31/claude-session-tracker)** β Optional GitHub Issues session tracking integration
+## 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
+## License
-[MIT](https://opensource.org/licenses/MIT) Β© CloudMem Contributors
+`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.
diff --git a/assets/readme/hero.svg b/assets/readme/hero.svg
new file mode 100644
index 0000000..2062958
--- /dev/null
+++ b/assets/readme/hero.svg
@@ -0,0 +1,27 @@
+
+ CloudMem β local AI memory with search, MCP access, and Git-backed snapshots
+ Projects and conversations are filed into a four-level palace, then searched locally or synchronized through portable snapshots.
+
+ LOCAL-FIRST MEMORY SYSTEM Β· PYTHON 3.9+
+ CloudMem
+ Searchable memory that survives the session.
+ Mine locally Β· query over MCP Β· export snapshots Β· sync with Git
+
+
+ $ cloudmem mine ~/projects/my-app
+ $ cloudmem search "why did we change storage?"
+
+
+ PALACE / PORTABLE MEMORY
+ WING project
+ ROOM architecture
+ CLOSET decisions
+ DRAWER source + metadata
+ ChromaDB cache Β· JSON snapshot Β· SQLite graph
+
+
+