@andre.li/memoark 0.3.1 → 0.3.2

package/README.en.md

@@ -1,6 +1,7 @@
 <p align="center">
   <h1 align="center">Memoark</h1>
-  <p align="center"><strong>Turn your Feishu work and AI-agent sessions into one private memory your agents can actually use. Local-first, you own it.</strong></p>
+  <p align="center"><em>You are the sum of your working relationships.</em></p>
+  <p align="center"><strong>A local-first memory system for your work — turning your DMs, group chats, emails, docs, and meetings into a private personal memory, so your AI agents truly know you.</strong></p>
 </p>
 
 <p align="center">
@@ -9,9 +10,10 @@
 
 <p align="center">
   <a href="LICENSE"><img alt="License: Apache 2.0" src="https://img.shields.io/badge/License-Apache_2.0-blue.svg"></a>
+  <a href="https://www.npmjs.com/package/@andre.li/memoark"><img alt="npm" src="https://img.shields.io/npm/v/@andre.li/memoark?color=cb3837&logo=npm"></a>
   <img alt="Runtime: Bun" src="https://img.shields.io/badge/runtime-Bun-black">
   <img alt="Language: TypeScript" src="https://img.shields.io/badge/lang-TypeScript-3178c6">
-  <img alt="Tests: 800+" src="https://img.shields.io/badge/tests-800%2B-success">
+  <img alt="Tests: 1000+" src="https://img.shields.io/badge/tests-1000%2B-success">
 </p>
 
 <p align="center">
@@ -24,11 +26,16 @@
 </p>
 
 <p align="center">
-  <img src="docs/assets/web-ui-graph.jpeg" alt="Memoark knowledge graph — entities, decisions, tasks, and knowledge connected across your work" width="850">
+  <img src="https://raw.githubusercontent.com/AndreLYL/memoark/main/docs/assets/web-ui-graph.jpeg" alt="Memoark knowledge graph — entities, decisions, tasks, and knowledge connected across your work" width="850">
   <br>
   <em>Your work, as a living knowledge graph — people, decisions, tasks, and knowledge, connected.</em>
 </p>
 
+<!-- TODO(demo): replace with an 8-12s demo GIF — ask Memoark a question inside Claude Code
+     and watch the agent recall a Feishu meeting decision + linked task over MCP.
+     Research shows a GIF of "the product actually working" is the single highest-converting
+     element in a README. -->
+
 ---
 
 ## The Problem
@@ -44,7 +51,9 @@ But every time you open a new agent session, it knows nothing. You re-explain wh
 
 ## The Solution
 
-Memoark is a **local-first personal memory system** built on two equal input streams — your **Feishu work** and your **AI-agent sessions**. It extracts structured signals (entities, decisions, tasks, discoveries, knowledge, relationships) into one searchable knowledge graph on your own machine, then serves that memory back to any agent over **MCP**.
+Memoark is a **local-first personal memory system built for the Chinese workplace**. Work in China happens inside Feishu, DingTalk, and WeCom — Memoark pulls the DMs, group chats, emails, meetings, and docs out of these tools, together with your AI-agent sessions, and extracts them into structured signals (entities, decisions, tasks, discoveries, knowledge, relationships) — into one searchable knowledge graph on your own machine, then serves that memory back to any agent over **MCP**.
+
+> The MVP focuses on full **Feishu** capture; **DingTalk, WeCom**, and more Chinese workplace tools are on the roadmap (below).
 
 The result: your agents both **write to** and **read from** the same memory — so Claude Code, Codex, and any MCP client finally *know you and your work*.
 
@@ -69,22 +78,39 @@ The result: your agents both **write to** and **read from** the same memory —
 >
 > Memoark connects these three events automatically — across platforms, across time — and hands the whole thread to your agent on demand.
 
+## Three Pillars
+
+**🔒 Local-first, truly private**
+Your data never leaves your machine. PGLite embedded database stores everything, optional local embeddings via Ollama, zero cloud dependency. Dual-track privacy redaction (reversible / irreversible) scrubs sensitive data before it's written.
+
+**🕸️ An entity knowledge graph, not a pile of vector chunks**
+Signals are anchored to entities (people, projects, tools) and linked in a directed graph. You get answers *with context* — who, why, and what it relates to — instead of isolated similar-text fragments.
+
+**🤖 MCP-native + Feishu capture**
+**29 built-in MCP tools** let any agent both query and write back to your memory. Full Feishu capture (7 sources) turns your real work — requirements, proposals, team decisions — into a first-class data source, something neither pure RAG nor note apps can do.
+
 ## Features
 
 **🛰️ Full Feishu (Lark) Capture**
