@prmichaelsen/remember-mcp 2.8.0 → 3.12.0

package/agent/design/local.ghost-persona-system.md

@@ -0,0 +1,273 @@
+# Ghost/Persona System — Cross-User Memory Access via AI Conversation
+
+**Concept**: Cross-user memory access mediated through AI "ghost" conversations, with backend-enforced trust filtering
+**Created**: 2026-02-27
+**Status**: Design Specification
+
+---
+
+## Overview
+
+The ghost/persona system enables cross-user interaction through AI-mediated conversations. Instead of granting direct access to another user's memories, User B talks to User A's "ghost" — an AI representation that speaks in first person, searches User A's memories on every message, and reveals information according to trust levels.
+
+Trust enforcement is hardcoded at the Weaviate query level in remember-mcp, preventing prompt injection from bypassing trust boundaries. The ghost uses existing `remember_search_memory` and `remember_query_memory` tools with trust-filtered queries.
+
+**Key architectural decisions**:
+- **remember-mcp** owns trust configuration and enforcement (not agentbase.me)
+- **Query-level filtering** as default enforcement (memories above trust threshold never returned)
+- **Three enforcement modes** (query, prompt, hybrid) — configurable, default to query
+- **Ghost memories** (`content_type: 'ghost'`) track ghost-user relationships over time
+- **Existing tools reused** — no dedicated ghost search tool needed
+
+**Source**: [clarification-2](../clarifications/clarification-2-cross-user-access-model.md), [clarification-3](../clarifications/clarification-3-ghost-system-deep-dive.md)
+
+---
+
+## Problem Statement
+
+- Memories are either fully private (owner only) or fully public (published to spaces/groups)
+- No middle ground for controlled cross-user access at varying trust levels
+- Direct memory access tools would expose raw memories and require complex permission management
+- Prompt-level trust enforcement is vulnerable to prompt injection attacks
+- No mechanism for users to interact with each other's knowledge in a natural way
+
+---
+
+## Solution
+
+### 1. Ghost Conversation Model
+
+A ghost is an AI conversation mode in agentbase.me where User B chats with a representation of User A.
+
+```
+User B opens conversation → selects "@patrick's ghost"
+→ System prompt establishes ghost identity (first person)
+→ On EVERY message, ghost calls remember_search_memory on User A's collection
+→ Weaviate query includes trust filter: trust_score <= accessor_trust_level
+→ Ghost responds based on retrieved memories, speaking as User A
+```
+
+**Ghost identity**:
+- Speaks in **first person** ("I love hiking") via system prompt
+- If Anthropic guardrails prevent first-person impersonation, falls back to third person
+- Personality derived from ghost owner's `content_type: 'ghost'` core memory
+
+**Ghost availability**:
+- **Opted out by default** — users must explicitly enable their ghost
+- Enabling comes with disclaimer: "No guarantee your ghost won't disclose things you never wanted anyone to see. Use at your own risk."
+- Can be enabled per-friend or globally with tiered trust defaults
+
+### 2. Trust Enforcement Architecture
+
+Trust is enforced at the **Weaviate query level** in remember-mcp's filter generation logic. This is a hardcoded backend filter that cannot be overridden by prompt injection.
+
+**Trust score semantics**:
+- `memory.trust_score`: How sensitive this memory is (0 = very private, 1 = fully open)
+- `accessor_trust_level`: How much the ghost owner trusts this person (0 = stranger, 1 = intimate)
+- Rule: Ghost reveals memory when `accessor_trust_level >= memory.trust_score`
+
+**Three enforcement modes** (hardcoded setting, togglable for experimentation):
+
+| Mode | Behavior | Security | UX |
+|------|----------|----------|----|
+| **Query filter** (default) | Memories above threshold never returned from Weaviate | Strongest — nothing to leak | No graduated disclosure |
+| **Prompt filter** | All memories returned, formatted by trust level | Weaker — relies on LLM | Rich 5-level disclosure |
+| **Hybrid** | Query filter for trust 0.0, prompt filter for rest | Medium | Best of both |
+
+Design supports all three; default to query filter until LLM compliance can be benchmarked.
+
+**Example query filter** (injected into `buildBaseFilters`):
+```typescript
+// In ghost mode, add trust filter to every query
+if (ghostContext) {
+  filters.push(
+    collection.filter
+      .byProperty('trust_score')
+      .lessOrEqual(ghostContext.accessorTrustLevel)
+  );
+}
+```
+
+### 3. Trust Configuration (remember-mcp owned)
+
+Trust configuration lives in **remember-mcp's Firestore**, not agentbase.me. This prevents prompt injection from tampering with trust levels passed per-request.
+
+**Firestore schema**: `users/{ownerUserId}/ghost_config`
+
+```typescript
+interface GhostConfig {
+  enabled: boolean;                    // false by default
+  public_ghost_enabled: boolean;       // allow non-friends to chat
+  default_friend_trust: number;        // default 0.25
+  default_public_trust: number;        // default 0 (strangers see nothing)
+  per_user_trust: Record<string, number>; // userId → trust level overrides
+  blocked_users: string[];             // users blocked from ghost access
+  enforcement_mode: 'query' | 'prompt' | 'hybrid'; // default 'query'
+}
+```
+
+**Trust tiers** (3 tiers for now):
+- **Friend**: `default_friend_trust` (default 0.25)
+- **Public user**: `default_public_trust` (default 0)
+- **Per-user override**: `per_user_trust[userId]` takes precedence
+
+**Friend relationship**: Tracked in remember-mcp's Firestore (not derived from agentbase.me social graph or group membership).
+
+### 4. Ghost Memory Content Type
+
+Ghosts track a **`ghost` content type** memory for each user they converse with. This is a single memory per (ghost_owner, conversing_user) pair that evolves over time.
+
+**Schema** (uses existing Memory fields):
+```typescript
+{
+  content_type: 'ghost',              // new content type
+  content: string,                     // ghost's impression (free text, updated over time)
+  user_id: string,                     // ghost owner's userId
+  // Custom fields via tags or structured content:
+  tags: ['ghost:conversing_user_id'],  // identify who this ghost memory is about
+  // Standard fields:
+  weight: number,                      // relationship quality score
+  access_count: number,                // conversation count
+  last_accessed_at: string,            // last conversation timestamp
+}
+```
+
+**Ghost memory behavior**:
+- Created automatically on first conversation with a new user
+- Ghost can update its own memory during conversation (via `remember_update_memory`)
+- **Filtered out** of `remember_search_memory` by default (same pattern as comments: `content_type != 'ghost'`)
+- Owner can explicitly search ghost memories via `content_type: 'ghost'` filter
+- Tool description/schema should hint at this pattern for agent discoverability
+
+**Ghost tool access** (during conversation):
+- `remember_search_memory` — search owner's memories (with trust filter)
+- `remember_create_memory` — create ghost memories only (`content_type: 'ghost'`)
+- `remember_update_memory` — update ghost memories only
+- `remember_query_memory` — fallback if search doesn't yield results
+
+### 5. Ghost Initiation Flow
+
+```
+1. User B visits User A's profile on agentbase.me
+2. Clicks "Chat with ghost" (if enabled)
+3. agentbase.me generates ghost chat request
+4. Ghost owner (User A) is notified
+5. Ghost owner approves/rejects and sets trust level
+6. If approved: conversation opens with ghost system prompt
+7. One ghost at a time per conversation
+```
+
+**Access requirements**:
+- Friendship or public profile required (not space/group membership)
+- Users can enable public ghost chats with a default trust level
+- Blocked users cannot initiate ghost conversations
+
+### 6. Ghost System Prompt
+
+The system prompt establishes ghost identity and includes trust context:
+
+```
+You are {username}'s ghost — an AI representation that speaks from
+{username}'s perspective using their memories. Speak in first person
+as if you are {username}.
+
+You are speaking with {accessor_name}, whom {username} trusts at
+level {trust_level}. You can only access memories with trust_score
+<= {trust_level}. If asked about topics you can't find memories for,
+respond naturally — you may not have memories on every topic.
+
+{ghost_core_memory_content}
+
+IMPORTANT: On every message, search {username}'s memories before
+responding. Use remember_search_memory first, fall back to
+remember_query_memory if search doesn't yield useful results.
+
+If {accessor_name} repeatedly asks about topics you can't share:
+- First: "I don't trust you enough to share that yet."
+- Second: "I'm not comfortable discussing that. Let's talk about something else."
+- Third: "You're being insistent. If you keep asking, I might trust you less."
+- After that: Trust escalation kicks in (handled by backend).
+```
+
+**Personality source**: Ghost owner's `content_type: 'ghost'` core memory (user-editable). If none exists, ghost operates with a neutral personality based on retrieved memories.
+
+---
+
+## Benefits
+
+- **Natural interaction**: Users interact with each other's knowledge through conversation, not raw memory access
+- **Strong security**: Query-level trust enforcement prevents prompt injection leaks
+- **Progressive trust**: Ghost reveals more as trust increases — natural relationship building
+- **Living relationships**: Ghost memories evolve, creating persistent ghost-user bonds
+- **Minimal new tools**: Reuses existing search/create/update tools with trust filtering
+- **User control**: Opt-in, configurable trust tiers, blocking capability
+
+---
+
+## Trade-offs
+
+- **No graduated disclosure in query mode**: Query filtering means the ghost can't hint "I know something but can't tell you" — it genuinely doesn't see the memory. Mitigated by hybrid mode option.
+- **First-person impersonation risk**: Anthropic guardrails may block first-person ghost speech. Mitigated by third-person fallback.
+- **Ghost accuracy**: Ghost represents memories, not the actual person — may misrepresent views. Mitigated by disclaimer on ghost enable.
+- **Search on every message**: Performance cost of Weaviate query per message. Mitigated by existing search being fast enough per user confirmation.
+- **Trust configuration complexity**: Per-user trust overrides, friend tracking, tiered defaults add Firestore complexity. Mitigated by simple 3-tier default.
+
+---
+
+## Dependencies
+
+- **M7 (Trust & Permissions)**: Trust types, Firestore trust storage, trust enforcement service, access control service
+- **Existing tools**: `remember_search_memory`, `remember_query_memory`, `remember_create_memory`, `remember_update_memory`
+- **Existing schema**: `trust_score` field on memories, `content_type` field
+- **agentbase.me**: Conversation UI, ghost chat initiation flow, profile integration
+- **Firestore**: Ghost config storage, friend relationship tracking, trust escalation blocking
+
+---
+
+## Testing Strategy
+
+- **Trust enforcement**: Verify query filter correctly excludes memories above trust threshold
+- **Three enforcement modes**: Test query, prompt, and hybrid modes independently
+- **Ghost memory CRUD**: Create, update, search ghost memories; verify default filtering
+- **Trust escalation**: Verify -0.1 penalty and blocking after 3 attempts
+- **Edge cases**: No memories found, ghost disabled, blocked user, stranger access with public ghost
+- **Security**: Prompt injection attempts to bypass trust level, tool call manipulation
+- **Performance**: Search latency with trust filter on every message
+
+---
+
+## Migration Path
+
+1. **M7**: Build trust foundations (types, Firestore, enforcement, access control)
+2. **M16**: Ghost system implementation
+   - Ghost config schema + Firestore operations
+   - Trust filter integration into search/query tools
+   - Ghost memory content type + filtering
+   - Ghost system prompt generation
+   - agentbase.me conversation UI integration
+3. **Future**: Benchmark prompt-filter and hybrid modes; make enforcement mode user-configurable
+
+---
+
+## Future Considerations
+
+- **Prompt-filter benchmarking**: Test LLM compliance with graduated trust disclosure; if reliable, enable as user option
+- **Ghost conversation logs**: Let ghost owner see who talked to their ghost and what was discussed
+- **Notification system**: Notify ghost owner when someone initiates a ghost chat
+- **Ghost personality customization**: Beyond core ghost memory, allow style/tone preferences
+- **Multi-ghost conversations**: Talk to multiple ghosts in one conversation (deferred — one at a time for now)
+- **Trust level auto-adjustment**: Ghost could recommend trust changes based on conversation quality
+- **REST API support**: Expose ghost/trust config via forthcoming remember REST API
+
+---
+
+**Status**: Implemented (v3.12.0)
+**Note**: M7 trust foundations + M16 ghost system both complete
+**Related Documents**:
+- [clarification-2: Cross-User Access Model](../clarifications/clarification-2-cross-user-access-model.md)
+- [clarification-3: Ghost System Deep Dive](../clarifications/clarification-3-ghost-system-deep-dive.md)
+- [trust-system-implementation.md](./trust-system-implementation.md)
+- [permissions-storage-architecture.md](./permissions-storage-architecture.md)
+- [trust-escalation-prevention.md](./trust-escalation-prevention.md)
+- [access-control-result-pattern.md](./access-control-result-pattern.md)
+- [milestone-7-trust-permissions.md](../milestones/milestone-7-trust-permissions.md)

