halflife-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| HALFLIFE_HOME | No | Data directory. Defaults to a per-OS path: Linux ~/.local/share/halflife (or $XDG_DATA_HOME/halflife), macOS ~/Library/Application Support/halflife, Windows %APPDATA%\halflife. | |
| HALFLIFE_EMBED | No | Whether vector search is enabled (on if the vector extra is installed). Set to off to disable vector search. | on |
| HALFLIFE_EMBED_MODEL | No | Another fastembed model to use for embeddings. Recall thresholds are tuned for the default. | BAAI/bge-small-en-v1.5 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Long-term memory that persists across conversations on this computer. Five kinds: preference (how the user likes things done), procedural (workflows that worked), fact (durable facts not derivable from code or docs), episodic (what happened in a past task), trace (short-lived log of files/commands, for resuming work).
Scope: pass the absolute project/workspace path as scope when working in a project (it
is normalized to the git root); omit it or use "global" for things that apply everywhere.
Project queries always include global memories.
When to use:
Start of a non-trivial task: call memory_brief (preferences + procedures always apply), then memory_recall with a short description of the task.
Treat memories as context, not authority: the current user request and the actual code/docs win. Verify facts before relying on them.
When the user states a preference or corrects you: memory_remember right away (kind=preference, scope global unless project-specific).
When you infer something the user did not say: memory_remember with provisional=true; it stays hidden until confirmed later.
When a memory turned out useful or was confirmed: memory_reinforce.
When a memory is wrong or outdated: memory_remember the correction with contradicts= (the old one is retired, not deleted).
End of a substantive task: one kind=episodic memory: goal, what was done, decisions, open items. Pointers (paths, URLs) rather than copies.
When the user asks you to forget something: memory_forget (permanent). Never store secrets, credentials, raw transcripts or unnecessary personal data; such writes are refused.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| memory_briefA | What to know before starting work: the top preferences (up to 8) and procedures (6), the strongest facts (5) and the most recent episodes (3) for this scope (plus global). Bodies are clipped; use memory_get for a full memory. |
| memory_recallA | Search memory with hybrid keyword + vector + graph ranking. |
| memory_rememberA | Store one memory. kind: preference | procedural | fact | episodic | trace. content: the memory itself, short (for preference/procedural include why and how to apply). description: one keyword-rich line (used for matching; defaults to the first line). provisional: true when inferred rather than stated by the user. contradicts: id of a memory this one replaces. entities: [{"name", "type"}] for the specific files/tools/projects/people/concepts it is about (type: file, repo, tool, library, service, person, concept, ticket, command, project, organization). relations: [{"src", "rel", "dst"}] between those entities (rel: uses, depends_on, part_of, configures, fixed, caused, contradicts, supersedes, related_to, owns, prefers). source: where it came from (URL, file path). A near-duplicate reinforces the existing memory instead of creating a new one. |
| memory_reinforceA | A memory was confirmed or proved useful: raises its confidence, resets its decay and activates it if provisional. |
| memory_forgetA | Permanently delete a memory (file, graph, archived copy, index). Only when the user asks to forget something. |
| memory_getB | One memory in full, with its metadata and graph. |
| memory_listA | List memories of a scope (plus global), newest first. status: active | provisional. Use when the user asks what you remember. |
| memory_statsB | Counts per scope, kind and status; where the data lives; whether vector search is on. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 8 tools
The verbs are largely distinct: remember/get/forget/reinforce/stats are unambiguous. However, memory_recall, memory_list, and memory_brief all surface memories and could be confused—recall is query-driven search, list is scoped enumeration, and brief is a curated pre-work digest. The descriptions do clarify the boundary, so it's a minor overlap rather than a real ambiguity.
Every tool uses the same memory_ prefix followed by a short, readable suffix (recall, reinforce, forget, get, list, stats, brief, remember). The pattern is uniform throughout with no casing or convention drift.
Eight tools is well-scoped for a memory subsystem, with each tool earning its place (store, search, get, list, stats, reinforce, forget, brief). Nothing feels padded or missing.
The lifecycle is fully covered: create (remember), read (get/list/recall/brief), reinforce, and delete (forget), plus stats. Updates are handled via the contradicts/supersedes fields and reinforcement, so there is no dead end for the memory domain.