-Your work lives in Feishu. Memoark collects across **7 sources** — DMs, group chats, email, calendar, docs, tasks, and message search — turning your working relationships into structured memory.
+Your work lives in Feishu. Memoark collects across **7 sources** — DMs, group chats, email, calendar, docs, tasks, and message search — turning your working relationships into structured memory. Doc capture produces upgradable "summary cards" (DocSource v2).
 
 **🤖 Agents That Know You (MCP)**
-Use Memoark as the memory layer for any MCP agent — Claude Code, Cursor, Windsurf. **17 built-in tools** let your agent query your history, read entity pages, and write new knowledge back. Agents are both producers and consumers of your memory.
-
-**🔒 Private & Local-First**
-Your data never leaves your machine. PGLite embedded database, optional local embeddings via Ollama, no cloud dependency. You own your memory.
+Use Memoark as the memory layer for any MCP agent — Claude Code, Cursor, Claude Desktop, Windsurf. **29 built-in tools** let your agent query your history, read entity pages, and write new knowledge back. Agents are both producers and consumers of your memory.
 
 **🧠 AI-Powered Signal Extraction**
 An LLM pipeline extracts 7 types of structured signals from raw conversations: entities, timeline events, decisions, tasks, discoveries, knowledge, and relationships.
 
 **🔍 Hybrid Semantic Search**
-Full-text search + vector retrieval fused with Reciprocal Rank Fusion (RRF). Ask in natural language — powered by PGLite FTS + pgvector.
+Full-text search (tsvector, multilingual) + vector retrieval fused with Reciprocal Rank Fusion (RRF). Ask in natural language — powered by PGLite FTS + pgvector.
+
+**♻️ Memory Consolidation (Dream Cycle)**
+A background consolidator automatically runs tier rotation (hot → warm → cold), repairs dead links, and infers preferences — so your memory organizes itself over time.
+
+**⏰ Resident Daemon + Scheduled Capture**
+A built-in daemon collects from your sources on a schedule, with run history and alerts, keeping your memory continuously fresh.
+
+**🔗 Obsidian Bidirectional Sync**
+Export your memory pages to an Obsidian vault (Markdown), edit them, and import them back.
 
 **🕸️ Knowledge Graph + Web UI**
 See the connections between people, projects, and decisions. Browse a built-in web UI with dashboard, timeline, force-directed graph, and search.
@@ -92,16 +118,112 @@ See the connections between people, projects, and decisions. Browse a built-in w
 **🔌 REST API**
 Full Hono-powered HTTP API for all store operations. Integrate with any client.
 
