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 LanceDB vector embeddings 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
- 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
- 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
- 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.85+)
- Git (for blame and hooks integration)
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 serveConfigure 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 (in development) |
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 |
| 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 |
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 |
Dynamic skills: Any
.mdor.yamlfile placed in.hief/skills/is automatically advertised as a custom MCP tool namedexecute_skill_<filename>(hyphens converted to underscores). Callingcreate_intentwith askillparameter injects the recipe content directly into the response — giving the agent executable context before it starts work.
| 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 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 check # Run drift checker suite
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/
├── hief.db # SQLite database (FTS5 index, intents, eval scores)
├── vectors/ # LanceDB directory (semantic embeddings)
├── conventions.toml # Machine-readable project rules
├── context/ # Agent-maintained context docs (architecture/setup/etc.)
├── patterns/ # Project-specific task patterns + INDEX.md
└── router.toml # Task-to-context routing table
golden/
└── *.toml # Golden set evaluation criteria
src/
├── cli/ # CLI commands (clap)
├── context/ # Context file read/write/list logic
├── docs/ # Doc scaffolding engine (MiniJinja templates)
├── drift/ # Drift checkers + scoring
├── 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 # LanceDB semantic search
│ └── walker.rs # File system walker
├── mcp/ # MCP server (rmcp)
│ ├── tools.rs # Tool implementations
│ └── resources.rs # Resource definitions
├── patterns/ # Pattern library and index sync
├── router/ # Session routing table loader/defaults
├── 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 |
| Task Tracking UI | Local-first task and worktree web UI architecture |
| Constitution | Inviolable project rules |
| Scaffolding Guide | How the docs engine works |
| CHANGELOG | Release history |
cargo build --release # Compile release binary
cargo test # Run unit tests
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) and a local vector store. - 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
- rmcp — MCP server framework
- LanceDB — Vector database