by Health-Yang
Local-first Memory OS for personal AI assistants with L0-L3 memory, Wiki++ knowledge, skill routing, and TokenLess context compression.
# Add to your Claude Code skills
git clone https://github.com/Health-Yang/MineEchoLast scanned: 6/4/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-06-04T08:21:20.034Z",
"npmAuditRan": true,
"pipAuditRan": true
}No comments yet. Be the first to share your thoughts!
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.
| 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 |
The project is designed around four baseline ideas:
MineEcho separates memory into two complementary views:
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.
MineEcho's knowledge base is organized as raw source files plus AI-maintained wiki pages. Query-time retrieval uses four channels:
This makes it closer to a high-density, maintainable AI knowledge substrate than a simple chunk-only RAG store.
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 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.
This is the full path for first-time users.
Install:
Check versions:
git --version
node -v
npm -v
If node -v is lower than 22, upgrade Node.js first.
git clone https://github.com/Health-Yang/MineEcho.git
cd MineEcho
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.
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.
npm run dev
The development URLs are:
http://127.0.0.1:5175/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.
You can start the two apps separately when debugging one side:
npm run dev:bff
npm run dev:console
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.
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.
docs/environment.mddocs/architecture.mddocs/product-positioning.mddocs/runtime-data.md](d