+## Works With
+
+Memoark is a standard MCP stdio server and plugs into any MCP client:
+
+**Claude Code** · **Cursor** · **Claude Desktop** · **Windsurf** · and any MCP-compatible agent.
+
+## Feature Inventory
+
+The full capability list (✅ = shipped and included in the package).
+
+### 📥 Data Collection
+- ✅ Feishu group chats (OpenAPI chat/message)
+- ✅ Feishu DMs / recent chats (lark-cli `message_search`, user mode)
+- ✅ Feishu email
+- ✅ Feishu calendar events
+- ✅ Feishu tasks
+- ✅ Feishu doc summary cards (DocSource v2: pointer card → upgraded full card on trigger)
+- ✅ Claude Code sessions (`~/.claude/projects/`)
+- ✅ Codex CLI sessions (`~/.codex/`)
+- ✅ OpenClaw Hermes multi-agent sessions (`~/.openclaw/agents/`, auto sub-agent discovery)
+- ✅ Incremental collection: per-source cursor + content-hash dedup
+- ✅ Historical backfill: coverage stats, start / cancel / reset
+
+### 🧠 Signal Extraction Pipeline
+- ✅ Collect → Dedup → Block Builder → Noise Filter → Signal Extractor → Privacy
+- ✅ Two-layer noise filtering: L1 rules + L2 LLM scoring
+- ✅ 7 structured signal types: entities, timeline, decisions, tasks, discoveries, knowledge, relationships
+- ✅ LLM providers: OpenAI / Anthropic (plus a mock for testing)
+- ✅ Signal scoring and entity extraction
+- ✅ JSON / Markdown output formats
+- ✅ Output adapters: store (PGLite) / file / gbrain / stdout
+- ✅ Provenance: every signal traces back to its source message
+
+### 🔒 Privacy & Security
+- ✅ Redaction before write; data stays fully local
+- ✅ Dual-track modes: reversible / irreversible
+- ✅ Built-in redaction: phone, ID card, bank card, with custom replacement token
+- ✅ API keys always masked in the config center
+
+### 🗄️ Storage & Retrieval
+- ✅ PGLite embedded PostgreSQL (in-process, zero external deps)
+- ✅ pgvector vector search
+- ✅ tsvector full-text search (simple tokenizer, multilingual)
+- ✅ RRF hybrid search (FTS + vector fusion) with compiled_truth / backlink boosts
+- ✅ Recursive chunking (300 words / 50-word overlap), embedding reuse + stale detection
+- ✅ Embeddings: OpenAI / Ollama (local)
+
+### 🕸️ Knowledge Graph
+- ✅ Directed link graph with link types and context
+- ✅ BFS traversal (controllable depth / direction)
+- ✅ Backlinks
+- ✅ Entity anchoring: signals attach to people / projects / tools
+- ✅ Entity profile aggregation (signals + timeline)
+
+### 👤 Person Identity
+- ✅ Identity resolution and canonicalization
+- ✅ Alias / handle linking (Feishu open_id, email, name, nickname, slug)
+- ✅ Strong / weak link strength
+- ✅ Person merge (re-points links / timeline / tags / aliases)
+- ✅ Recanonicalize slug (fix a wrong canonicalization)
+
+### ♻️ Memory Lifecycle & Daemon
+- ✅ Memory consolidation (dream cycle): hot → warm → cold tier rotation
+- ✅ Dead-link repair
+- ✅ Preference inference (learns preferences from history)
+- ✅ Resident daemon: scheduled per-source capture, scheduling, run history, alerts
+
+### 🔗 Sync & Interop
+- ✅ Obsidian bidirectional sync (export vault / import back)
+- ✅ MCP stdio server (29 tools)
+- ✅ REST API (Hono — pages / search / graph / tags / timeline / embed / extract / provenance / event stream)
+
+### 🖥️ Web UI (React + Vite)
+- ✅ Dashboard overview
+- ✅ Timeline view (feed)
+- ✅ Force-directed knowledge graph
+- ✅ Search interface
+- ✅ Entity / page detail
+- ✅ In-browser config editing + guided setup wizard
+
+### ⚙️ Configuration & Onboarding
+- ✅ Interactive config center (full-screen TUI, React + ink)
+- ✅ Linear Q&A wizard fallback (`--no-tui`) / fully automatic (`--auto`)
+- ✅ Auto-detection: runtime, API keys, existing data sources
+- ✅ Hardware assessment → recommends local / remote embeddings
+- ✅ Live connection checks (LLM / embedding API key and connectivity)
+- ✅ `memoark doctor` environment diagnostics
+
 ## Use Cases
 
-**Onboard your agent to a project in seconds**
-Start a Claude Code session and ask *"what's the current state of the memoark project?"* — your agent pulls the aggregated decisions, open tasks, and recent timeline straight from your memory, no re-explaining.
+> Memoark answers not "what do I know" but "**what should I do**" — every scenario returns a cited, traceable action, not a pile of chunks.
+
+**🌟 Know how to talk to someone before you meet them (Hero)**
+*"I'm meeting Director Zhang tomorrow to negotiate a renewal price increase — what should I keep in mind?"* — `prep_for_person` **passively infers** a communication profile from your real interactions (direct vs. indirect, data-driven vs. relationship-driven, landmines), tailors advice to this goal, and flags gaps (*"nothing new about Zhang in 18 days — the profile may be stale"*). Zero questionnaire; the profile never leaves your machine.
 
-**Recall a person or a thread**
-*"What did I discuss with my colleague last week?"* — Memoark stitches together the Feishu DMs, the meeting, and the follow-up task into one answer.
+**📋 Generate a cross-channel daily report in one line**
+*"Help me write today's daily report"* — `daily_report` aggregates today's signals scattered across DMs, group chats, email, Feishu Minutes notes, and calendar into 7 sections: decisions / in-progress / my tasks / awaiting-reply·@mentions / relationship updates / tomorrow's reminders. Action items in meeting notes that name you land in "my tasks" automatically.
 
