Knowledge

Hefty has a long-term memory. Every time you interact with it, Hefty can learn something new - a technique that worked, a mistake to avoid, or a fact about your project. This knowledge is stored locally and recalled automatically whenever it's relevant, making Hefty more effective the more you use it.

Skills

A skill is a reusable technique that Hefty learned from a successful interaction. Think of skills as Hefty's playbook - proven approaches it can reach for when facing a similar task.

Example skill
Docker Multi-Stage Build
When building Docker images for Node.js apps, use a multi-stage build: first stage installs dependencies and runs the build, second stage copies only the production artifacts. This reduces image size by 60-80%.

Skills capture what to do, when to apply it, and what results to expect. When Hefty encounters a similar task later, it recalls the relevant skill and uses the proven approach instead of figuring it out from scratch.

Skills also track their own track record:

  • Usage count - how many times the skill has been applied
  • Success rate - how often it leads to good outcomes
  • Recent history - the last several uses with outcomes

This means frequently-used, reliable skills get prioritized in future lookups. Skills that consistently fail naturally get deprioritized.

Teaching Hefty Skills

Beyond automatic learning, you can explicitly teach Hefty skills by providing structured text - for example, a skill.md file describing a workflow, deployment process, or coding pattern. Hefty sanitizes the input, extracts the core technique, and saves it to its knowledge base.

Antipatterns

An antipattern is a learned mistake - something that went wrong and should be avoided in the future. When Hefty encounters a failure or produces a bad result, it records what happened and how to prevent it next time.

Example antipattern
Unescaped Characters in sed
When using sed to modify files, special characters in the replacement string must be escaped. An unescaped forward slash in a URL replacement corrupted the nginx config file. Always use a different delimiter (e.g. sed 's|old|new|') when working with URLs or file paths.

When Hefty faces a similar situation later, it sees the antipattern warning and actively steers away from the known-bad approach. Antipatterns are especially valuable because they prevent Hefty from repeating the same class of mistake across different conversations.

Entities

Entities are the people, tools, services, and concepts that Hefty encounters during your conversations. They form Hefty's understanding of your world.

Example entity
staging-api
The staging API server at api.staging.example.com, running on port 3001. Uses PostgreSQL. Managed by the backend team. Deploy via make deploy-staging.

Entities build up over time as Hefty picks up facts from your conversations. If you mention "the staging server runs on port 3001," Hefty saves that and can recall it later without you repeating it.

Entities can also have data artifacts (entity documents) - larger pieces of information attached to them, like API documentation, configuration files, or command output. These are extracted automatically from action results during learning. Hefty can recall entity data on demand using a dedicated instrument when it needs detailed reference material during a task.

Deduplication is automatic - if Hefty encounters the same person or concept under different names or in different conversations, it merges them together rather than creating duplicates.

How Knowledge Is Used

Before Hefty reasons about your request, it automatically searches its knowledge base for anything relevant. This happens during the enrichment phase of the cognition pipeline. Hefty uses hybrid search - combining full-text search with vector similarity search - so it can find relevant knowledge even when you phrase things differently than before. Entity documents are also searched, and matching documents boost their parent entity in the results.

What Hefty recalls is visible in the activity details panel, so you can always see which skills, antipatterns, and entities influenced a particular response.

Keeping Knowledge Clean

Over time, Hefty may learn overlapping or redundant knowledge. Two built-in features help:

  • Consolidation - Hefty identifies similar items and proposes merging them into a single, cleaner version. You review and approve the merge.
  • Review - you can browse what Hefty has learned and decide whether to keep, refine, or retire items. All changes require your approval.

Hefty also automatically maintains its knowledge - pruning stale items and merging near-duplicates - so the knowledge base stays useful without manual upkeep.

Scoping

Not all knowledge applies everywhere. Hefty scopes knowledge so it's recalled in the right context:

  • Global - useful in any conversation
  • Per-user - specific to you
  • Per-conversation - only relevant in a particular chat
  • Per-project - tied to a specific project directory

This means advice about your Python project won't bleed into a conversation about your Rust project.