Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@hiveai/cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@hiveai/cli

hAIve — team-first persistent memory layer for AI coding agents.

Stop re-explaining your project to every AI session. hAIve stores your team's conventions, architectural decisions, gotchas, and discovered patterns as version-controlled Markdown files. Every AI tool on your team reads the same shared knowledge automatically — via the MCP server, bridge files (CLAUDE.md, .cursorrules, Copilot instructions), or the CLI directly.

Install

npm install -g @hiveai/cli

This installs the haive command globally.

MCP server: also install @hiveai/mcp to expose memories to Claude Code, Cursor, Copilot, and any MCP-compatible AI client. Semantic search (optional): install @hiveai/embeddings for local embedding-based search (no data leaves your machine).

Quick start

# 1. Initialize hAIve in your project
cd my-project
haive init

# 2. Start the MCP server (in Claude Code / Cursor MCP config)
haive mcp --root /absolute/path/to/my-project

# 3. Add a team memory
haive memory add \
  --type gotcha \
  --slug "open-in-view-false" \
  --scope team \
  --paths src/main/resources/application.properties \
  --body "spring.jpa.open-in-view=false is intentional — do not re-enable."

# 4. Browse memories
haive memory list --scope team

# 5. Get a briefing before a task
haive briefing --task "add a payment endpoint" --scope team

# 6. Sync after a git pull
haive sync

Commands

`haive init`

Initialize the .ai/ structure in a project and generate bridge files for your AI tools.

haive init                    # Creates .ai/, CLAUDE.md, .cursorrules, copilot-instructions.md
haive init --no-bridges       # Skip bridge file generation
haive init --with-ci          # Also write .github/workflows/haive-sync.yml
haive init --dir /other/path  # Initialize in a specific directory

What it creates:

your-project/
├── .ai/
│   ├── project-context.md        # Shared project overview (fill via bootstrap_project MCP prompt)
│   ├── modules/                  # Per-component context files
│   └── memories/
│       ├── personal/             # Private to one developer
│       ├── team/                 # Shared with the whole team (git-committed)
│       └── module/<name>/        # Scoped to a specific module/component
├── CLAUDE.md                     # Bridge for Claude Code (auto-generated)
├── .cursorrules                  # Bridge for Cursor (auto-generated)
└── .github/
    └── copilot-instructions.md   # Bridge for GitHub Copilot (auto-generated)

Bridge files include mandatory rules that tell agents to call post_task and mem_tried before closing a session, so knowledge is captured automatically.

`haive mcp`

Start the hAIve MCP server over stdio. Point your AI client at this binary.

haive mcp                           # Auto-detect project root
haive mcp --root /path/to/project   # Explicit project root

Claude Code (~/.claude.json):

{
  "mcpServers": {
    "haive": {
      "command": "haive-mcp",
      "args": ["--root", "/absolute/path/to/your/project"]
    }
  }
}

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "haive": {
      "command": "haive-mcp",
      "args": ["--root", "/absolute/path/to/your/project"]
    }
  }
}

VS Code:

code --add-mcp '{"name":"haive","command":"haive-mcp","args":["--root","/path/to/project"]}'

`haive memory`

Manage individual memory entries.

`haive memory add`

haive memory add \
  --type <type> \          # convention | decision | gotcha | architecture | glossary | attempt
  --slug <slug> \          # Short identifier used in the filename
  --scope team \           # personal (default) | team | module
  --title "My title" \     # Optional heading (auto-added to body)
  --tags "auth,jwt" \      # Comma-separated tags
  --domain payments \      # Business domain for relevance scoring
  --paths src/auth.ts \    # Anchor to files (enables staleness detection)
  --symbols JwtFilter \    # Anchor to symbols/functions
  --body "The knowledge."  # Memory content (Markdown)

# Read body from a file (useful for long memories):
haive memory add --type architecture --slug "payment-flow" \
  --body-file docs/payment-architecture.md

Memory types:

Type	When to use
`convention`	How things are done here: naming, patterns, workflow
`decision`	A choice that was made and WHY (tradeoffs, constraints)
`gotcha`	Non-obvious behavior, traps, things that surprise newcomers
`architecture`	Structural overview of a system or module
`glossary`	Domain terms and their meaning in this project
`attempt`	Failed approach — prevents the same mistake next session

`haive memory list`

haive memory list                        # All memories
haive memory list --scope team           # Team memories only
haive memory list --status validated     # Only validated
haive memory list --type gotcha          # Gotchas only
haive memory list --tags auth,jwt        # By tags (AND match)
haive memory list --module payments      # Module-scoped memories

`haive memory query`

Full-text search across id, tags, and body.

haive memory query "flyway migration"         # AND search across all tokens
haive memory query "payment mobile wave"      # Falls back to OR if no AND match
haive memory query "jwt" --scope team --limit 5

`haive memory show`

Print the full body, frontmatter, and usage stats of a memory.

haive memory show 2025-01-15-gotcha-flyway-strict

`haive memory update`

Update a memory's body, tags, or anchor without changing its id or history.

haive memory update <id> --body "Updated content."
haive memory update <id> --tags "auth,jwt,security"
haive memory update <id> --paths src/auth.ts,src/jwt.ts

`haive memory verify`

Check anchor freshness — detect stale memories when anchored files or symbols have moved.

haive memory verify           # Check all memories
haive memory verify --id <id> # Check a specific one
haive memory verify --update  # Write stale/validated status back to disk

When a file is missing, hAIve searches the project for files with the same basename and suggests possible renames.

`haive memory approve` / `promote` / `reject`

Control the memory lifecycle: draft → proposed → validated or rejected.