-**Auto-written work log**
-Browse your timeline like a diary that writes itself — what you decided, what you shipped, and across which platforms.
+**🔧 Troubleshoot by the playbook**
+*"Why won't the ADAS engage?"* — `troubleshoot` walks the playbook's diagnostic chain (`precedes`) to give ordered steps and explain what each result means. Playbooks can be authored by hand or auto-extracted (as drafts) from your troubleshooting conversations.
+
+**⚡ Onboard your agent to a project in seconds**
+*"What's the current state of the memoark project?"* — `get_session_context` pulls the aggregated decisions, open tasks, and recent timeline straight from memory, no re-explaining.
+
+**🔎 Recall a person or a thread**
+*"What did I discuss with this colleague last week?"* — stitches Feishu DMs, the meeting, and the follow-up task into one cited answer.
 
 ## Why Memoark
 
@@ -114,9 +236,9 @@ Browse your timeline like a diary that writes itself — what you decided, what
 | Agent-native: read **and** write over MCP | ✅ | ❌ | ❌ | ✅ | partial |
 | Entity + relationship knowledge graph | ✅ | ❌ | manual | ✅ | partial |
 | Structured signal extraction (not just chunks) | ✅ | ❌ | ❌ | ✅ | ✅ |
-| Focused MCP surface (17 tools, not 40+) | ✅ | n/a | n/a | ❌ (40+) | varies |
+| Memory consolidation + scheduled-capture daemon | ✅ | ❌ | ❌ | partial | partial |
 
-> Pure RAG gives you vectors but no entities or relationships, so answers lack context. Note apps are powerful but rely on manual upkeep. GBrain is capable but heavy, with a sprawling MCP surface. Memoark keeps it local, focused, and agent-native — with Feishu work as a first-class source.
+> Pure RAG gives you vectors but no entities or relationships, so answers lack context. Note apps are powerful but rely on manual upkeep. Memoark keeps it local and agent-native — with Feishu work as a first-class source.
 
 ## Quick Start
 
