mcp-memory-service: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with this MCP Memory Service repository. It is written to be self-sufficient: a model should be able to work correctly here from this file alone, without filling gaps from prior knowledge.

Personal Customizations: You can create CLAUDE.local.md (gitignored) for personal notes, custom workflows, or environment-specific instructions. This file contains shared project conventions.

Information Lookup: Files first, memory second, user last. See .claude/directives/memory-first.md for strategy. Comprehensive project context is stored in the MCP Memory Server with tag claude-code-reference.

Non-Negotiables (hard rules)

Quick reference; each rule is expanded in the sections below. Violations cause real incidents.

1. Development happens on GitHub. origin is github.com:doobidoo/mcp-memory-service; CI is GitHub Actions (.github/workflows/); issues, PRs, releases and the tag push that starts a release all live there, and gh is the CLI for all of it. GitLab is a push mirror that receives fast-forwards of main and never tags (see "Source Control & Hosting").
2. Never manually bump versions. Follow the documented release workflow for every version bump and release.
3. Run bash scripts/pr/pre_pr_check.sh before every PR. It is the mandatory pre-PR gate and must pass.
4. Use the project venv. Run .venv/bin/python and .venv/bin/pytest (Python 3.12) — the system interpreters are not the project environment.
5. Store context in the MCP Memory Server first, tagged mcp-memory-service. Claude Code's file-based memory (~/.claude/projects/<project>/memory/) may run alongside it as a local cache — it is a supplement, not a substitute, and it lives outside the repo. Never commit memory files into the working tree.
6. Access Memory fields by attribute (memory.tags), never via memory.metadata.get('tags'). This has caused 3 production bugs.
7. Sanitize user-provided values in logs with _sanitize_log_value() (from mcp_memory_service.compat).
8. MCP server configs go in .mcp.json, not settings.json.
9. Update site/index.html version strings on every MINOR/MAJOR release (a CI gate enforces this).
10. Never click "Always allow" on heredoc commands — it corrupts .claude/settings.local.json.
11. Before any SSH/network task, verify hostname and connection direction (source → target).
12. Report outcomes faithfully. "Tests pass" means you ran them and saw them pass; if a step was skipped or failed, say so with the output.
13. Write in the maintainer's or contributor's own voice. Commit messages, PR descriptions, CHANGELOG entries, issue/PR comments, and release notes read as authored by the maintainer or contributor.
14. CONTRIBUTING.md binds maintainers and agents too. Before starting work on issue #N, check for existing work three ways: gh issue view N --json comments,assignees,closedByPullRequestsReferences (claims, assignee, linked PRs), gh pr list --search "N" --state all, and a gh pr list --search "<topic keywords>" --state open, since a PR can cover an issue without naming its number. If someone else claimed it or an open PR covers it, stop and report that. Otherwise claim it the way CONTRIBUTING.md asks: comment on the issue, and also run gh issue edit N --add-assignee @me so other sessions can see the claim. Henry asking for the work is the maintainer confirmation. An agent never claims an issue it was not asked to take. Every review thread (Greptile's included) gets a fix or a reply before it is resolved; see "Source Control & Hosting" for the ruleset that enforces this.