MineEcho

A local-first Memory OS for personal AI assistants: remember, learn, use skills, and spend fewer tokens.

中文文档

MineEcho is a source-available, local-first AI assistant framework for building private, extensible assistant workflows on top of local services and user-owned knowledge.

MineEcho is not meant to be just another chat UI. Its product loop is:

Remember user preferences and past work.
Learn from imported knowledge through Wiki++ and graph context.
Use skills and external AI apps through one routing surface.
Save context cost with TokenLess reducers and local metrics.

Use MineEcho when a normal chat UI is too forgetful, a RAG app is too passive, and an agent framework is too noisy to run as a long-term personal assistant.

Why MineEcho

| Common product shape | Typical gap | MineEcho difference | |----------------------|-------------|---------------------| | Chat UI | No durable memory, tools and knowledge stay separate | Memory tree + knowledge base + skill routing + cost layer | | RAG knowledge base | Fragmented chunks, little action capability | raw/wiki storage, four-channel retrieval, AI apps as callable skills | | Agent tool framework | Tool output is noisy and context-heavy | TokenLess keeps key errors, counts, and actionable lines | | Enterprise AI app portal | Apps become silos | AI apps are converted into skills with triggers, routing, and health checks |

What Makes It Different

• Memory-first assistant loop: MineEcho stores raw interaction memory, daily/weekly/monthly summaries, semantic recall evidence, and memory-to-knowledge alignment instead of treating every chat as disposable.
• Wiki++ knowledge system: imported sources become raw files, wiki pages, chunk indexes, graph nodes, and alignment candidates, so knowledge stays inspectable rather than becoming opaque vector chunks.
• Skill and AI app convergence: external AI apps are registered as callable skills and participate in the same trigger, routing, health, and workflow surface as local skills.
• TokenLess cost layer: long command logs, tool outputs, URL imports, and document extraction results are compressed by scenario-aware reducers before they enter memory or context.
• Local-first release posture: runtime data, provider keys, chat history, audio, and metrics live under local MineEcho state and are excluded from the release tree.

The project is designed around four baseline ideas:

• Skill routing: route user intent to focused capabilities instead of pushing every task through one general prompt.
• Memory distillation: compact interaction history into durable working memory while keeping raw transcripts optional and local.
• Wiki and graph knowledge base: organize notes, entities, and relationships into a browsable knowledge layer that can support retrieval and reasoning.
• Cost controls: keep local defaults, explicit provider configuration, and bounded memory/performance settings so experimentation does not silently become expensive.

Current Capabilities

• Local console and BFF for chat, skills, memory, knowledge base, calendar/meeting helpers, and configuration.
• Skill center with JSON skill import, ZIP/.skill package import, URL install, AI app registration, trigger refresh, and routing preview APIs.
• AI app adapters that convert RAG/workflow apps into Gateway-callable skills.
• Memory-to-knowledge alignment preview, commit history, and knowledge graph refresh hooks.
• Knowledge graph neighborhood API for explaining selected nodes and one-hop relationships.
• TokenLess compression metrics with local persistence.

Core Highlights

Memory: runtime memory plus L0-L3 memory tree

MineEcho separates memory into two complementary views:

• Working / Short-term / Long-term: current session, daily interactions, cross-session profile and insights.
• L0 / L1 / L2 / L3 Memory Tree: raw memory chunks, daily summaries, weekly summaries, and monthly archives.

When a user asks a question, MineEcho recalls recent L0 chunks with keyword, semantic, local-vector, importance, and recency scoring, then reranks the top candidates with the configured embedding provider when available. L1/L2 summaries pass a local semantic gate before embedding-enhanced ranking, which reduces unrelated long-term context injection.

Wiki++ knowledge base

MineEcho's knowledge base is organized as raw source files plus AI-maintained wiki pages. Query-time retrieval uses four channels:

1. Vector search for semantic similarity.
2. BM25 for Chinese/English keyword matching.
3. Structured search over title, type, tags, and headings.
4. Graph channel search over entities and one-hop neighborhoods.

This makes it closer to a high-density, maintainable AI knowledge substrate than a simple chunk-only RAG store.

