EchoWiki

Local-first LLM knowledge compiler for Obsidian. Drop notes or record voice into raw/; the wiki compiler turns them into a structured, interlinked wiki under wiki/.

Repository: github.com/mohammadmaso/echowiki

Install from Obsidian Community Plugins

Once published, install EchoWiki from any vault:

1. Settings → Community plugins → Browse → search EchoWiki → Install → Enable.
2. Open Settings → EchoWiki, add your LLM and STT API keys, then use the commands below.

EchoWiki creates raw/ and wiki/ folders in your vault automatically. You do not need to clone this repo unless you are developing EchoWiki itself.

Publish / update the Community listing (maintainers)

1. Bump version in root manifest.json and obsidian-plugin/manifest.json (keep them identical).
2. Commit and push to main.
3. Create and push a matching git tag (example: 0.1.0). GitHub Actions builds main.js, manifest.json, and styles.css.
4. Submit or update at community.obsidian.md → Plugins → New plugin (first time only) with repo URL https://github.com/mohammadmaso/echowiki.

Quick start (developer vault)

EchoWiki is designed so the repo root is your Obsidian vault. Your personal notes (raw/, wiki/) stay local and are not committed to git.

1. Clone and install

git clone https://github.com/mohammadmaso/echowiki.git
cd echowiki
nvm use          # Node.js >= 22.13 (see .nvmrc)
npm install
npm run build:plugin

This builds the Obsidian plugin (obsidian-plugin/main.js), bundling the compiler and Vercel AI SDK in-process — no separate server process.

2. Open as an Obsidian vault

1. In Obsidian, choose Open folder as vault.
2. Select the cloned echowiki folder (the repo root).
3. Obsidian creates .obsidian/ locally (gitignored — your settings stay private).

On first plugin load, EchoWiki creates empty raw/ and wiki/ folders with the expected subfolders.

Optional: copy the starter compiler instructions into your wiki:

cp templates/wiki/AGENTS.md wiki/AGENTS.md

3. Install the plugin in the vault

Symlink or copy the built plugin into Obsidian’s plugin directory:

mkdir -p .obsidian/plugins/echowiki
cp obsidian-plugin/manifest.json obsidian-plugin/styles.css obsidian-plugin/main.js .obsidian/plugins/echowiki/

Then in Obsidian:

1. Settings → Community plugins → Turn on community plugins
2. Enable EchoWiki

The status bar should show EchoWiki: ready.

4. Configure API keys

Settings → EchoWiki:

Setting	Purpose
LLM API key / model / base URL	Text compilation (any OpenAI-compatible endpoint)
STT base URL / API key / model	Voice transcription (/audio/transcriptions)
Language	Compilation output language (e.g. en, fa)
Watch mode	Auto-compile when files change under raw/
Require approval	Queue new raw files until you approve them

API keys are stored only in .obsidian/plugins/echowiki/data.json on your machine (never committed).

5. Daily use

Action	How
Drop a note for compilation	Save a .md or .txt file in raw/, or use EchoWiki: Send active note to raw/
Record a voice note	Ribbon mic icon, or EchoWiki: Record voice note
Compile one file	Open a file under raw/, run EchoWiki: Compile active raw file
Approve queued files	EchoWiki: Review pending compilations (when require approval is on)
Browse results	Open wiki/index.md, graph view on wiki/, follow [[wikilinks]]

Compilation writes to wiki/summaries/, updates wiki/concepts/ and wiki/entities/, and refreshes wiki/index.md and wiki/log.md.

Vault layout

Open the project root as your Obsidian vault. It must contain sibling folders:

<vault>/
├── raw/          # incoming notes and voice transcripts
└── wiki/         # compiled summaries, concepts, entities, index, log

Obsidian plugin (desktop & mobile)

The plugin runs compilation in-process via the Vercel AI SDK — you do not need Node.js on your PATH or a separate server. It works on Obsidian desktop and mobile (iOS/Android).

Requirements

• Obsidian 1.5.0+ (desktop or mobile)
• LLM and STT API keys configured in plugin settings (network required for compilation and voice transcription)

Build and install

From the repo root:

npm install
cd obsidian-plugin
npm install
npm run build

Copy or symlink the plugin folder into your vault:

<vault>/.obsidian/plugins/echowiki/
├── main.js
├── manifest.json
└── styles.css

Enable EchoWiki in Obsidian → Settings → Community plugins.

Plugin settings

Configure in Obsidian → Settings → EchoWiki:

Setting	Purpose
LLM API key / model / base URL	OpenAI-compatible chat endpoint for compilation
STT base URL / API key / model	Voice transcription (/audio/transcriptions)
Watch mode	Auto-detect new/changed files in raw/
Require approval	Hold raw files in a pending queue until approved

Status appears in the status bar on desktop (EchoWiki: ready or EchoWiki: compiling...). On mobile, use command palette notices during compilation.

Commands

• EchoWiki: Record voice note — mic → STT → raw/<timestamp>.transcript.md
• EchoWiki: Send active note to raw/ — copy current note into raw/
• EchoWiki: Compile active raw file — run compilation on the open raw note
• EchoWiki: Review pending compilations — approve or reject queued raw files

Ribbon: microphone icon opens the voice recorder.

CLI compilation (optional)

For headless compilation from the terminal (Node.js ≥ 22.13):

export OPENAI_API_KEY=sk-...
npm run compile -- raw/my-note.md

Optional flags: --kb-dir <vault-root> (defaults to current directory).

Manual test checklist

1. Text path: Create a note → Send active note to raw/ → file appears in raw/ → Compile active raw file → wiki/summaries/<name>.md is created.
2. Voice path: Record voice note → transcript .md appears in raw/ with the same pipeline as manual notes.
3. Watcher: With watch mode on, save a file under raw/ → compilation triggers (or approval prompt if enabled).
4. Approval: With require approval on, compilation waits until you approve in Review pending compilations; with it off, compile runs immediately.
5. Obsidian graph: Open graph view on wiki/ and confirm new pages link via [[wikilinks]].

Environment variables (CLI)

Variable	Purpose
OPENAI_API_KEY	LLM provider key
LLM_MODEL	Model id (default openai/gpt-5-mini; provider prefix is stripped)
OPENAI_BASE_URL	Optional OpenAI-compatible base URL

See .env.example for a minimal CLI setup.

Project structure

src/
├── llm/              # Vercel AI SDK client
├── wiki/             # Compilation pipeline (summaries, concepts, entities)
└── compiler-api.ts   # Public compile entry point
obsidian-plugin/      # Obsidian plugin (desktop + mobile; bundles compiler in-process)
raw/                  # Universal ingestion folder
wiki/                 # Compiled Obsidian-compatible wiki output

Learn more

• Vercel AI SDK
• Product/tech context: .ai/01-PRD.md, .ai/02-TECH-SPEC.md
• Task breakdown: .ai/03-TASKS.md