bulhufas
About
MCP server that ingests project docs once and lets Claude search by meaning instead of reading everything — saving tokens on large codebases
Details
- Author
- hugoluizmtb
- Categories
- Developer Tools, Knowledge Base
Jump to
Setup
Install bulhufas in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/hugoluizmtb/bulhufas
Follow the installation instructions in the repository README, then restart your MCP client.
RAG-powered project management that captures what PM tools miss.
Getting Started·How It Works·API·Self-Host·Contributing
Bulhufasis Brazilian Portuguese slang for "zilch", "diddly-squat", "bupkis" — absolutely nothing.
As in: "How much does Claude know about that decision your team made on WhatsApp last Thursday?"Bulhufas.
"What about that blocker someone mentioned in standup?"Bulhufas.
"And that architecture decision from two sprints ago?" You guessed it.Bulhufas.
Teams make decisions in Slack, WhatsApp, and meetings — then none of it reaches the PM tool.bulhufascaptures raw conversations, extracts structured project artifacts (decisions, action items, blockers, scope changes), and makes them searchable via semantic embeddings.
Single binary. No external dependencies. Embeddings run in-process.
- Conversation to Structure— Paste raw chat, get structured chunks: decisions, action items, blockers, requirements, scope changes
- Agent Memory— Store working, episodic, semantic and procedural memories in isolated namespaces with provenance, confidence, importance and validity windows
- Semantic Search— Find context by meaning, not keywords. "What did we decide about auth?" finds the right chunk even if "auth" isn't in the text
- Compact Recall— Return a bounded context packet with memory IDs and source references so any LLM can recall only what it needs
- CRUD on Knowledge— Update status, add context, archive outdated chunks. Your knowledge base stays current
- Single Binary— One Go binary with embedded vector store (chromem-go) and embedding model (hugot/all-MiniLM-L6-v2). No Ollama, no Docker, no external processes
- Self-Hostable— Deploy anywhere: Coolify, Railway, Hetzner, AWS, GCP. Runs on a 2GB VPS
You paste a conversation into your AI assistant | The LLM extracts structured chunks with metadata | bulhufas stores chunks + generates embeddings in-process (hugot) | Later: "what's pending from last week?" -> semantic search returns relevant chunks
# Requires Go 1.22+ with CGO enabled git clone https://github.com/HugoluizMTB/bulhufas.git cd bulhufas make build
claude mcp add --transport stdio --scope user bulhufas -- /absolute/path/to/bulhufas/bin/bulhufas --mcp
Replace/absolute/path/towith the actual path where you cloned the repo. Use--scope userto make it available across all your projects. Use--scope projectto restrict it to the current project only.
Run/mcpinside Claude Code. You should seebulhufasconnected with 10 tools:
On first run, the embedding model (all-MiniLM-L6-v2, ~80MB) is downloaded automatically to./data/models/.
Starts an HTTP API on port 8420. Use--mcpflag for MCP stdio mode instead.
Automatic gateway for any OpenAI-compatible LLM
To capture turns automatically in Claude Code without relying on the model callingobserve_turn, register theStophook inintegrations/claude-code-hook.mjs. Seedocs/claude-code-sessions.md.
For providers that do not support MCP, run the dependency-free memory proxy:
LLM_UPSTREAM_URL=https://api.openai.com \ LLM_UPSTREAM_API_KEY="$OPENAI_API_KEY" \ BULHUFAS_NAMESPACE=project:bulhufas \ make proxy
Point the client athttp://127.0.0.1:8421/v1. The proxy recalls scoped memory before each chat completion and captures substantive turns after the response. It works with OpenAI-compatible endpoints such as Ollama, vLLM and LM Studio; seeintegrations/README.md.
With Docker Compose, usedocker compose --profile proxy up -dafter settingLLM_UPSTREAM_URL,LLM_UPSTREAM_API_KEYandBULHUFAS_NAMESPACEin the environment.
curl -X POST http://localhost:8420/api/conversations \ -H "Content-Type: application/json" \ -d '{ "source": "whatsapp", "summary": "Discussion about database access", "participants": ["renan", "hugo"], "chunks": [ { "content": "Renan needs read-only access to PostgreSQL", "type": "decision", "tags": ["infra", "postgres"], "people": ["renan"], "status": "pending", "action_item": "Create read-only credentials" } ] }'
curl -X POST http://localhost:8420/api/search \ -H "Content-Type: application/json" \ -d '{"text": "database access", "limit": 5}'
curl -X POST http://localhost:8420/api/memories \ -H "Content-Type: application/json" \ -d '{ "content": "The payments service uses idempotency keys for retries", "memory_kind": "procedural", "namespace": "project:bulhufas", "source": "architecture-review", "source_ref": "meeting:2026-08-01", "confidence": 0.95, "importance": 0.8, "tags": ["payments", "reliability"] }' curl -X POST http://localhost:8420/api/recall \ -H "Content-Type: application/json" \ -d '{ "text": "How should payment retries work?", "namespace": "project:bulhufas", "memory_kinds": ["semantic", "procedural"], "limit": 5, "max_chars": 3000 }'
recallreturns both structuredresultsand a boundedcontextstring. Namespaces, project/tenant/session IDs and memory kinds are hard filters, so unrelated agent contexts are not concatenated accidentally.
WhenMEMORY_LLM_BASE_URLis configured, a background manager periodically consolidates episodic memories into conservative semantic/procedural records. It can also be triggered or previewed explicitly:
curl -X POST http://localhost:8420/api/consolidate \ -H "Content-Type: application/json" \ -d '{"namespace":"project:bulhufas","limit":32,"dry_run":true}'
In normal agent usage, the client can callrecallat task start andobserve_turnafter substantive turns. These are internal tool calls: you do not need to type “remember this” for ordinary learning. The explicitremember, update and delete tools remain available for corrections, promotions, forgetting and exact control. For chat gateways that can forward every message automatically,POST /api/turnsprovides the same capture path without relying on the model to initiate the call.
curl "http://localhost:8420/api/chunks?type=blocker&status=pending"
curl -X PATCH http://localhost:8420/api/chunks/{id}/status \ -H "Content-Type: application/json" \ -d '{"status": "resolved"}'
curl -X DELETE http://localhost:8420/api/chunks/{id}
Metrics are available atGET /metricsin Prometheus text format. SetBULHUFAS_API_KEYto protect API routes; place the service behind a TLS reverse proxy or set both TLS file variables directly.
cmd/server/ -> entrypoint, wires everything together internal/ domain/ -> core types: Conversation, Chunk, WorkItem, Relation mcp/ -> HTTP server, handlers, request/response logic store/ -> persistence interface + SQLite implementation vectorstore/ -> embedded vector search via chromem-go embedder/ -> in-process embeddings via hugot (all-MiniLM-L6-v2) scripts/ -> test scripts macos/BulhufasMac/ -> native macOS app: Dynamic Island + menu bar (GPL-3.0)
All external dependencies are behind interfaces. Swap SQLite for Postgres, or chromem-go for pgvector — without touching business logic.
No Ollama. No Docker. No external databases. One binary.
The local backend is deliberately the first tier of a larger memory design. SQLite/chromem is the default offline store; the native macOS app talks to it over the local HTTP API, while the optional Postgres adapter can use pgvector HNSW plus PostgreSQL full-text search. Vector quantization such as TurboQuant is an optional index optimization and must be validated against recall before enabling it.
The optional PostgreSQL/pgvector adapter is documented indocs/pgvector.md. The deeper LLM and memory research is summarized indocs/research-landscape.md.
CGO_ENABLED=1 GOOS=linux go build -o bulhufas ./cmd/server scp bulhufas your-server:/opt/bulhufas/ ssh your-server '/opt/bulhufas/bulhufas'
docker build -t bulhufas . docker run -d --name bulhufas -p 8420:8420 -v bulhufas-data:/data bulhufas
git clone https://github.com/HugoluizMTB/bulhufas.git cd bulhufas docker compose up -d
Works with Coolify, Railway, Hetzner, AWS, GCP, Oracle Cloud — anything that runs Docker.
The macOS app has no regular window. It lives in two places: a Dynamic Island that hangs from the notch, and a menu bar panel.
Dynamic Island.Closed, it is exactly the size of the notch and therefore invisible. Hovering opens it; clicking pins it open. When new memories arrive it briefly widens into a sneak peek. The open state shows the active Claude Code session and either recent memories or the session list. On displays without a notch the same shape hangs from the top edge.
Menu bar.A panel with the memory count, capture activity over time, and a breakdown of what was captured by chunk type.
Claude Code sessions.The app lists sessions by reading file metadata from$CLAUDE_CONFIG_DIR/projects,~/.claude/projectsand~/.claude-pessoal/projects— modification times and file names only. Transcript contents are never opened and no credentials are read. Memory capture itself still happens through the MCP server; seedocs/claude-code-sessions.md.
The app defaults tohttp://127.0.0.1:8420. SetBULHUFAS_URLbefore launching it to use another local or remote HTTP endpoint. The Homebrew formula is documented indocs/homebrew.md.
License note:the macOS app inmacos/is GPL-3.0, because it contains code derived fromAtolland, through it,boring.notch. The Go server and everything else in this repository stay Apache-2.0 — they are separate programs communicating over a local HTTP API. Seemacos/NOTICE.
- Core domain types and interfaces
- HTTP API with save/search/update/delete
- SQLite store implementation
- In-process embeddings via hugot (all-MiniLM-L6-v2)
- chromem-go vector store
- Semantic search with SQLite enrichment
- Action items endpoint
- MCP server protocol (stdio transport via mcp-go)
- Docker image
- Native macOS app: Dynamic Island + menu bar
- Claude Code session list from local transcript metadata
- Slack plugin
- Remote MCP via SSE transport
SeeCONTRIBUTING.mdfor setup instructions, code style, and PR process.
Apache License 2.0— use it freely, even commercially. Patent protection included.
This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.
Easily provide codebase context to Large Language Models (LLMs).
Local codebase context compiler for AI coding agents, turning TypeScript/Node workspaces into compact, verifiable context packs.
Local stdio MCP server that lets AI coding agents read and maintain structured architecture, rules, and decisions directly from your repository.
Official Context7 MCP server that brings up-to-date, version-specific library documentation and code examples into AI coding prompts.
Remote, no-auth MCP server providing AI-powered codebase context and answers
An intelligent codebase search engine that transforms local codebases into a natural language queryable knowledge base.
A local MCP server for AI coding agents. AST-aware indexing, semantic search, and automatic compression. Your agent stops re-reading your entire codebase every session.
A knowledge management tool for code repositories using vector embeddings, powered by a local Ollama service.
Provides up-to-date, version-specific documentation and code examples for libraries directly into your prompt.
Context7 Private Docs MCP is a paid hosted remote MCP for private, version-pinned documentation context, source citations, stale-doc checks, and usage receipts for coding agents.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
