Agentic Task Coordination Platform & Persistent Memory Layer
Getting Started • Features • MCP Tools • CLI Reference • Documentation • Security • Manifesto
AI coding agents are powerful but forgetful. They lose context between sessions, can't see the full codebase, don't know what other agents are doing, and have no systematic way to catch quality regressions.
HIEF is a local-first MCP server that gives any AI coding agent — Claude Code, Cursor, Copilot, Windsurf, Goose, and more — persistent, searchable codebase context, lightweight task coordination, and automated quality evaluation. All from a single Rust binary. Zero external services. Your code never leaves your machine.
HIEF is a sidecar, not an agent. It has no LLM, doesn't execute code, and doesn't make decisions. The host agent provides reasoning; HIEF provides memory.
Agent (Claude Code / Cursor / Copilot / Windsurf / Goose)
│
│ MCP (stdio or HTTP)
▼
HIEF Server
├── INDEX: AST-aware search (keyword + structural + semantic)
├── INTENTS: Lightweight task coordination + provenance
├── EVAL: Golden-set quality guardrails
└── DOCS: Documentation scaffolding + drift/sync workflows
- AST-aware chunking via tree-sitter (Rust, Python, TypeScript/JavaScript)
- Keyword search via FTS5 full-text search
- Structural search via ast-grep pattern matching (e.g., find every
$X.unwrap()) - Semantic search via vector embeddings stored in libsql with TTL-bounded caching
- Incremental updates via blake3 content hashing — only re-indexes what changed
- Response Budgeting — automatically truncates oversized search responses while preserving metadata and snippets
- Query Routing — deterministic routing across lexical, semantic, and hybrid lanes
- Retrieval Weight Learning — dynamically optimizes query retrieval weights from historical groundedness feedback in shadow mode
- DAG-based task graph with status workflow (
draft → in_progress → in_review → approved → done) - Dependency tracking prevents conflicting concurrent work
- Provenance records which agent made each change and when
- Multi-Tenant / Worktree Isolation — partitions session telemetry and cognitive memory dynamically by git worktree ID
- Intent Soft-Locks — lease-based soft locks preventing competing worktree ownership on concurrent transitions
- Issue Claims —
hief claim/release/claimsleases shared by every worktree of a clone, optionally mirrored to GitHub - Task Tracking Web UI — HITL controls and review panels for active asynchronous worktrees
- SQL-Native Observability — built-in session telemetry and active evaluation loop
- Lightweight by design — not a project manager, just enough coordination
- Golden sets define project-specific quality criteria in TOML
- Literal checks —
must_contain/must_not_containvia substring matching - Structural checks —
structural_must_not_containvia ast-grep patterns - Differential eval —
diff_only = truechecks only changed files - Score history with regression detection
- Drift gate for CI —
hief checkwith a baseline,--diff-baseand GitHub annotations, plus checkers for unlinked TODOs, dead cited paths, stale reference docs and broken instruction commands - Fail-Closed Wave Gates — programmatically blocks intent pipeline promotion unless the latest evaluation run passes successfully
- Adaptive Protocol Routing — dynamically routes workloads across
mcp,progressive-mcp, andclilanes based on token pressure and capabilities - Robust Validation & Security — strict parameter validation with typed error shapes and path traversal rejection
- Configurable tool set —
[mcp] toolspresets (minimal,default,all) cut per-session context;hief skills exportmoves rare workflows into skill files - Dry-Run Installation —
hief installscaffolds and previews agent registration payloads safely
- Spec-Driven Development (SDD): Scaffold new feature specs from embedded or custom templates.
- Harness-Driven Development (HDD): Generate test harnesses and simulation playbooks.
- Auto-population: Templates can automatically inject project name, index statistics, and more.
- Template Overrides: Customize any default template by placing an override in
.hief/templates/.
- Place any markdown/YAML recipe in
.hief/skills/and HIEF will expose it as a dynamic MCP tool namedexecute_skill_<filename>(hyphens become underscores). - The tool returns the full file contents when invoked, allowing agents to load instructions on demand and follow project‑specific procedures.
- Skills can be listed (
hief skills list) and inspected (hief skills show).
- Rust stable toolchain (MSRV 1.88+)
- Git (for blame and hooks integration)
Download a prebuilt binary from the latest release
(Linux x86_64, macOS Intel and Apple silicon, Windows x86_64), unpack it, and put
hief on your PATH. Or build from source:
git clone https://github.com/hiranp/hief.git
cd hief
cargo build --release
# Optional: symlink to PATH for global access
mkdir -p ~/bin
ln -sf "$(pwd)/target/release/hief" ~/bin/hief# Initialize HIEF in your project
cd /path/to/your/project
hief init
# Build the code index
hief index build
# Start the MCP server (agents connect here)
hief serveKeyword, structural and drift checks work right away. For semantic search, set
[vectors] enabled = true in hief.toml and run hief index build again.
Configure your AI coding agent to connect to HIEF's MCP server:
Claude Code / Claude Desktop — add to your MCP settings:
{
"mcpServers": {
"hief": {
"command": "hief",
"args": ["serve"]
}
}
}HTTP transport (for agents that support it):
hief serve --transport http --port 3100HIEF exposes the following tools via the Model Context Protocol:
| Tool | Purpose |
|---|---|
| Search | |
search_code |
Keyword search over indexed code chunks (FTS5). Optional cognitive memory boost via boost_by_history. |
structural_search |
AST pattern matching via ast-grep (e.g., $X.unwrap(), fn $NAME($$$)) |
semantic_search |
Vector similarity search over libsql-stored embeddings (needs vectors.enabled) |
index_status |
Index statistics (file count, chunk count, languages, DB size) |
git_blame |
Git authorship info for a file range |
| Intents | |
create_intent |
Create a task in the dependency graph. Pass skill to get JIT recipe injection. |
list_intents |
List intents filtered by status and/or kind |
update_intent |
Update intent status or assignee (transitions are validated) |
ready_intents |
Show intents whose all dependencies are satisfied |
recover_stale_intents |
Recover stale in_progress intents past timeout back to approved |
get_transitive_deps |
Resolve recursive dependency chain for an intent |
find_callers |
Find call-sites using structural patterns |
| Claims | |
claim_issue |
Claim an issue with a lease; shared by every worktree of the clone |
release_issue |
Release a claim (holder only, unless force) |
list_claims |
Who holds which issue, and when each lease expires |
| Evaluation | |
run_evaluation |
Run golden set quality checks against the indexed codebase |
run_test_suite |
Run local test commands with timeout and structured pass/fail summaries |
judge_with_local_model |
Run local rubric judging via ollama or custom backend |
get_eval_scores |
Score history for a golden set |
check_drift |
Run drift checkers and return a 0-100 scaffold synchronization score |
| Context | |
get_project_context |
Index stats + active intents + ready intents snapshot |
get_conventions |
Machine-readable project rules from .hief/conventions.toml |
get_project_health |
Latest eval scores, regressions, and warnings |
get_session_context |
Files accessed this session + co-access graph suggestions |
get_session_summary |
Tool-call telemetry for a session |
related_files |
Files frequently accessed alongside a given file (co-access graph) |
list_context_files |
List .hief/context/ files and metadata |
read_context_file |
Read a named .hief/context/ file |
write_context_file |
Create/update a .hief/context/ file |
get_routing_table |
Fetch task-to-context routing from .hief/router.toml |
| Patterns | |
list_patterns |
List project patterns in .hief/patterns/ |
get_pattern |
Fetch full markdown for a named pattern |
create_pattern |
Create/update a pattern and auto-sync pattern index |
| Skills | |
list_skills |
List all skill recipe files in .hief/skills/ |
get_skill |
Fetch the contents of a named skill file |
reload_skills |
Hot-reload skill files without restarting the server |
execute_skill_<name> |
(dynamic) Invoke any skill recipe — returns its full markdown text |
Calling
create_intentwith askillparameter injects that recipe's content into the response, giving the agent the procedure before it starts work. See Trimming the MCP tool list to expose fewer tools.
| Command | Purpose |
|---|---|
hief docs init |
Initialize the standard documentation structure |
hief docs list |
List all available scaffolding templates |
hief docs generate |
Generate a new document from a template |
hief docs check |
Verify completion of required documentation |
hief skills init |
Create .hief/skills directory with README |
hief skills list |
List all skill recipes available |
hief skills show <name> |
Display the contents of a skill file |
hief skills export --target <harness> |
Write workflows as SKILL.md files for Claude, OpenCode or Gemini |
hief init # Initialize HIEF in current project
hief index build # Build/rebuild the code index
hief index search "query" # Search indexed code
hief index structural '$X.unwrap()' -l rust # AST pattern search
hief serve # Start MCP server (stdio)
hief serve --transport http --port 3100 # Start MCP server (HTTP)
hief claim 42 --lease 4h # Claim an issue across all worktrees
hief claims # Who holds what, with expiry
hief release 42 # Release your claim
hief check # Run drift checker suite
hief check --write-baseline # Accept today's drift; fail only on new issues
hief check --diff-base origin/main --format github # PR gate with annotations
hief sync --backend none # Generate targeted sync prompt
hief sync --backend codex --apply # Generate prompt + run fixer backend
hief watch --agent local-a # Watch filesystem + conflict warnings
hief patterns list # List project patterns
hief patterns create fix-api --title "Fix API" # Create/update a pattern
hief eval run # Run golden set evaluation
hief eval report # Show eval score history
hief session-cost --session-id <id> # Print human-readable session summary and telemetry
hief doctor --fix # Health check + auto-fix
hief hooks install # Install git hooks for auto-indexing
hief hooks watch # Alias for hooks install
hief install # Scaffolds installation with validated dry-run preview
hief ui --port 3190 # Start the local task-tracking web UI
hief docs init # Initialize standard docs structure
hief docs generate spec --name "feature" # Scaffold a new feature spec
hief docs generate harness --name "feature" # Scaffold a new test harness
hief skills init # Create skills directory for recipes
hief skills list # List available skill files
hief skills show create_database_migration # Print a specific skill
hief skills export --target claude # Write workflows as SKILL.md fileshief check needs no index (hief index build is not required). Exit codes:
0 clean, 1 new errors, 2 usage or config error (bad hief.toml, unknown
git ref, corrupt baseline).
On a repo that already has drift, record it once and commit the file:
hief check --write-baseline # writes .hief/drift-baseline.jsonAfter that, hief check hides the known issues and fails only on new ones.
Fixed issues drop out the next time you rewrite the baseline. --no-baseline
ignores the file. --diff-base <ref> counts only issues in files changed since
<ref>. --format github prints ::error file=…,line=…:: annotations.
# .github/workflows/hief.yml
on: pull_request
jobs:
drift:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with: { fetch-depth: 0 } # --diff-base needs history
- name: Install hief
run: |
curl -fsSL https://github.com/hiranp/hief/releases/latest/download/hief-linux-x86_64.tar.gz | tar xz
sudo install hief /usr/local/bin/hief
- run: hief check --diff-base origin/${{ github.base_ref }} --format githubParallel agents in separate git worktrees can claim issues so they do not
collide. Claims are one file per issue under $(git rev-parse --git-common-dir)/hief/claims/,
which every worktree of the clone shares. There is no daemon and no flock.
hief claim 42 --lease 4h --agent claude-1 # fails if someone holds a live claim
hief claims # holder, branch, worktree, expiry
hief release 42 # only the holder, unless --forceAn expired lease is taken over silently. --github (or [claims] github = true)
also adds the status:in-progress label and a comment, and removes the label on
release; this is the cross-machine signal, and a GitHub failure only warns.
Claims are separate from soft intent locks: those guard files for one intent in
each worktree's database, and claims say who works on an issue.
[claims]
default_lease = "4h"
github = falseEvery exposed tool's schema is sent to the agent on every session. Narrow the
list in hief.toml:
[mcp]
tools = "minimal" # preset: minimal | default | all (default: all)
# tools = ["minimal", "run_evaluation"] # presets and tool names mix| Preset | Tools | Approx. tokens |
|---|---|---|
minimal (search, context, drift check, claims) |
11 | ~4,400 |
default (all but rarely used tools) |
25 | ~8,200 |
all |
38 | ~11,500 |
An unknown name stops hief serve at startup. hief mcp status shows the
exposed tools and the cost of each preset. To keep the less common workflows
without paying for their tools, export them as skills, which cost context only
when the agent loads them:
hief skills export --target claude # .claude/skills/<name>/SKILL.md
hief skills export --target opencode # .opencode/skills/
hief skills export --target gemini # .gemini/skills/The export covers intents, eval, drift, patterns, docs and claims, plus your own
.hief/skills recipes. Existing files are kept unless you pass --force.
hief check runs 12 checkers. Four of them catch repo rot:
| Checker | Flags |
|---|---|
todo-issue |
TODO/FIXME without an issue ref (TODO(#123)), and TODO(#n) whose issue is closed (needs gh; skipped with a warning when gh is missing or offline) |
cited-paths |
Paths and file:line cited in backticks in AGENTS.md, CLAUDE.md, GEMINI.md and docs/ that no longer exist or are past the end of the file. Fenced blocks, URLs, globs and gitignored paths are skipped. |
reference-freshness |
Docs with front matter verified_at: <sha or date> and covers: [globs] where a covered file changed after verified_at |
instruction-literals |
Commands in agent instruction files that don't resolve: missing scripts/ file, unknown npm script, unknown cargo alias or -p package |
Turn checkers off, or skip noisy docs, in hief.toml:
[drift]
disabled_checkers = ["todo-issue"]
ignore_paths = ["docs/superpowers/**"] # cited-paths skips these docs.hief/
├── hief.db # SQLite database (FTS5 index, vectors, intents, eval scores)
├── conventions.toml # Machine-readable project rules
├── context/ # Agent-maintained context docs (architecture/setup/etc.)
├── golden/ # Golden set evaluation criteria (*.toml)
├── patterns/ # Project-specific task patterns + INDEX.md
├── skills/ # Skill recipes (exposed as execute_skill_<name>)
├── drift-baseline.json # Known drift, from `hief check --write-baseline`
└── router.toml # Task-to-context routing table
src/
├── cli/ # CLI commands (clap)
├── claims.rs # Issue claims shared across worktrees
├── context/ # Context file read/write/list logic
├── docs/ # Doc scaffolding engine (MiniJinja templates)
├── drift/ # Drift checkers, scoring, baseline
├── eval/ # Golden set evaluation engine
├── graph/ # Intent dependency graph (DAG)
├── index/ # AST-aware code indexing + search
│ ├── chunker.rs # tree-sitter based chunking
│ ├── search.rs # FTS5 keyword search
│ ├── structural.rs # ast-grep pattern matching
│ ├── vectors.rs # Semantic search (libsql vectors)
│ └── walker.rs # File system walker
├── mcp/ # MCP server (rmcp)
│ ├── tools.rs # Tool implementations
│ ├── toolset.rs # [mcp] tools presets
│ └── resources.rs # Resource definitions
├── patterns/ # Pattern library and index sync
├── router/ # Session routing table loader/defaults
├── skills/ # Skill loading and `skills export`
├── ui/ # Local task-tracking web UI
├── watcher/ # Filesystem watcher + conflict warnings
├── config.rs # TOML configuration (hief.toml)
├── db.rs # Database initialization (libsql)
├── errors.rs # Error types (thiserror)
└── main.rs # Entry point
hief.toml # Project-level configuration
templates/ # Doc scaffolding templates
| Capability | HIEF | Augment Code | Sourcegraph | Cursor |
|---|---|---|---|---|
| Local-first (no cloud) | ✅ | ❌ | ❌ | Partial |
| MCP server (any agent) | ✅ | ❌ | ❌ | ❌ |
| Quality evaluation | ✅ | ❌ | ❌ | ❌ |
| Task coordination | ✅ | ❌ | ❌ | ❌ |
| AST-aware structural search | ✅ | ✅ | ✅ | ✅ |
| Documentation scaffolding | ✅ | ❌ | ❌ | ❌ |
| Open source | ✅ | ❌ | Partial | ❌ |
HIEF's unique combination: local-first + MCP protocol + quality evaluation + open source.
| Document | Description |
|---|---|
| Manifesto | Core beliefs and design philosophy |
| Architecture | C4 views, design decisions, data schemas, failure modes |
| Constitution | Inviolable project rules |
| Scaffolding Guide | How the docs engine works |
| CHANGELOG | Release history |
cargo build --release # Compile release binary
cargo test # Run tests (no protoc needed)
cargo fmt -- --check # Check formatting
cargo clippy --all-targets # Run linterOr use the Justfile:
just build # cargo build --release
just test # cargo test
just lint # cargo clippy
just fmt # cargo fmt --check
just install # Build + symlink to ~/bin/hiefContributions are welcome! Please read CONTRIBUTING.md for guidelines on how to get started, the development workflow, and how to submit pull requests.
HIEF is built for developers who care about security and privacy.
- Local-First: All data stays on your machine. HIEF uses an embedded SQLite database (
.hief/hief.db), which also holds the vectors. - No Cloud Required: HIEF does not make any external network calls to process your code. Your source code never leaves your local environment.
- Sandboxed Execution: HIEF does not execute your code; it only parses it via tree-sitter or performs structural searches via
ast-grep. - Path Sanitization: All CLI and MCP tool inputs are strictly validated to prevent path traversal or flag injection attacks.
If you discover a security vulnerability, please see SECURITY.md for responsible disclosure instructions. Do not open a public issue.
HIEF is dual-licensed under MIT or Apache-2.0 at your option.
HIEF builds on excellent open-source projects:
- tree-sitter — AST parsing
- ast-grep — Structural search
- libsql — Embedded database with native vector search
- rmcp — MCP server framework