package/agent/design/local.group-acl-integration.md

@@ -0,0 +1,338 @@
+# Group ACL Integration for remember-mcp
+
+**Concept**: Consume agentbase.me group permissions to enforce memory-level ACLs in remember-mcp
+**Created**: 2026-02-27
+**Status**: Design Specification
+**Source**: [agentbase.me group-management-tools.md](../../../agentbase.me-e1/agent/design/local.group-management-tools.md), [group-credentials-for-remember-mcp.md](../../../agentbase.me-e1/agent/design/local.group-credentials-for-remember-mcp.md)
+
+---
+
+## Overview
+
+This document specifies what remember-mcp (built on remember-core) needs to implement to consume and enforce the group permission model defined by agentbase.me. agentbase.me owns group definitions, membership, and permissions. remember-mcp owns memory-level ACL enforcement and space configuration.
+
+agentbase.me stores **permission-level ACL flags** directly on group members (no named roles). The credentials endpoint returns these flags as-is. remember-mcp reads them and enforces memory operations accordingly.
+
+---
+
+## Problem Statement
+
+remember-mcp currently has no group or space ACL support. The existing `User` type has a flat `role: 'admin' | 'member' | 'viewer'` field that applies system-wide, not per-group. To support group memory spaces, remember-mcp needs to:
+
+1. Consume per-group permission objects from the agentbase.me credentials endpoint
+2. Map permission flags to memory operations (publish, revise, retract, etc.)
+3. Enforce `auth_level` hierarchy for moderation actions on memories
+4. Store moderation action stamps on memories for hierarchy enforcement
+
+Without this, users in a group could perform any memory operation regardless of their permissions.
+
+---
+
+## Solution
+
+Add a credentials client, permission types, and an authorization layer to remember-core. The authorization layer sits between MCP tool handlers and the memory services, checking permissions before allowing operations.
+
+### Ownership Split
+
+| Concern | Owner |
+|---------|-------|
+| Group definitions, membership, ACL flags | agentbase.me |
+| Credentials endpoint (`/api/credentials/agentbase`) | agentbase.me |
+| Memory storage, space configuration | remember-mcp |
+| Memory-level ACL enforcement | remember-mcp |
+| Moderation action stamps on memories | remember-mcp |
+
+---
+
+## Implementation
+
+### 1. Permission Types
+
+remember-core needs types that mirror the agentbase.me permission model. These are **read-only** — remember-mcp never writes permissions, only reads them from the credentials endpoint.
+
+```typescript
+// src/types/permissions.types.ts
+
+/**
+ * Per-group permission flags as returned by the agentbase.me credentials endpoint.
+ * remember-mcp reads these flags to gate memory operations.
+ *
+ * These flags are defined and stored by agentbase.me on each group member.
+ * remember-mcp MUST NOT modify, cache long-term, or duplicate this data.
+ */
+export interface MemberPermissions {
+  auth_level: number           // 0 = root/owner, increments up. Lower = more authority
+  can_read: boolean
+  can_publish: boolean
+  can_revise: boolean          // Revise others' published content
+  can_propose: boolean         // Propose changes for approval
+  can_overwrite: boolean       // Force-replace content
+  can_comment: boolean
+  can_retract_own: boolean
+  can_retract_any: boolean     // Retract any member's content
+  can_manage_members: boolean  // Not used by remember-mcp (agentbase concern)
+  can_update_properties: boolean // Not used by remember-mcp (agentbase concern)
+  can_moderate: boolean        // Delete/edit messages, moderate memories
+  can_kick: boolean            // Not used by remember-mcp (agentbase concern)
+  can_mute: boolean            // Not used by remember-mcp (agentbase concern)
+  can_ban: boolean             // Not used by remember-mcp (agentbase concern)
+}
+
+/**
+ * A single group membership entry from the credentials endpoint.
+ */
+export interface GroupMembership {
+  group_id: string
+  permissions: MemberPermissions
+}
+
+/**
+ * The relevant portion of the agentbase.me credentials response.
+ */
+export interface AgentbaseCredentials {
+  access_token: string
+  group_memberships: GroupMembership[]
+}
+```
+
+### 2. Permission-to-Operation Mapping
+
+Each remember-mcp memory operation maps to one or more permission flags:
+
+| Memory Operation | Required Permission Flag | Notes |
+|-----------------|------------------------|-------|
+| `remember_search_memory` (in group space) | `can_read` | Read-only access to group memories |
+| `remember_publish` (to group space) | `can_publish` | Create new memory in group space |
+| `remember_revise` (own memory) | `can_publish` | Author can always revise their own |
+| `remember_revise` (another's memory) | `can_revise` | Edit someone else's published content |
+| `remember_propose` | `can_propose` | Suggest a change for approval |
+| `remember_overwrite` | `can_overwrite` | Force-replace content without confirmation |
+| `remember_comment` | `can_comment` | Add comments to group memories |
+| `remember_retract` (own memory) | `can_retract_own` | Remove your own published memory |
+| `remember_retract` (another's memory) | `can_retract_any` | Remove any member's memory |
+| `remember_moderate` (delete/edit memory) | `can_moderate` | Moderation action on group memories |
+
+**Flags NOT consumed by remember-mcp** (agentbase.me concerns only):
+- `can_manage_members` — group membership management
+- `can_update_properties` — group name, description, picture
+- `can_kick` — remove members from group
+- `can_mute` — prevent members from sending messages
+- `can_ban` — permanently ban members
+
+### 3. Credentials Client
+
+A thin client to fetch permissions from the agentbase.me credentials endpoint. Called on every ACL-gated operation (no caching).
+
+```typescript
+// src/client/credentials.client.ts
+
+export interface CredentialsClient {
+  /**
+   * Fetch the current user's group memberships and permissions.
+   * Called on every ACL-gated operation — no caching.
+   */
+  getCredentials(jwt: string): Promise<AgentbaseCredentials>
+
+  /**
+   * Get permissions for a specific group.
+   * Returns null if the user is not a member.
+   */
+  getGroupPermissions(
+    jwt: string,
+    groupId: string
+  ): Promise<MemberPermissions | null>
+}
+```
+
+### 4. Authorization Service
+
+A service that sits between tool handlers and memory services, enforcing permissions.
+
+```typescript
+// src/services/authorization.service.ts
+
+export class AuthorizationService extends BaseService {
+  private credentialsClient: CredentialsClient
+
+  /**
+   * Check if a user can perform an operation on a group memory.
+   * Returns Result<void, ForbiddenError> — Ok if allowed, Err if denied.
+   */
+  async checkPermission(
+    jwt: string,
+    groupId: string,
+    requiredFlag: keyof MemberPermissions,
+  ): Promise<Result<void, ForbiddenError>>
+
+  /**
+   * Check if a user can perform a moderation action, considering auth_level.
+   * The user's auth_level must be <= the target action's acted_by_auth_level.
+   */
+  async checkModerationPermission(
+    jwt: string,
+    groupId: string,
+    targetAction?: MemoryModerationAction,
+  ): Promise<Result<void, ForbiddenError>>
+}
+```
+
+### 5. auth_level Enforcement for Memory Moderation
+
+When a user moderates a memory (delete, edit, retract via moderation), the action is **stamped** with the user's `auth_level`. A subsequent user can only reverse the action if their `auth_level <= acted_by_auth_level`.
+
+```typescript
+// src/types/moderation.types.ts
+
+/**
+ * Stamped moderation action on a memory.
+ * Stored alongside the memory record.
+ */
+export interface MemoryModerationAction {
+  action: 'memory_delete' | 'memory_edit' | 'memory_retract'
+  memory_id: string
+  acted_by_user_id: string
+  acted_by_auth_level: number   // Snapshot of actor's auth_level at time of action
+  created_at: string
+  reversed_at?: string          // Set when action is undone
+  reversed_by_user_id?: string
+}
+```
+
+**Enforcement rule**: To reverse a `MemoryModerationAction`, the requesting user must have `auth_level <= acted_by_auth_level` in that group.
+
+**Example**: An admin (`auth_level: 1`) deletes a memory. A moderator (`auth_level: 2`) with `can_moderate: true` cannot restore it — the deletion was performed at level 1. Only `auth_level` 0-1 users can reverse it.
+
+### 6. Memory ACL Flow
+
+```
+User calls a memory tool (e.g., remember_revise)
+  │
+  ▼
+Tool handler identifies target memory and group_id
+  │
+  ▼
+AuthorizationService.checkPermission(jwt, groupId, 'can_revise')
+  │
+  ├─ Err(ForbiddenError) → return "Permission denied"
+  │
+  └─ Ok → determine if this is own memory or another's
+       │
+       ├─ Own memory → proceed (can_publish is sufficient)
+       │
+       └─ Another's memory → check can_revise flag
+            │
+            ├─ false → return "Permission denied"
+            └─ true → proceed with revision
+```
+
+For moderation actions:
+
+```
+User calls remember_moderate (e.g., delete a memory)
+  │
+  ▼
+AuthorizationService.checkPermission(jwt, groupId, 'can_moderate')
+  │
+  ├─ Err → return "Permission denied"
+  │
+  └─ Ok → check if reversing an existing moderation action?
+       │
+       ├─ No (new action) → execute, stamp with MemoryModerationAction
+       │
+       └─ Yes (reversing) → checkModerationPermission(jwt, groupId, existingAction)
+            │
+            ├─ user.auth_level > existingAction.acted_by_auth_level
+            │   → "Cannot reverse: action performed by higher authority"
+            │
+            └─ user.auth_level <= existingAction.acted_by_auth_level
+                → reverse action, stamp reversed_at + reversed_by_user_id
+```
+
+### 7. Space Configuration
+
+Group memory spaces need configuration that maps to permission enforcement. This is owned by remember-mcp.
+
+```typescript
+// src/types/space.types.ts (extension)
+
+export interface SpaceConfig {
+  space_id: string
+  group_id: string              // Links to agentbase.me group
+  write_mode: 'owner_only' | 'group_editors' | 'anyone'
+  created_at: string
+  updated_at: string
+}
+```
+
+`write_mode` determines how permissions are checked:
+- `owner_only` — only the memory author can modify (no credentials call needed)
+- `group_editors` — check `can_revise` / `can_overwrite` via credentials endpoint
+- `anyone` — no permission check (open space)
+
+---
+
+## Benefits
+
+- **No permission duplication**: remember-mcp reads ACL flags from agentbase.me, never stores or maps them
+- **Always fresh**: Fetched per-operation, no stale caches
+- **auth_level hierarchy**: Moderation actions respect authority levels, preventing lower-authority users from reversing higher-authority actions
+- **Extensible**: New permission flags can be added to agentbase.me without remember-mcp code changes (only flag consumption needs updating)
+- **Clean ownership**: agentbase.me owns permissions, remember-mcp owns enforcement
+
+---
+
+## Trade-offs
+
+- **Network overhead**: Every ACL-gated operation requires a credentials fetch (~50-100ms). Acceptable for current scale; can add short-TTL cache later if needed
+- **Credential endpoint dependency**: remember-mcp cannot function for group operations if agentbase.me is down (mitigate: graceful error handling, fall back to denying access)
+- **Moderation stamp storage**: `MemoryModerationAction` records accumulate over time (mitigate: only stored for active moderation actions, cleaned up when memories are permanently deleted)
+- **Unused flags**: remember-mcp receives flags it doesn't use (`can_kick`, `can_mute`, etc.) — small payload overhead, no functional impact
+
+---
+
+## Dependencies
+
+- **agentbase.me credentials endpoint** (`/api/credentials/agentbase`) — must return `MemberPermissions` per group
+- **agentbase.me group management tools** — defines the permission model and ACL flags
+- **remember-core BaseService** — authorization service extends existing pattern
+- **remember-core Result<T,E>** — permission checks return Result types
+- **remember-core ForbiddenError** — used for permission denied responses
+
+---
+
+## Testing Strategy
+
+**Unit Tests**:
+- AuthorizationService: each permission flag correctly gates its operation
+- AuthorizationService: `auth_level` comparison logic (lower = more authority)
+- MemoryModerationAction: stamps capture correct `acted_by_auth_level`
+- MemoryModerationAction: reversal blocked when user `auth_level > acted_by_auth_level`
+- MemoryModerationAction: reversal allowed when user `auth_level <= acted_by_auth_level`
+- CredentialsClient: parses `MemberPermissions` from endpoint response
+- CredentialsClient: returns null for non-member
+
+**Integration Tests**:
+- End-to-end: user with `can_publish` can publish to group space
+- End-to-end: user without `can_revise` cannot revise another's memory
+- End-to-end: moderation stamp prevents lower-authority reversal
+- End-to-end: credentials endpoint returns fresh data (no stale cache)
+
+---
+
+## Future Considerations
+
+- **Short-TTL cache**: If credentials fetch latency becomes a concern, add a 30-second in-memory cache with invalidation on membership changes
+- **Per-memory permission overrides**: Allow specific memories to have custom permission overrides beyond group-level flags
+- **Audit log**: Record all permission-gated operations for compliance and debugging
+- **Batch permission checks**: Optimize for operations touching multiple memories in one request
+- **REST API exposure**: When remember-core builds its REST adapter, the authorization service can be reused for HTTP endpoints
+
+---
+
+**Status**: Design Specification
+**Recommendation**: Implement after agentbase.me credentials endpoint returns `MemberPermissions` (agentbase task-188). The types and interfaces can be built now; the credentials client integration depends on the endpoint being ready.
+**Related Documents**:
+- [core-sdk.architecture.md](core-sdk.architecture.md) — remember-core architecture patterns
+- [agentbase group-management-tools.md](../../../agentbase.me-e1/agent/design/local.group-management-tools.md) — ACL flag definitions and presets
+- [agentbase credentials endpoint](../../../agentbase.me-e1/agent/design/local.group-acl-credentials-endpoint.md) — credentials endpoint design
+- [agentbase group-credentials-for-remember-mcp.md](../../../agentbase.me-e1/agent/design/local.group-credentials-for-remember-mcp.md) — credentials response extension