chat-memory
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| CHAT_MEMORY_DB | No | Set to store the database somewhere else (default is ~/.local/share/chat-memory/memory.db). | |
| CHAT_MEMORY_SEMANTIC | No | Set CHAT_MEMORY_SEMANTIC=0 to switch off optional semantic (meaning-based) search. | 1 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Persistent memory that survives between chat sessions. Use it quietly; don't announce each call.
START OF A SESSION: call get_profile once to load pinned facts and preferences. When a topic comes up that past sessions may have covered, call recall before answering.
SAVE (remember) only things likely to matter in a future session:
durable facts about the user, their setup, people and projects
preferences and corrections ("don't do X", "always Y") and the reason given
decisions and their why; outcomes of finished work; where things live
at the end of substantial work, one kind="summary" note: goal, what was done, next steps DO NOT SAVE: passing state (free disk space, today's command output), things the files or git history already record, guesses, chit-chat, raw tool output, or anything secret (passwords, tokens, keys, account numbers). The server refuses obvious secrets.
HOW TO WRITE A MEMORY: one fact per memory, self-contained, with absolute dates (not "yesterday"). Title = short label. Content = What / Why / Where / How to apply, as relevant. kind is one of: fact, preference, project, decision, event, person, howto, summary. For a subject that will evolve (a project's status, a device's setup), pass a stable topic_key such as "project/chat-memory" or "device/printer"; saving with the same key updates in place.
DUPLICATES AND CONFLICTS: remember checks for similar memories. If it answers needs_review, update the existing memory instead (or pass force=true if it is genuinely different). If it saved but lists similar memories that the new one replaces, call supersede(old_id, new_id). When the user says something is no longer true, update or supersede; use forget only when it should never have been saved or the user asks.
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 |
|---|---|
| rememberB | Save a memory for future sessions. Returns action: created, updated (same topic_key), duplicate, unchanged, or needs_review (a near-identical memory exists; nothing saved). |
| recallA | Search memories by keywords and meaning (when the embedding model is installed). Returns short previews ranked by score; use get_memory for full text. |
| get_memoryB | Get one memory in full, optionally with its earlier versions. |
| update_memoryB | Change an existing memory. The previous text is kept as a version. pinned=true puts it in every session's profile. |
| supersedeA | Mark old_id as replaced by new_id. The old memory is hidden from recall but kept. |
| forgetC | Hide a memory that should not have been saved or that the user asked to remove. |
| list_recentC | Most recently saved or updated memories. |
| get_profileB | Session-start briefing: pinned memories, preferences and the most-used facts. |
| reviewA | Memories worth tidying: unused for stale_days, superseded, or saved repeatedly. Use when the user asks to clean up memory. |
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 9 tools
Each tool maps to a fairly distinct memory lifecycle operation, and descriptions clarify the subtle cases (remember's duplicate/needs_review outcomes, supersede vs forget both hiding but for different reasons). The main soft spot is the boundary between remember (which can update on same topic_key) and update_memory, plus forget vs supersede, which an agent could occasionally misselect.
Half the tools follow verb_noun (get_memory, update_memory, list_recent, get_profile) while the other half are bare verbs (remember, recall, supersede, forget, review). Each name is readable and reasonably self-describing, but the two conventions are mixed without a clear rule for which applies.
Nine tools is well within the sweet spot and every one earns its place in a memory lifecycle (save, search, read, edit, supersede, forget, list, profile, review). No filler tools and no obviously merged concerns.
The surface covers full lifecycle: create (remember), read (recall/get_memory), update (update_memory/supersede), soft-delete (forget), plus listing, profile briefing, and cleanup review. Minor gaps remain: no hard/permanent delete or purge, and no batch operations, but core workflows are fully served.