Engram Memory MCP Server
thomas-maurice/engram-memory-mcp-server
Memória semântica persistente para agentes Claude com Weaviate Engram
Ver no GitHubServidor MCP que fornece memória semântica persistente para agentes Claude usando Weaviate Engram como backend. Expõe ferramentas de busca e adição de memória, com suporte a CLI para inspeção e diagnóstico do estado de memória.
Instalação
npx convez-ai thomas-maurice/engram-memory-mcp-server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Manter preferências e contexto do usuário entre sessões do Claude Code
- Armazenar referências a sistemas externos e projetos relacionados
- Registrar correções validadas e abordagens comprovadas para reutilização
- Gerenciar estado de projeto que não está no código-fonte
Veredito

Solução robusta para memória de agentes em Go, ainda em fase POC com Engram em preview. Adequada para quem precisa de contexto persistente em Claude Code, mas requer configuração manual e compreensão dos mecanismos de captura de memória.
README
A tradução para o português deste README ainda está na fila.
engram-memory-mcp-server
Persistent semantic memory for Claude Code (and any MCP-compatible agent), backed by Weaviate Engram.
One Go binary, two modes:
- MCP stdio server (default) — exposes
memory_searchandmemory_addtools for agents. - CLI (subcommands) — for humans to inspect, seed, prune, and diagnose memory state.
The same env-var configuration drives both. There is also a SessionStart hook script that pre-loads relevant memories at the start of every Claude Code session.
Status: POC. Engram is in preview, the API surface is small (and slightly leaky — see known issues). The MCP wire works end-to-end against
https://api.engram.weaviate.io.
Contents
- Quickstart
- How memories are determined
- Configuration
- Wiring into Claude Code
- Instructing the agent
- CLI reference
- MCP tool reference
- SessionStart hook
- Project scoping
- Conversation scoping
- Add modes:
stringvspre_extracted - Troubleshooting
- Known Engram issues
Quickstart
# 1. Build (or: make build — injects the version via ldflags)
go build -o engram-memory-mcp-server .
# 2. Scaffold a config file
./engram-memory-mcp-server init
# wrote /Users/you/.config/engram-memory-mcp-server/config.yaml
# 3. Edit api_key and user_id in that file. Get a key at
# https://console.weaviate.cloud/engram → API Keys.
# 4. Sanity check
./engram-memory-mcp-server doctor
# 5. Try it
./engram-memory-mcp-server add "I prefer concise direct answers." --global --wait
./engram-memory-mcp-server search "answer style" --global
If doctor is happy and the round-trip works, you're ready to wire it into Claude Code — see Wiring into Claude Code.
How memories are determined
This is the most important part to get right.
Capture is agent-driven
The MCP server is a passive surface. It does not scrape transcripts, summarize sessions, or auto-extract anything. Memory only lands when the agent (or you, via CLI) explicitly calls memory_add. The tool's description tells the agent when to call it; LLMs follow tool descriptions closely, so phrasing matters.
The current memory_add description tells the agent to save:
- Durable user preferences or working style — "user prefers tabs over spaces in Go", "user dislikes trailing summaries".
- Validated corrections — "after my first attempt was rejected, the right approach was X."
- Project state that isn't derivable from the code — "the auth rewrite is driven by legal compliance, not tech debt", "Thursday's merge freeze blocks mobile."
- External system references — "incidents are tracked in Linear project FOO", "the latency dashboard is grafana.internal/d/api-latency."
And not to save:
- Code, conventions, file paths, or architecture —
gitandgrepare authoritative. - Ephemeral task state for the current session —
TaskCreate/ TODOs exist for that. - Debugging recipes — the fix is in the commit.
- Sensitive data — API keys, tokens, secrets.
- Speculation — anything the user did not actually say.
Read is agent-driven, with a hook assist
The agent calls memory_search whenever it suspects prior context might be relevant. The SessionStart hook supplements this by injecting a small set of top retrievals at session start, clearly labelled as a non-exhaustive preview — so the agent still calls memory_search for anything not visible.
Why this split
Two failure modes shape this design:
- Silently-wrong context — if a hook injected top-K memories without telling the agent it was a preview, the agent would assume that's everything and skip search. So the hook output is labeled explicitly.
- Polluted memory — if every transcript got auto-summarized into memory, signal-to-noise would collapse fast. Agent-driven capture is more deliberate; the agent only saves what it judges durable.
If you want auto-capture later (e.g. a Stop hook that ingests the transcript), it's straightforward to add — but ship the deliberate version first and observe before automating.
Configuration
Settings are layered, lowest priority to highest:
built-in defaults < config.yaml < ENGRAM_* env vars < CLI flags
The config file is the recommended source of truth. Env vars exist for per-invocation overrides (CI, ephemeral testing); CLI flags exist for per-call overrides.
Config file
Default path: $XDG_CONFIG_HOME/engram-memory-mcp-server/config.yaml, falling back to ~/.config/engram-memory-mcp-server/config.yaml. Override with ENGRAM_CONFIG=/path/to/config.yaml or --config PATH on subcommands that accept it.
Scaffold a starter file:
engram-memory-mcp-server init # writes to the default path
engram-memory-mcp-server init --path ./my.yaml
The generated file is self-documenting. The schema:
# Required
api_key: "eng_..." # from console.weaviate.cloud/engram → API Keys
user_id: "you@example.com" # stable identity; all memory is partitioned by this
# Optional — sensible defaults if omitted
# base_url: "https://api.engram.weaviate.io"
# group: "" # empty = use the project's default group
# project: "" # empty = auto-detect via `git remote get-url origin` / cwd
# default_topic: "UserKnowledge" # used by memory_add mode="pre_extracted"
# default_mode: "string" # write mode for topics not in topic_modes; string | pre_extracted
# topic_modes: # per-topic write mode (see "Add modes" below)
# ConversationSummary: pre_extracted
# UserKnowledge: string
# retrieval: "hybrid" # hybrid | vector | bm25 | fetch
# search_limit: 10
chmod 600 the file — it contains a secret.
Env-var overrides (optional)
Every YAML key has a corresponding ENGRAM_* env var that overrides it. Useful for CI, devcontainers, ephemeral testing, or having one machine use a different key without editing the file.
| YAML key | Env var | Notes |
|---|---|---|
api_key | ENGRAM_API_KEY | Required (in file or env) |
user_id | ENGRAM_USER_ID | Required (in file or env) |
base_url | ENGRAM_BASE_URL | Default https://api.engram.weaviate.io |
group | ENGRAM_GROUP | Leave empty/unset unless you've created a named group server-side. Unknown group names return HTTP 500 (not 404). |
project | ENGRAM_PROJECT | Auto-detected if empty/unset |
default_topic | ENGRAM_DEFAULT_TOPIC | Default UserKnowledge |
default_mode | ENGRAM_DEFAULT_MODE | Write mode for topics without a topic_modes entry. Default string. See Add modes. |
topic_modes | (config file only) | Per-topic write mode map; merges onto built-in ConversationSummary → pre_extracted. No env equivalent. |
retrieval | ENGRAM_RETRIEVAL_TYPE | Default hybrid |
search_limit | ENGRAM_SEARCH_LIMIT | Default 10 |
| (no YAML key) | ENGRAM_CONVERSATION_ID | Conversation scope tag. Falls back to CLAUDE_CODE_SESSION_ID. Runtime-only — see Conversation scoping. Often required on write — the default group rejects writes without it. |
| (config path itself) | ENGRAM_CONFIG | Override the file location |
Wiring into Claude Code
Two pieces, wired in two different places:
- The MCP server (so the agent can call
memory_search/memory_add) — registered withclaude mcp add, which writes~/.claude.json.~/.claude/settings.jsonhas nomcpServersfield; trying to add one there fails schema validation. - The SessionStart hook (so relevant memories pre-load each session) — added to the
hooksblock of~/.claude/settings.json. There is noclaude hooks addCLI, so this piece is a JSON edit.
Because the binary reads ~/.config/engram-memory-mcp-server/config.yaml directly, the wiring is just the binary path — no bash -lc 'source …' wrapping, no shell-env-inheritance gotchas. The same binary serves the MCP tools when invoked with no args and emits the SessionStart hook JSON when invoked as hook session-start.
1. Register the MCP server
claude mcp add engram --scope user -- /Users/thomas/git/engram-memory-mcp-server/engram-memory-mcp-server
--scope user makes it available in all your projects. Adjust the absolute path to wherever you built the binary. If your config lives somewhere non-standard, pass it through the env:
claude mcp add engram --scope user -e ENGRAM_CONFIG=/opt/secrets/engram-memory-mcp-server.yaml \
-- /Users/thomas/git/engram-memory-mcp-server/engram-memory-mcp-server
2. Add the SessionStart hook to ~/.claude/settings.json
Merge this into your existing config; don't overwrite. If you already have a SessionStart array, append a new entry to it rather than replacing it.
{
"hooks": {
"SessionStart": [
{
"matcher": "startup|resume|clear|compact",
"hooks": [
{
"type": "command",
"command": "/Users/thomas/git/engram-memory-mcp-server/engram-memory-mcp-server hook session-start"
}
]
}
]
}
}
The two pieces are independent — register the MCP server first, see how the agent uses it, then add the hook.
Verify
# 1. MCP server is registered and reachable
claude mcp get engram # Status: ✓ Connected
# 2. Hook output is well-formed
/Users/thomas/git/engram-memory-mcp-server/engram-memory-mcp-server hook session-start | jq .
# 3. Start a new Claude Code session
# The system context should include a block headed
# "Retrieved memories (Engram preview, NOT exhaustive)".
Gotchas
- The hook runs once per session start — 2 parallel Engram searches each time. ~200–500ms of wall time; not blocking, but visible if you start many sessions.
- Hook failures degrade gracefully. If config is missing or the API is down, the hook still emits a valid envelope with an informational note instead of crashing the session start.
claude mcp listdoesn't validate the command runs — only that it's registered. The agent's first attempt to call a tool is the real test.- Restart required after wiring. Claude Code freezes its tool set at session start; new MCP servers are picked up only by new sessions.
Instructing the agent
The MCP tool descriptions already tell the agent what memory_search / memory_add are — they fire whenever the model considers calling either tool. But you also need session-level guidance: "as part of how you work, here are the moments to reach for these tools." That lives in CLAUDE.md.
Paste the block below into ~/.claude/CLAUDE.md (global) or <repo>/CLAUDE.md (per-project). It's tuned to (a) make the agent reliably use the memory tools without being asked, and (b) keep the signal-to-noise ratio high so memory doesn't fill with junk over time.
## Persistent memory (engram-memory-mcp-server)
You have access to a persistent memory store via the `engram` MCP server. Two
tools: `memory_search` and `memory_add`. Treat memory as part of your normal
workflow, not an optional extra.
### When to search
Call `memory_search` proactively, not just when asked:
- **At the start of an unfamiliar task** — before reading code, search for the
user's prior preferences and project context. The SessionStart hook gives
you a small preview; assume more relevant memories exist.
- **When the user references prior work** ("the way we did X last time", "my
usual approach") — search before guessing.
- **Before making a non-trivial decision** (architecture, naming, test
strategy) — check whether the user has stated a preference.
- **When a topic comes up that may have history** — a system, a person, a
deadline, a vendor. Run a quick search even if you think you remember.
Tips:
- `project="*"` for user-level preferences and cross-cutting feedback.
- Omit `project` (or use the current project's identifier) for repo-specific
facts.
- A zero-hit result means "nothing matched", not "nothing exists" — try a
rephrasing or broader query before concluding the memory isn't there.
### When to save
Call `memory_add` when you learn something worth recalling next time. Save:
- **Durable user preferences** — *"user prefers integration tests over unit
tests in this repo"*, *"user wants concise responses, no trailing
summaries"*.
- **Validated corrections** — *"my first attempt added a wrapper; the user
clarified that direct calls are preferred here"*. Include enough context
to judge edge cases later.
- **Project state not derivable from code** — *"the auth rewrite is driven
by legal/compliance, not tech debt"*, *"merge freeze begins 2026-03-05
for the mobile release cut"*.
- **External system references** — *"incidents are tracked in Linear project
FOO"*, *"the latency dashboard is grafana.internal/d/api-latency"*.
Do NOT save:
- Code, conventions, file paths, architecture — `git` and `grep` are
authoritative. A memory pointing to `src/foo/bar.go:42` rots the moment
the file moves.
- Ephemeral session state — that's what TODOs are for.
- Debugging fix recipes — the commit message has the context.
- Sensitive data — API keys, tokens, credentials. Ever.
- Speculation — only save what the user actually said or demonstrated.
### How to phrase memory content
Write each memory as a **standalone fact** that will make sense in a future
session with zero context from this one:
- ✓ *"The user is the Platform Engineering tech lead at Weaviate."*
- ✗ *"As we discussed, you're a tech lead."* (refers to current turn)
- ✗ *"User prefers X."* (in the file index this is fine; in memory it should
be specific enough to retrieve: "User prefers X over Y in <context>".)
For corrections, include the *why* (a past incident, a strong preference) and
*how to apply* (when this guidance kicks in) so future-you can judge edge
cases rather than blindly applying the rule.
### Topic choice (mode follows automatically)
Pick the **topic**; the server derives the write mode from it (config:
`topic_modes`). You normally don't set `mode` at all.
- `topic="UserKnowledge"` — durable, standalone facts about the user
(preferences, working style, identity) that should hold across sessions.
- `topic="ConversationSummary"` — a recap of *this* session's events or
decisions that only makes sense in conversational context.
- Other topics that exist in your Engram project are also valid.
Only override `mode` for a one-off reason. `pre_extracted` stores verbatim
under your topic (~2s); `string` lets Engram atomize/dedup but then *Engram*
chooses the topic, so it can't guarantee your label.
### Read-your-writes is not guaranteed
A `memory_search` immediately after `memory_add` will often miss the new
memory — the pipeline is async (~2–10s to commit). If you need the value in
the same turn, hold onto it locally; don't round-trip through memory.
If you want this to fire on every project without per-repo CLAUDE.md edits, put it in the global ~/.claude/CLAUDE.md. Per-project CLAUDE.md is the right home if some repos should opt out (e.g. work code where you don't want personal-preference memory cross-pollinating).
CLI reference
engram-memory-mcp-server run MCP stdio server (default; for Claude Code)
engram-memory-mcp-server serve same, explicit
engram-memory-mcp-server search QUERY [--project P] [--global] [--conversation C] [--limit N] [--retrieval T] [--json]
engram-memory-mcp-server add CONTENT [--project P] [--global] [--conversation C] [--mode string|pre_extracted]
[--topic T] [--wait] [--json]
# --mode defaults to the topic's configured mode (topic_modes); pass to override
engram-memory-mcp-server list [--project P] [--global] [--conversation C] [--limit N] [--json]
engram-memory-mcp-server delete MEMORY_ID
engram-memory-mcp-server doctor diagnose env, auth, connectivity, project state
engram-memory-mcp-server help
Flags work in any position (e.g. add "fact" --global --wait and add --global --wait "fact" are equivalent). Use -- to disambiguate if your query starts with a dash.
Examples
# Diagnose setup
engram-memory-mcp-server doctor
# Save a global user preference, block until committed
engram-memory-mcp-server add "I prefer integration tests over unit tests in this repo." --wait
# Save a project-scoped fact (auto-tagged with current git remote)
engram-memory-mcp-server add "The auth rewrite is blocked on legal review."
# Search the current project
engram-memory-mcp-server search "auth rewrite status"
# Search across all projects (e.g. for personal preferences)
engram-memory-mcp-server search "what testing style does the user prefer" --global
# Inspect everything
engram-memory-mcp-server list --global --limit 100
# Delete by id
engram-memory-mcp-server delete 7bf61b5f-73b3-4ff4-a7bf-fc71a2190e80
# Pipe JSON for scripting
engram-memory-mcp-server search "deadlines" --global --json | jq '.memories[].content'
MCP tool reference
Run with no arguments (or serve) for stdio MCP. The wire protocol is the standard MCP JSON-RPC over stdin/stdout, served via the official modelcontextprotocol/go-sdk.
memory_search
memory_search({
query: string, // natural-language question or topic
project?: string, // "" = current project (default), "*" = all projects, or an explicit id
limit?: number // default ENGRAM_SEARCH_LIMIT (10)
}) → {
hits: Array<{ id, content, topic?, properties?, score? }>,
total: number
}
memory_add
memory_add({
content: string, // standalone fact, no "as we discussed"
project?: string, // "" = current (default), "*" = global
topic?: string, // "UserKnowledge" | "ConversationSummary" | other project topic
mode?: "string" | "pre_extracted", // usually omit — derived from topic via config (topic_modes)
}) → {
run_id: string,
status: string, // "running" — pipeline is async server-side
mode: string,
project: string,
conversation?: string // harness-supplied tag (CLAUDE_CODE_SESSION_ID); inert server-side today
}
The MCP tools deliberately expose no
conversationinput — conversation tagging is harness-supplied, never LLM-supplied. See Conversation scoping.
Read-your-writes is not guaranteed. Writes are processed asynchronously by Engram's pipeline (Temporal-backed). A
memory_searchimmediately aftermemory_addwill often miss the new memory. Acceptable for capture-after-conversation; not acceptable if the agent needs the memory in the same turn.
Wiring into Claude Code
See the dedicated Wiring into Claude Code section above.
SessionStart hook
engram-memory-mcp-server hook session-start runs two parallel searches (global + project-scoped) when a session begins and emits the results as Claude Code's hookSpecificOutput.additionalContext. The output is labelled as a non-exhaustive preview so the agent still calls memory_search for anything not shown — silently-wrong context is the worst failure mode this hook could create, so the label is explicit.
Configuration: shares config.yaml with the MCP server. No separate env file to source.
Tuning flags:
engram-memory-mcp-server hook session-start \
--global-limit 3 \
--project-limit 5 \
--timeout 5s
Wiring is documented in Wiring into Claude Code.
Project scoping
⚠️ Project scoping is OFF by default because the deployed API rejects it. Engram only honors scope properties that a group registers;
conversation_idis registered for thedefaultgroup (enforced and stored — see Conversation scoping), butprojectis not. The deployed API (https://api.engram.weaviate.io) now hard-rejects any unregistered scope property with HTTP 400 (invalid scope property: [project] not configured on any topic) on both reads and writes — it used to silently drop it, so sendingprojecttoday breaks every operation (search, add, and the SessionStart hook).To avoid that, the server does not send the
projectproperty at all unless you opt in viaproject_scope: true(config) /ENGRAM_PROJECT_SCOPE=true(env). With it off (the default),--project/ theprojecttool argument are accepted but ignored, and every search returns all memories for theuser_id. The isolation dimensions actually enforced areuser_id,group,topic, and any registered scope properties. See Known Engram issues.The wire contract is already correct, so once
projectis registered as a scope property server-side you flipproject_scope: trueand project scoping works — no other code change. Until then, leave it off.
The intended design (and what lights up once the server supports it):
Memories carry a project property so a fact about repo A doesn't pollute searches in repo B.
- Default project ID is the git remote origin URL, chosen so the same repo on different machines / worktrees resolves to the same scope.
- Fallback is the current working directory (fragile across machines — only used when there's no git remote).
- Override with
ENGRAM_PROJECT(env) or--project(CLI flag) orproject(tool argument). - Global memories (cross-repo user preferences) use
project="*"on either tool / CLI. They are stored without aprojectproperty and searched without a project filter.
When the agent should use project="*":
- User preferences and working style.
- Cross-cutting feedback ("never mock the database in tests, regardless of repo").
- References to external systems that aren't repo-specific.
When the agent should use project scope (default):
- Anything tied to a specific codebase, team, deadline, or migration.
Conversation scoping
Writes are tagged with a conversation_id scope property so memories created in
one session can be filtered back to it. The id value is runtime-only —
there is no config-file field for it.
Whether the property is sent at all is gated by
conversation_scope(config) /ENGRAM_CONVERSATION_SCOPE(env), defaulting to on. Leave it on for thedefaultgroup (which requiresconversation_idon write). Turn it off only if your group doesn't registerconversation_id— otherwise Engram hard-400s on it exactly like an unregisteredproject. Registration is per-group server-side config, so the right value depends on your group, not on us. This mirrorsproject_scope(see Project scoping).
- Source:
ENGRAM_CONVERSATION_IDenv var, falling back toCLAUDE_CODE_SESSION_ID(Claude Code injects this into the MCP server's environment — one MCP subprocess per conversation, so it's stable per session). - Override per call with
--conversation(CLI) onsearch/add/list. - Required on write (default group). The
defaultgroup registersconversation_idas a required scope property, so a write without one fails with HTTP 400 (missing required scope properties [conversation_id]). In normal MCP usage under Claude Code the id is always present (fromCLAUDE_CODE_SESSION_ID), so this is invisible; it bites direct CLI/SDK use that clears or omits the id. - Writes are tagged; reads are not filtered by default. The
memory_addtool tags new memories with the conversation id automatically;memory_searchdoes not filter by it (the model has no reliable id to supply, and conversation isolation on reads is rarely what you want). The CLIsearch/listaccept an explicit--conversationto filter when you do want it. - The MCP tools do not expose a
conversationinput — it's harness-supplied, never LLM-supplied, by design.
✅
conversation_idis enforced and stored server-side. Unlikeproject, it's a registered scope property for thedefaultgroup: writes that omit it are rejected (HTTP 400), and writes that include it persist the value —GET /v1/memories/{id}returns it underproperties(verified end-to-end). The read-side filter follows the same registration; this client only narrows reads when you pass an explicit--conversation. See Project scoping for the contrastingprojectbehavior.
Add modes: string vs pre_extracted
string (default) | pre_extracted | |
|---|---|---|
| Latency to commit | ~5–10s | ~2s |
| Memories produced | 0..N (extraction LLM decides) | exactly 1 |
| Dedup | server-side, against existing memories | server-side, but only this one item |
| Topic | inferred by extraction LLM | must be provided |
| When to use | agent writes natural prose | agent has already atomized one fact |
The default is string because the extraction step does useful work beyond storage. In testing, a single sentence — "Thomas prefers concise direct answers and dislikes filler text" — produced two atomic memories and a third inferred one ("the user's name is Thomas"). That kind of normalization is hard to replicate client-side.
Use pre_extracted when:
- You want a deterministic single-memory write.
- Latency matters more than extraction quality.
- The content is already a clean atomic fact and you know its topic.
Mode follows the topic (you don't usually pick it)
There's a catch that drives the design: only pre_extracted honours the topic you pass. In string mode the extraction LLM assigns the topic itself, so you cannot guarantee a memory lands under a specific label like UserKnowledge or ConversationSummary.
So rather than make the agent reason about modes, the agent picks one thing — the topic — and the server derives the mode from it. The mapping lives in config:
# config.yaml
default_mode: "string" # used for any topic not listed below
topic_modes:
ConversationSummary: pre_extracted # a deliberate verbatim recap, fixed topic
UserKnowledge: string # durable facts; let Engram dedup/atomize
Resolution order for a write: explicit mode (CLI --mode / the tool's mode input) > the topic's entry in topic_modes > default_mode > built-in string. Invalid values at any layer are skipped, so a config typo can't produce a mode the API will reject.
The built-in default (with no config) maps ConversationSummary → pre_extracted; everything else uses string. Override or extend via topic_modes — config entries merge onto the built-in seed. default_mode is also settable via ENGRAM_DEFAULT_MODE; the per-topic map is config-file only.
Heads-up: mapping a topic to
stringmeans Engram, not you, chooses the final topic — so the memory may not actually carry that label. If you need a guaranteed label, map it topre_extracted. Notepre_extractedrequires the topic to already exist in the Engram project, or the run fails withtopic "X" not found.
Run engram-memory-mcp-server doctor to print the resolved default_mode and topic_modes.
Troubleshooting
doctor says "user not found"
You have an API key but the project has zero memories for this user_id. Add one (engram-memory-mcp-server add "test" --global --wait); the user is auto-created on first add.
Writes succeed but search returns empty
The Engram project has no topics configured. Without a topic, the extraction step completes with no output — silently. Either:
- In the console, create your project from the personalization template (ships with the
UserKnowledgetopic), or - Ask whoever administers your Engram project to add the topics you need (there is no public API to add topics from the client).
You can confirm what topic the run used by polling GET /v1/runs/{run_id} — the response includes committed_operations.created[] when memories actually landed.
pre_extracted add returns a run that fails with topic "X" not found in group
Either rename your topic to one that exists in the project, or set ENGRAM_DEFAULT_TOPIC to a topic that does. Use engram-memory-mcp-server list --global to see what topics existing memories use.
Setting ENGRAM_GROUP=my-group returns HTTP 500
The server-side group name doesn't exist. Leave ENGRAM_GROUP unset to use the project's default group. (This is an Engram bug — unknown group names should 404, not 500.)
git remote get-url origin fails (not a git directory)
The project scope falls back to pwd, which is not stable across machines. Set ENGRAM_PROJECT explicitly to something stable (e.g. a project name string).
Known Engram issues (not our bugs)
Flagged for visibility — these are the rough edges as of the preview, and would be worth raising with the Engram team:
- Only registered scope properties are honored; arbitrary ones are dropped.
A property the group registers as a required scope property is enforced and
stored — e.g. the
defaultgroup requiresconversation_id: writes without it fail (HTTP 400) and writes with it persist the value, returned byGET /v1/memories/{id}. But arbitrary properties likeprojectare silently dropped on write (a subsequentGETshows noproject) and ignored as a search filter — a query with a matching filter and one with a non-matching value return identical results. There is no public API to register a scope property; it's configured server-side per group. Practical effect: per-conversation isolation works on groups that registerconversation_id, but per-project isolation is non-functional today (see Project scoping). - No
GET /v1/topics— client can't validate setup or render a topic picker. One read-only endpoint would fix it. - No public API for creating topics or groups — the only path is the console UI (and that's also currently missing for topics in some preview states). Bootstrap is fully manual.
group="<unknown>"returns HTTP 500 instead of 404.stringinput + zero topics = silent no-op — run goes tocompleted, zero memories produced, no warning surfaced.- No discovery /
/openapi.json— only/healthresponds outside the documented memory/search/runs endpoints. - String-only property values — no arrays, no numbers. Limits filter design.
- ~7s p50 latency for
string-input pipeline — fine for fire-and-forget capture, blocks read-your-writes UX.
Layout
engram-memory-mcp-server/
├── main.go thin entrypoint — calls cli.Run()
├── internal/
│ ├── cli/
│ │ ├── app.go settings layering, subcommand dispatch, project/conversation resolution
│ │ ├── commands.go CLI subcommands (search, add, list, delete, doctor)
│ │ ├── config.go config.yaml loading, init template
│ │ ├── serve.go MCP stdio server (memory_search, memory_add)
│ │ ├── hooks.go init + `hook session-start` subcommands
│ │ └── app_test.go unit tests (project/conversation/mode resolution)
│ └── engram/
│ └── client.go minimal HTTP client for Engram REST API
├── hooks/
│ └── session-start.sh legacy standalone shell hook (the Go binary's
│ `hook session-start` is preferred — see wiring)
├── .github/workflows/
│ ├── build.yml fmt-check, vet, test, build on push/PR
│ └── release.yml goreleaser release on v* tags
├── Makefile build/install/test/vet/fmt/check/snapshot targets
├── .goreleaser.yaml multi-platform binary release config
├── go.mod
└── README.md this file