haive memory approve <id>       # Mark as validated
haive memory approve --all      # Bulk-approve all proposed/draft
haive memory promote <id>       # Promote personal → team (status: proposed)
haive memory reject <id> --reason "Outdated after refactor"

`haive memory tried`

Record a failed approach — the most valuable type of negative knowledge.

haive memory tried \
  --what "importing gray-matter with ESM dynamic import" \
  --why-failed "gray-matter doesn't export a default; named import required" \
  --instead "import matter from 'gray-matter'" \
  --scope team \
  --paths src/parser.ts

Auto-validated (no approval cycle needed). Surfaced first in get_briefing so agents see it before making the same mistake.

`haive memory import`

Import documentation (README, ADR, wiki page) as memories via the import_docs MCP prompt.

haive memory import --from docs/architecture.md --scope team

Prints the MCP import_docs invocation to run in your AI client.

`haive memory for-files`

Show memories relevant to specific files you're about to edit.

haive memory for-files src/payments/PaymentService.java src/payments/PaymentController.java

`haive memory stats` / `hot` / `pending`

haive memory stats     # Usage stats and confidence levels for all memories
haive memory hot       # Most-read unvalidated memories (good promotion candidates)
haive memory pending   # Proposed memories awaiting review

`haive briefing`

Print the full project briefing — project context + relevant memories — in one shot. Use before starting a task.

haive briefing                                      # Full briefing, team scope
haive briefing --task "add a Stripe payment"        # Filter by task relevance
haive briefing --files src/payments/PaymentService.java  # Filter by files
haive briefing --scope all                          # Include personal memories
haive briefing --include-stale                      # Include stale memories
haive briefing --max-memories 15                    # Show more memories

`haive sync`

Refresh memory state after a git pull or merge.

haive sync                          # Verify anchors + auto-promote eligible memories
haive sync --since main             # Report memories changed since main
haive sync --inject-bridge          # Inject top memories into CLAUDE.md
haive sync --embed                  # Rebuild embeddings index after sync
haive sync --quiet                  # Minimal output (for git hooks)

What sync does:

Checks every anchored memory: does the file/symbol still exist? → marks stale if not
Re-validates previously stale memories that are now fresh again
Auto-promotes proposed memories that have been read enough times
Reports a decay warning for memories not read in >90 days
Optionally injects the top validated memories into your CLAUDE.md

`haive install-hooks`

Install git hooks so haive sync runs automatically after every pull/merge.

haive install-hooks         # Install post-merge and post-rewrite hooks
haive install-hooks --dir /path/to/project

`haive embeddings`

Manage the local semantic search index (requires @hiveai/embeddings to be installed).

haive embeddings index          # Build or refresh the embeddings index
haive embeddings status         # Show index stats (count, last updated, model)
haive embeddings query "how do we handle retries on payment failures"

The model (bge-small-en-v1.5, ~110MB) is downloaded on first use and cached locally. No data leaves your machine.

`haive index`

Build code navigation indexes.

haive index code        # Build .ai/code-map.json (file → exports + 1-line descriptions)

The code map lets AI agents find where a function lives without grepping — dramatically reducing tool calls at the start of a task.

`haive tui`

Interactive terminal dashboard to browse, filter, and manage memories.

haive tui               # Open the TUI (q to quit, arrow keys to navigate)
haive tui --dir /path/to/project

Memory lifecycle

haive memory add        → status: draft
haive memory promote    → status: proposed  (personal → team)
haive memory approve    → status: validated
haive sync              → status: stale     (if anchor broken)
haive memory reject     → status: rejected

Validated team memories are loaded into every get_briefing call and injected into bridge files.

Multi-component projects

For projects with frontend + backend (or microservices), create one module context per component:

# After haive init, create module context files:
mkdir -p .ai/modules/backend .ai/modules/frontend

cat > .ai/modules/backend/context.md << 'EOF'
# Module: backend
- Spring Boot, Java 17, PostgreSQL
- Always filter by tenantId in every query
- Never modify existing Flyway migrations
EOF

cat > .ai/modules/frontend/context.md << 'EOF'
# Module: frontend
- React 19, TypeScript, TanStack Query
- All API calls go through hooks in features/<domain>/api/
- Env vars must be prefixed with VITE_
EOF

get_briefing auto-loads the relevant module context based on the files the agent is editing.

Semantic search (optional)

Install @hiveai/embeddings for similarity-based memory retrieval:

npm install -g @hiveai/embeddings
haive embeddings index          # First run downloads the model (~110MB)
haive embeddings query "payment retry logic"

From MCP: set semantic: true on mem_search or get_briefing.

License

MIT

@hiveai/cli

Package Exports

Readme

@hiveai/cli

Install

Quick start

Commands

haive init

haive mcp

haive memory

haive memory add

haive memory list

haive memory query

haive memory show

haive memory update

haive memory verify

haive memory approve / promote / reject

haive memory tried

haive memory import

haive memory for-files

haive memory stats / hot / pending

haive briefing

haive sync

haive install-hooks

haive embeddings

haive index

haive tui

Memory lifecycle

Multi-component projects

Semantic search (optional)

License

`haive init`

`haive mcp`

`haive memory`

`haive memory add`

`haive memory list`

`haive memory query`

`haive memory show`

`haive memory update`

`haive memory verify`

`haive memory approve` / `promote` / `reject`

`haive memory tried`

`haive memory import`

`haive memory for-files`

`haive memory stats` / `hot` / `pending`

`haive briefing`

`haive sync`

`haive install-hooks`

`haive embeddings`

`haive index`

`haive tui`