Skills and AI apps as one capability layer

Native skills, imported skills, and registered AI apps enter the same registry. AI apps are converted into Gateway-callable skills, triggers are derived from name + description, and the router scores trigger, name, description, and mode evidence before returning candidates. AI apps therefore participate in the same routing and workflow surface as local skills.

TokenLess cost controls

TokenLess ships with 15 built-in reducer rules for git, npm, cargo, docker, document extraction, and generic long output. It keeps errors, counts, head/tail context, and actionable lines instead of blindly truncating output. Based on the current rule structure, long tool/document outputs commonly fall into an estimated 20%-85% token-saving range depending on repetition and output shape; MineEcho records raw/reduced characters and estimated tokens saved locally for real workload measurement.

Quick Start

This is the full path for first-time users.

1. Prepare your machine

Install:

• Git
• Node.js 22 or later
• npm, usually bundled with Node.js

Check versions:

git --version
node -v
npm -v

If node -v is lower than 22, upgrade Node.js first.

2. Clone the repository

git clone https://github.com/Health-Yang/MineEcho.git
cd MineEcho

3. Install dependencies

npm run install:apps

This installs dependencies for BFF, Console, and the vendored OpenClaw Gateway runtime under vendor/openclaw-gateway. MineEcho ships the OpenClaw Gateway runtime source in this repository, so users do not need to install OpenClaw separately.

4. Create local environment files

cp apps/bff/.env.example apps/bff/.env
# Optional, only when you need to override Console defaults:
# cp apps/console/.env.example apps/console/.env

MineEcho does not ship real model API keys. You can start without keys first, then configure model providers in the Console settings page.

5. Start development services

npm run dev

The development URLs are:

• Console: http://127.0.0.1:5175/
• BFF: http://127.0.0.1:3085/

The checked-in Vite dev config proxies /api to the local BFF.

On first launch, open the Console and complete model/API key configuration in Settings. Keep real provider keys in local .env files or local Console settings, not in Git.

6. Debug BFF or Console separately

You can start the two apps separately when debugging one side:

npm run dev:bff
npm run dev:console

7. Verify and build

Build checks:

npm run build

Start the built BFF package:

npm run start:bff

Full verification:

npm run verify

Runtime smoke check, after npm run dev is running:

npm run smoke

Dependency audit for release-blocking advisories:

npm run audit:apps

Export a filtered source tree for public release:

npm run export:release

The export command writes to releases/mineecho-source-<version>/ and checks that local runtime data, .env files, databases, keys, logs, and cache artifacts are not included. Publish from the export directory or a fresh clone, not from a local development tree.

Local-First Defaults

MineEcho should run against loopback services by default. Secrets, provider API keys, production endpoints, and user data belong in ignored local environment files, not in source control.

Start from the example environment files and copy only the settings needed for your machine:

cp apps/bff/.env.example apps/bff/.env
# Optional:
# cp apps/console/.env.example apps/console/.env

Then edit .env locally. Keep any real tokens or service credentials out of commits.

Local development does not force the console login screen by default. Set VITE_MINEECHO_AUTH_REQUIRED=true when you need to test the auth flow explicitly.

The BFF defaults to port 3085. Override it with BFF_PORT only if you also update the Console proxy target.

The following runtime directories are intentionally ignored and should stay out of source control:

• .mineecho/
• .openclaw/
• apps/**/.mineecho/
• apps/**/.openclaw/
• apps/**/workspace/

MineEcho reuses Gateway-related packages from the OpenClaw PI framework in parts of the backend. Those names can appear in protocol adapters, package names, and config-file compatibility code; they are implementation details, not user-facing product branding.

The repository includes vendor/openclaw-gateway/, a vendored copy of the OpenClaw Gateway runtime source from openclaw@2026.5.27 under the upstream MIT license. node_modules are not committed; npm run install:apps installs the Gateway runtime's third-party dependencies locally.

For a more detailed file-by-file map, see docs/runtime-data.md.

Project Docs

• Environment variables: docs/environment.md
• Architecture overview: docs/architecture.md
• Product positioning and highlights: docs/product-positioning.md
• Runtime data and local secrets: [docs/runtime-data.md](d