little-heta 0.2.3

Little Heta first-time initialization CLI

Little Heta

English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Español · Português · Français · Deutsch

Little Heta is a local CLI knowledge infrastructure for personal documents, agent memory, and document intelligence. It turns PDFs, Office files, images, audio, code, HTML, Markdown, and notes into a stable Markdown wiki, adds semantic vector retrieval, and lets agents reuse distilled knowledge through a memory layer.

Install

Install from PyPI:

pip install little-heta

From a local checkout:

pip install -e .

For development:

pip install -e ".[dev]"

The package installs the heta command:

heta --help

Initialize

Run the first-time setup:

heta init

You need to prepare:

• An LLM API key for one provider: Qwen, ChatGPT, Gemini, or custom.
• For custom providers, prepare separate chat and embedding capability settings. Use LiteLLM-native model names such as openai/gpt-5.4-nano when no base URL is needed, or use bare model names with an OpenAI-compatible /v1 base URL. Multimodal can be enabled separately when you want image parsing.
• Optional MinerU access for PDF and Office parsing. Apply or learn more at MinerU.

heta init writes config and workspace data under:

~/.heta/

It also installs the Little Heta agent skill automatically into:

~/.codex/skills/heta
~/.claude/skills/heta

Use with Codex and Claude Code

After heta init, Codex and Claude Code can discover the Little Heta skill globally. The skill tells the agent when to use:

heta ask "..."
heta query "..."
heta recall "..."
heta remember "..."

You can refresh or reinstall the skill at any time:

heta skill

For other agent frameworks, copy these two files:

~/.heta/skills/heta/SKILL.md
~/.heta/skills/heta/COMMANDS.md

What You Get

Most personal knowledge bases eventually become a /raw folder: papers, slides, screenshots, audio clips, code files, notes, and half-finished drafts all pile up together. A normal agent can read those files directly, but every question pays the same cost again: open the index, guess which page matters, read long pages, and spend tokens rediscovering context it already found before.

Little Heta separates the external knowledge base from the agent's internal memory. The KB remains the source of truth: a structured, versioned wiki built from the user's files. Memory, by contrast, is the agent's persistent working layer, storing reusable information that helps the agent reason, route, and avoid repeated deep retrieval. This creates a memory-first, KB-grounded retrieval loop.

Little Heta turns that pile into a persistent agent workspace:

• Wiki foundation: raw files are compiled into stable Markdown pages with numeric page ids, clean [[Wiki Links]], and Git history.
• Vector Wiki: each page is chunked by Markdown structure, so heta query can jump to the right section instead of relying only on sparse index.md summaries.
• Memory-first retrieval: heta ask stores distilled KB insights after expensive lookups, allowing later questions to reuse prior KB understanding instead of repeating the same deep wiki traversal.
• Synchronized memory + KB management: memory stays tied to the evolving wiki. When KB content changes, related memories can be invalidated to prevent stale cached insights from drifting away from the source of truth.
• Agent reuse: larger teams and multi-agent workflows benefit because useful KB discoveries can be reused across later questions, sessions, and agents.

Heta's memory architecture stores four complementary types of information:

• Raw dialogue memory: original user-agent interaction history, preserving full context and wording.
• Atomic fact memory: compact factual statements extracted from interactions, useful for precise attribute or preference recall.
• Episodic memory: event-level summaries that capture tasks, decisions, temporal context, and multi-step work sessions.
• KB insight memory: distilled insights produced after KB retrieval, storing what the agent learned from external documents so future questions can reuse that understanding without repeating the same expensive traversal.

Retrieval quality depends heavily on corpus structure. In corpora where important details are buried deep inside long wiki pages and poorly represented by summaries, index-only wiki navigation can suffer severe retrieval collapse. In our initial stress scenarios, Vector Wiki and memory-backed retrieval improved answer accuracy by roughly 1.25x-5x+, with some cases recovering from 0% to 100% accuracy.

Memory-backed reuse used 82.1% fewer tokens than index-only wiki query and answered 2.58x faster in a multi-page comparison setting. This gap is expected to grow in larger or messier workspaces, because index-only wiki navigation scales with the number and length of pages an agent may need to inspect, while memory-backed reuse resolves repeated questions from previously distilled insights. The main extra cost is the first pass that creates the reusable insight.

Recent Capabilities

• Static insert mode: every inserted source can be written as its own stable wiki page, while dynamic insert remains available for LLM-assisted wiki merging.
• Faster memory writes: heta remember --fast stores raw memory immediately, while the default high-quality mode now batches extraction, deduplication, and conflict checks more efficiently.
• Better memory recall: episodic memories are deduplicated, atomic facts can expire conflicting older facts, and heta recall ranks memory layers before answering.
• Cleaner operations: heta mem-show can inspect all memory layers, and CLI failures now show concise user-facing reasons instead of long tracebacks.

Core CLI

The main commands are:

• heta init: set up providers, workspace, and agent skills.
• heta status: show provider, MinerU, wiki, memory, and space status.
• heta insert: add files or folders to the knowledge base.
• heta query: ask a read-only question against inserted documents.
• heta ask: answer using memory and the document KB together.
• heta remember: save a fact, decision, or preference.
• heta recall: retrieve saved memory.
• heta clean: remove generated wiki pages and vector DB while keeping raw files.
• heta vector: turn document vector indexing on, off, or show status.
• heta insert-planning: turn smart insert planning on, off, or show status.
• heta dynamic-insert: turn dynamic LLM wiki merging on, off, or show status.
• heta mem-show: inspect stored KB memories.
• heta mem-clean: erase memory data.
• heta skill: install or refresh agent skills.

Detailed command docs:

• init
• status
• insert
• query
• ask
• remember
• recall
• clean
• vector
• insert-planning
• dynamic-insert
• mem-show
• mem-clean
• skill

Supported Files

Little Heta can insert:

• Markdown and text: .md, .markdown, .txt
• PDF and Office: .pdf, .doc, .docx, .ppt, .pptx, .xls, .xlsx
• Images: .png, .jpg, .jpeg, .webp, .gif, .bmp
• Audio and video transcripts: .mp3, .wav, .m4a, .flac, .ogg, .mp4
• Code and config files: .py, .js, .ts, .tsx, .jsx, .java, .go, .rs, .cpp, .c, .h, .hpp, .sh, .sql, .yaml, .yml, .json, .toml
• HTML: .html, .htm

PDF and Office parsing require MinerU. Images and audio/video require a multimodal or transcription-capable LLM provider.

Workspace

Runtime data lives under:

~/.heta/

Important paths:

~/.heta/heta.yaml                              config
~/.heta/workspace/kb/raw                       archived source files
~/.heta/workspace/kb/wiki/index.md            wiki entry index
~/.heta/workspace/kb/wiki/pages/              generated Markdown wiki pages
~/.heta/workspace/kb/wiki/log.md              wiki operation log
~/.heta/workspace/kb/db/wiki_vectors.sqlite3  local wiki vector database
~/.heta/workspace/mem/mem.sqlite3             local memory database
~/.heta/skills/heta/                          portable Little Heta agent skill

Development

Run tests:

pytest

Project layout:

src/heta/          CLI, config, assistants, memory, and KB implementation
docs/              user and technical documentation
tests/             unit tests
pyproject.toml     package metadata and dependencies

Community

If Little Heta is useful to you, please consider giving the project a star. If you run into bugs, rough edges, or missing workflows, open an issue and tell us what happened.

License

Little Heta is released under the MIT License. See LICENSE.