memory-service: Skill for Claude Code

API Contract Changes

contracts/ is the source of truth:

• Agent REST API: contracts/openapi/openapi.yml
• Admin REST API: contracts/openapi/openapi-admin.yml
• gRPC (agent and admin services): contracts/protobuf/memory/v1/memory_service.proto

Describe behavior in the contract (field and operation descriptions), not in agent notes or prose docs.

1. Keep the four surfaces aligned

When you change an agent REST operation, check the matching agent gRPC, admin REST, and admin gRPC operations, and change each one where the operation makes sense there. If a surface intentionally differs, say why in the contract description or the enhancement doc.

For each changed operation, keep these in step:

• The OpenAPI and protobuf contracts
• Server handlers: internal/plugin/route/** (REST, wired through internal/cmd/serve/wrapper_routes.go) and internal/grpc/server.go
• Datastore queries in all three stores (internal/plugin/store/{postgres,sqlite,mongo})
• BDD coverage for REST and gRPC (see the go-bdd skill)
• Site docs that show the operation

For conversation list, detail, or update changes, check both the public and the admin summary/detail payloads, filters, and mutation requests. Admin payloads may expose fields (such as clientId) that user-facing payloads must not.

2. Regenerate

task generate   # everything: Go (oapi-codegen + protoc), frontends, Python stubs, formatting
go generate .   # Go only: internal/generated/{api,apiclient,admin,pb}

Don't edit generated code. The Java REST and gRPC clients are generated during the Maven build:

./java/mvnw -f java/pom.xml -pl quarkus/memory-service-rest-quarkus,spring/memory-service-rest-spring -am compile

After deleting or renaming protobuf messages, use clean compile so stale generated classes don't survive.

OpenAPI generator traps are commented next to the schemas they affect in openapi.yml (for example searchType). Read those comments before restructuring a oneOf.