@@ -125,6 +247,28 @@ Browse your timeline like a diary that writes itself — what you decided, what
 - [Node.js](https://nodejs.org) >= 18 (for the `npx` / `npm` install)
 - (Optional) [Ollama](https://ollama.ai) for local embeddings
 
+### One-step launch (recommended)
+
+```bash
+# Run without installing — no config? it auto-launches the setup wizard,
+# then starts the server and opens your browser
+npx @andre.li/memoark start
+
+# Running with no subcommand is equivalent to `start`
+npx @andre.li/memoark
+```
+
+`memoark start` is the single-step path: if there's no `memoark.yaml`, it opens the browser setup wizard first, then starts the HTTP server and auto-opens your browser.
+
+> The npm package is `@andre.li/memoark` (scoped), but the command is still `memoark`.
+
+### Ports at a glance
+
+| Service | Default port | Address |
+|---------|--------------|---------|
+| HTTP API + Web UI | `3927` | `http://localhost:3927` |
+| MCP Streamable HTTP (`--mcp-http`) | `3928` | `http://localhost:3928/mcp` |
+
 ### Install (recommended: npm)
 
 ```bash
@@ -135,8 +279,6 @@ npx @andre.li/memoark --help
 npm install -g @andre.li/memoark
 ```
 
-> The npm package is `@andre.li/memoark` (scoped), but the command is still `memoark`.
-
 ### Install from source (development)
 
 ```bash
@@ -211,16 +353,58 @@ memoark search "JWT token" --mode fts
 ### Start the Server
 
 ```bash
-# HTTP API (default port 3927)
+# HTTP API + Web UI (default http://localhost:3927) — auto-opens your browser
 memoark serve
 
-# MCP stdio (for AI agent integration — Claude Code, Cursor, etc.)
+# Skip the auto-open (e.g. on a remote/headless host)
+memoark serve --no-open
+
+# MCP stdio (local direct connect for AI agents — Claude Code, Cursor, etc.; no browser)
 memoark serve --mcp
+
+# MCP Streamable HTTP (remote / multi-client, default http://localhost:3928/mcp; no browser)
+memoark serve --mcp-http
 ```
 
+> Without a `memoark.yaml`, `serve` tells you to run `memoark start` for one-step setup + launch, or `memoark init --web` to configure first.
+
 ### Connect Your Agent (MCP)
 
-Point any MCP client at Memoark so it can read and write your memory. For Claude Code:
+**One command (recommended)**: `memoark install` writes the MCP config plus a tiny memory directive into your AI client (**global by default**, across all projects). Supports **Claude Code · Claude Desktop · Cursor · Codex · Windsurf**:
+
+```bash
+memoark install                      # detect installed clients and wire them up
+memoark install --agent claude-code  # target a single client
+memoark install --dry-run            # preview file changes, write nothing
+memoark uninstall                    # clean removal (idempotent)
+```
+
+Reopen the client and you're set — ask "what did X tell me last week?" or "where is this project at?" and the agent will **proactively query Memoark** per the injected directive (cheap-first: `search` keyword lookup at zero cost, escalating to `query`/`recall` only if thin) instead of guessing.
+
+> Claude Desktop has no rules file, so it relies on the MCP server's `instructions` field. You can also configure things manually below.
+
+**Automatic recall on Claude Code (optional · hooks)**: go further on Claude Code so memory arrives with zero effort:
+
+```bash
+memoark hooks install               # SessionStart + UserPromptSubmit read hooks (on by default)
+memoark hooks install --write-back  # also enable end-of-session auto write-back (opt-in)
+memoark hooks uninstall             # remove
+```
+
+- **SessionStart**: injects an "active projects / decisions / open tasks / key people" digest at the start of each session (the always-on core).
+- **UserPromptSubmit**: a **zero-cost FTS** probe before each prompt; injects only on a hit (≤3 items, ≤3000 chars, appended after the user message to preserve prompt cache).
+- **SessionEnd** (`--write-back`, off by default): asynchronous incremental extraction back into memory, so it compounds.
+
+> Read hooks default on (local, cheap); write-back is explicit `--write-back` (cost + privacy, opt-in). Other clients have no lifecycle hooks and rely on the instruction layer above for model-initiated recall.
+
+**Let the agent install itself**: for agents that can read a URL, just say "onboard me to Memoark following [`MEMOARK_FOR_AGENTS.md`](MEMOARK_FOR_AGENTS.md)" and it runs the commands above and self-checks. For **OpenClaw / Hermes**, use `memoark install --agent hermes` (writes `mcp_servers` into `config.yaml` + drops the `memoark` skill; run `/reload-mcp` in-session to apply); or scaffold the skill alone with `memoark skill scaffold --dir ~/.hermes/skills`.
+
+Memoark offers two MCP transports — pick by scenario:
+
+- **stdio (`--mcp`)** — local direct connect; the agent spawns `memoark` as a subprocess. Zero network setup; best for a single client on one machine.
+- **Streamable HTTP (`--mcp-http`)** — over HTTP (default `3928`); use it for remote access or sharing one memory across multiple clients.
+
+Point any MCP client at Memoark so it can read and write your memory. For Claude Code (stdio, local direct connect):
 
 ```json
 {
@@ -245,39 +429,75 @@ bun run dev        # dashboard, timeline, knowledge graph, search
 
 ## Architecture
 
+Memoark is **5 vertical data-flow layers + 3 cross-cutting concerns**. Data flows top-down: sources are collected, extracted into signals, stored as local memory, then read/written through the bottom interfaces. **Person identity**, **consolidation**, and **scheduling** cut across the stack.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/AndreLYL/memoark/main/docs/assets/architecture.png" alt="Memoark architecture — 5 vertical layers + 3 cross-cutting concerns" width="920">
+</p>
+
+<details>
+<summary>📐 View the editable Mermaid source</summary>
+
+```mermaid
+flowchart TB
+  subgraph L1["① Config & Onboarding"]
+    cfg["TUI config center · Web UI config · memoark.yaml<br/>auto-detect · hardware assessment · connection checks"]
+  end
+  subgraph L2["② Collection"]
+    feishu["Feishu: DMs · groups · email · calendar · tasks · message search · docs"]
+    agent["AI-agent sessions: Claude Code · Codex · Hermes"]
+    inc["Incremental (cursor + dedup) · historical Backfill"]
+    planned1["Planned: DingTalk · WeCom · local documents"]:::planned
+  end
+  subgraph L3["③ Extraction Pipeline"]
+    pipe["Block Builder → Noise Filter (rules+LLM) → Signal Extractor (OpenAI/Anthropic)<br/>→ entity extraction → scoring → privacy redaction → 7 signal types"]
+  end
+  subgraph L4["④ Memory Store"]
+    store["PGLite + pgvector<br/>Page · Chunk · Tag · Timeline · Graph<br/>hybrid search (FTS + vector + RRF)"]
+  end
+  subgraph L5["⑤ Interfaces & Consumption"]
+    cli["CLI"]
+    mcp["MCP (29 tools)"]
+    rest["REST API"]
+    web["Web UI (read-only)"]
+    obs["Obsidian bidirectional sync"]
+  end
+
+  L1 --> L2 --> L3 --> L4 --> L5
+
+  subgraph X["Cross-cutting concerns"]
+    id["🧬 Person Identity<br/>merge same person across platforms"]
+    cons["♻️ Consolidation / Dream Cycle<br/>tier rotation · dead-link repair · preference inference"]
+    sched["⏰ Scheduling / AutoFetch<br/>scheduled capture · run history · alerts"]
+  end
+
+  id -.-> L2
+  id -.-> L4
+  cons -.-> L4
+  sched -.-> L2
+
+  classDef planned stroke-dasharray: 5 5,fill:#f6f6f6,color:#888;
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│                        Data Sources                             │
-│   Feishu (DMs · groups · email · calendar · docs · tasks)       │
-│   AI Agents (Claude Code · Codex · Hermes)                      │
-└───────────────────────────────┬─────────────────────────────────┘
-                                │
-                      ┌─────────▼──────────┐
-                      │   Signal Extraction │
-                      │   Pipeline          │
-                      │                    │
-                      │  Collector          │
-                      │  → Dedup            │
-                      │  → Block Builder    │
-                      │  → Noise Filter     │
-                      │  → Signal Extractor │
-                      │  → Privacy          │
-                      └─────────┬──────────┘
-                                │
-                      ┌─────────▼──────────┐
-                      │   Storage Layer     │
-                      │  PGLite + pgvector │
-                      │  (Embedded PG)     │
-                      └─────────┬──────────┘
-                                │
-            ┌───────────────────┼───────────────────┐
-            │           │               │           │
-   ┌────────▼─────┐ ┌───▼────┐ ┌────────▼───┐ ┌─────▼──────┐
-   │     CLI       │ │  MCP   │ │  REST API  │ │  Web UI    │
-   │  Management   │ │ Server │ │   (Hono)   │ │  (React)   │
-   │  & Extraction │ │(stdio) │ │            │ │            │
-   └───────────────┘ └────────┘ └────────────┘ └────────────┘
-```
+
+</details>
+
+### Layer Breakdown
+
+| Layer | Responsibility |
+|-------|----------------|
+| **① Config & Onboarding** | TUI config center (React + ink), Web UI config, hand-edited `memoark.yaml`; auto-detect runtime / API keys / sources, hardware-aware embedding recommendation, live connection checks |
+| **② Collection** | Feishu (DMs / groups / email / calendar / tasks / message search / docs), AI-agent sessions (Claude Code / Codex / Hermes); incremental capture (per-source cursor + content dedup), historical Backfill. **Planned**: DingTalk, WeCom, local documents |
+| **③ Extraction Pipeline** | Block Builder → Noise Filter (L1 rules + L2 LLM) → Signal Extractor (OpenAI / Anthropic) → entity extraction → scoring → privacy redaction; emits 7 signal types via output adapters (store / file / gbrain / stdout) |
+| **④ Memory Store** | PGLite (in-process embedded PostgreSQL) + pgvector; Page / Chunk / Tag / Timeline / Graph stores; hybrid search (tsvector FTS + vector + RRF) |
+| **⑤ Interfaces & Consumption** | CLI, MCP Server (29 tools — agent read / write / maintain), REST API (Hono), Web UI (search / view / graph / timeline, **read-only today**), Obsidian bidirectional sync |
+
+**Cross-cutting concerns (span layers, not standalone pipeline stages):**
+
+- **🧬 Person Identity** — spans Collection ↔ Store: recognize and merge the same person across platforms (Feishu open_id, email, nickname), alias linking, canonicalization. The foundation of "the sum of your social relations".
+- **♻️ Consolidation (Dream Cycle)** — background pass over the store: hot → warm → cold rotation, dead-link repair, preference inference.
+- **⏰ Scheduling / AutoFetch** — background driver of Collection: scheduled capture, run history, alerts. *(Runs inside `serve` today; standalone daemon + autostart is on the roadmap.)*
+
+> Runs on macOS / Linux / Windows · one-command install (npm / npx) · local-first, self-hosted, zero cloud dependency.
 
 ### Signal Extraction Pipeline
 
@@ -314,8 +534,42 @@ bun run dev        # dashboard, timeline, knowledge graph, search
 | **TimelineStore** | Chronological entries per page with dedup |
 | **EmbeddingService** | Batch embedding via OpenAI or Ollama, stale-chunk detection |
 
+## MCP Tools
+
+Memoark's MCP server exposes **29 tools** spanning retrieval, synthesis, page CRUD, graph, tags, timeline, identity, and Feishu doc ingestion. Prefer the high-level tools first:
+
+| Category | Tools |
+|----------|-------|
+| **Retrieval (high-level)** | `query`, `get_session_context`, `get_entity_profile`, `list_signals_by_entity` |
+| **Synthesis** | `synthesize`, `recall` (cited, gap-aware composed answers with inline `[n]`), `prep_for_person` (person communication profile → goal-conditioned strategy; passively inferred, no questionnaire, local-first, ethics-guardrailed), `daily_report` (cross-channel 7-section daily report), `troubleshoot` (one-shot diagnosis along a playbook chain) |
+| **Search** | `search` |
+| **Pages / content** | `get_page`, `put_page`, `list_pages`, `get_chunks` |
+| **Graph** | `add_link`, `remove_link`, `get_links`, `get_backlinks`, `traverse_graph` |
+| **Tags** | `add_tag`, `remove_tag`, `get_tags` |
+| **Timeline** | `add_timeline_entry`, `get_timeline` |
+| **Identity (people)** | `link_person_alias`, `list_person_handles`, `remove_person_alias`, `merge_persons`, `recanonicalize_person` |
+| **Feishu docs** | `ingest_feishu_doc` |
+| **Health** | `get_health` |
+
 ## CLI Reference
 
+| Command | Description |
+|---------|-------------|
+| `memoark start` | One-step launch: setup if needed, then serve + auto-open browser (bare `memoark` is equivalent) |
+| `memoark init` | Interactive config center to generate / edit `memoark.yaml` (`--auto` / `--no-tui` / `--force` / `--web`) |
+| `memoark extract` | Extract signals from a data source |
+| `memoark search <query>` | Search memory (hybrid / `--mode fts`) |
+| `memoark embed` | Generate embeddings for stale chunks |
+| `memoark serve` | Start HTTP API (auto-opens browser, `--no-open` to skip) / `--mcp` stdio / `--mcp-http` |
+| `memoark consolidate` | Run memory consolidation (tier rotation hot→warm / warm→cold) |
+| `memoark export` | Export memory pages to an Obsidian vault (Markdown) |
+| `memoark import` | Import an Obsidian vault back into Memoark |
+| `memoark docs` | Feishu doc summary cards: `sync` / `status` / `retry` |
+| `memoark identity` | Person identity: aliases, merge, rename |
+| `memoark sources` | `list` sources / `test <name>` connectivity |
+| `memoark doctor` | Diagnose configuration and connectivity |
+| `memoark config` | `init` (alias of `memoark init`) / `edit` (browser UI) |
+
 ### `memoark extract`
 
 Extract signals from data sources.
@@ -331,16 +585,31 @@ memoark extract \
   --dry-run                    # Test without LLM calls or writes
 ```
 
+### `memoark start`
+
+One-step launch. If no `memoark.yaml` exists, it opens the browser setup wizard first; once configured, it starts the HTTP server and auto-opens your browser. Running `memoark` with no subcommand does the same thing.
+
+```bash
+memoark start
+memoark              # equivalent
+```
+
 ### `memoark serve`
 
 Start the Memoark server.
 
 ```bash
-# HTTP API (default port from config)
+# HTTP API + Web UI (default http://localhost:3927) — auto-opens the browser
 memoark serve
 
-# MCP stdio transport (for AI agent integration)
+# Skip the auto-open
+memoark serve --no-open
+
+# MCP stdio transport (local direct connect for AI agents)
 memoark serve --mcp
+
+# MCP Streamable HTTP transport (remote / multi-client, default http://localhost:3928/mcp)
+memoark serve --mcp-http
 ```
 
 ### `memoark search <query>`
@@ -402,6 +671,36 @@ Test data source connectivity.
 memoark sources test claude-code
 ```
 
+### `memoark consolidate`
+
+Run memory lifecycle tier rotation (the "dream cycle").
+
+```bash
+memoark consolidate          # hot→warm and/or warm→cold rotation
+```
+
+### `memoark export` / `memoark import`
+
+Bidirectional Obsidian sync.
+
+```bash
+memoark export   # memory pages → Obsidian vault (Markdown)
+memoark import   # Obsidian vault → Memoark
+```
+
+### `memoark docs`
+
+Feishu doc summary cards (DocSource v2) — build lightweight pointer cards first, then upgrade triggered docs to full summary cards.
+
+```bash
+memoark docs sync                # scan docs, build pointer cards, upgrade triggered docs
+memoark docs status              # show card counts by type
+memoark docs retry <doc_token>   # retry a failed full-card extraction
+memoark docs retry --all-failed  # retry every failed doc
+```
+
+Agents can also ingest a single doc directly via the MCP tool `ingest_feishu_doc` (pass a doc URL or token).
+
 ## Configuration
 
 ### `memoark.yaml`
@@ -527,7 +826,7 @@ Extracts session data from OpenClaw Hermes agents.
 - [x] EmbeddingService (OpenAI / Ollama)
 - [x] StoreAdapter — pipeline writes directly to PGLite
 - [x] Hono REST API
-- [x] MCP Server with 17 stdio tools
+- [x] MCP Server with 29 stdio tools
 - [x] CLI serve, search, embed commands
 
 ### Phase 3 — Web UI (Complete)
@@ -538,23 +837,42 @@ Extracts session data from OpenClaw Hermes agents.
 - [x] Search interface
 - [x] Entity / page detail views
 
-### Phase 4 — Context-Aware Extraction (Planned)
+### Phase 4 — Consolidation & Daemon (Complete)
+
+- [x] Memory consolidation ("dream cycle"): tier rotation, dead-link repair, preference inference
+- [x] Resident daemon with scheduled extraction (scheduler, run history, alerts)
+- [x] Person identity management (aliases, merge, rename)
+- [x] Feishu doc summary cards (DocSource v2)
+- [x] Obsidian bidirectional sync (export / import)
+
+### Phase 5 — Self-Hosted Always-On (In Progress · MVP)
 
+- [ ] Standalone daemon service + autostart (systemd / launchd / Windows service) — "configure once, runs maintenance-free"
+- [ ] Agent Hook: auto read/write memory on session end / key decisions
+
+### Phase 6 — More Chinese Workplace Sources (Planned)
+
+- [ ] DingTalk
+- [ ] WeCom (WeChat Work)
+- [ ] WeChat chat history
+- [ ] Local document source (scan local files, community-driven · low priority)
+
+### Phase 7 — Context-Aware Extraction & Q&A (In Progress)
+
+- [x] Synthesis layer (basic): `synthesize` / `recall` — cited composed answers with inline `[n]` + gap analysis, intent-template framework, per-scope caching
+- [x] **Person communication profile (Hero)**: `prep_for_person(person, goal?)` — passively infers a communication profile from real interactions (zero-LLM behavior layer + behavior-quadrant trait layer + relation layer + four-color shell) and gives goal-conditioned, `[n]`-cited communication strategy. No questionnaire, local-first, ethics-guardrailed (suggestions, not manipulation); disabled by default, per-person opt-in
+- [x] **Cross-channel daily report**: `daily_report(date?)` — aggregates today's signals across DMs/group/email/Feishu Minutes/calendar into 7 sections; meeting notes yield `decisions` and owner-tagged `action_items` (yours land in "my tasks")
+- [x] **Troubleshooting Playbooks**: `troubleshoot(query)` — ordered steps along the playbook `precedes` chain with per-result meaning; hierarchical tree (`part_of`) organizes problem domains; playbooks authored by hand or auto-extracted (draft) from conversations
+- [x] **Retrieval quality**: best-chunk-per-page pooling (surface on strongest evidence), zero-LLM self-wiring (`[[slug]]`/`[[rel:slug]]` graph edges on write), rule-based query rewrite
 - [ ] ContextBuffer — share context across conversation blocks
 - [ ] Weighted admission scoring (replaces binary noise filter)
 - [ ] Narrative assembler — aggregate signals into per-entity narratives
-
-### Phase 5 — Consolidation & Daemon (Planned)
-
-- [ ] Memory consolidation ("dream cycle"): entity merge, link repair, pattern discovery
-- [ ] Resident background service with scheduled extraction
 - [ ] Natural language Q&A over stored memories
 
-### Phase 6 — Sync & New Sources (Planned)
+### Phase 8 — Web UI Enhancements (Planned)
 
-- [ ] Obsidian bidirectional sync
-- [ ] WeChat chat history
-- [ ] More platforms based on community demand
+- [ ] Memory editing (read-only today)
+- [ ] Audit view (signal provenance visualization)
 
 ## Tech Stack
 
@@ -569,7 +887,7 @@ Extracts session data from OpenClaw Hermes agents.
 | Web UI | React + Vite |
 | MCP | @modelcontextprotocol/sdk |
 | Linter | Biome |
-| Tests | Vitest (800+ tests) |
+| Tests | Vitest (1000+ tests) |
 
 ## Development
 
@@ -600,6 +918,7 @@ Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) before sub
 
 - 🐛 Found a bug or have a feature request? [Open an issue](https://github.com/AndreLYL/memoark/issues).
 - 💡 Questions and ideas are welcome in the issue tracker.
+- ⭐ If Memoark helps you, give it a Star — it's the best way to support the project.
 
 ## License