Table of Contents

Personalized Agent Memory Plan

Purpose

This document captures the current design for personalized memory in FoundationaLLM agents. It is intended to travel with the implementation work so future agents and engineers understand the research, decisions, scope boundaries, and verification expectations.

The design goal is to provide durable user memory as an agent tool. Agents can elect to retrieve, append, or clear memory. Memory is stored by FoundationaLLM, exposed through CoreAPI, and accessed by agents through an out-of-process Memory MCP server.

Summary of decisions

Decision Outcome Rationale
Memory is a tool Use MCP tools named get_memory, append_memory, and clear_memory. Keeps memory explicit, inspectable, and configurable per agent.
Memory storage is CoreAPI-owned MCP server calls CoreAPI; MCP server does not write Cosmos DB directly. Matches existing FoundationaLLM service boundaries and keeps policy/audit/storage in the platform.
Memory content is markdown Store one markdown document per memory scope. Keeps v1 simple and portable. No vectors or semantic search required.
Scope is an argument, not separate tools scope is user, agent, or combined depending on the operation. Avoids duplicated MCP tools and maps cleanly to the existing MCP client tool UI.
User identity target architecture Use user-delegated OBO tokens for interactive user calls; use a platform-issued identity context when OBO is impossible, such as agent access token calls. Provides the strongest posture for user portal traffic while still supporting non-interactive callers.
Ownership is UPN-based for v1 Store and enforce memory ownership by upn. Conversations already use UPN as the ownership check, and CoreService requires UPN.
Memory is a resource provider Implement FoundationaLLM.Memory from the start. Aligns memory with platform authorization, resource metadata, and the closest existing model: FoundationaLLM.Conversation.
Import/export is API-only in this repo Add CoreAPI markdown import/export endpoints. No portal UI in this repo for v1. Agent Portal lives in a different repo and will provide user-facing import/export.
Auto memory is included in v1 Agents can call append_memory when prompting tells them to persist durable facts. No backend extraction pipeline is needed; behavior is driven by tool availability and agent instructions.

Existing platform context

FoundationaLLM already has the core extension points needed for memory:

  • Agents have a tools collection and conversation history settings in the agent resource model.
  • LangChain tools are instantiated with tool_config, objects, user_identity, and config.
  • The Orchestration builder adds FoundationaLLM.InstanceId, Agent.AgentName, and Agent.AgentObjectId to request objects.
  • Completion requests carry session_id, operation_id, metadata, message_history, and file_history.
  • Conversation history is already a short-term, current-session memory layer.
  • CoreAPI already exposes conversation-like user-scoped operations and enforces ownership by UPN in the Conversation resource provider.
  • The Management Portal Tools Experience configures FoundationaLLMMCPClientTool (MCP headers, including system context tokens such as context://user_identity).

Memory taxonomy

Layer Scope Status
Conversation history Current conversation/session Already exists via conversation_history_settings and message_history.
Saved personalized memory Cross-conversation, user-scoped or user-agent-scoped New v1 capability.
Reference chat history Cross-conversation mining/retrieval from prior chats Not v1.

The new feature should not duplicate conversation history. append_memory should persist durable facts, preferences, repeated corrections, and user profile details that should survive beyond the current conversation.

Competitive research

OpenAI / ChatGPT

Observed capabilities:

  • Saved memories: explicit or automatically captured facts/preferences.
  • Reference chat history: personalization based on past conversations, not just saved memories.
  • Temporary Chat: avoids using/updating memory.
  • User controls: view, delete individual memories, clear all, turn memory off.
  • Enterprise/Edu controls: admins can disable memory.
  • Memory is separate from chat history; deleting a chat does not necessarily delete saved memories.
  • Sensitive information guidance: avoid proactive saving of sensitive information unless explicitly requested.
  • Memory can influence search/query rewriting.
  • Project-only memory exists for scoping in ChatGPT Projects.
  • Export is not a clean saved-memory API in public docs; users generally rely on copy/paste or prompt-generated summaries.

Sources reviewed:

  • OpenAI Memory FAQ: https://help.openai.com/en/articles/8590148-memory-faq
  • OpenAI reference saved memories: https://help.openai.com/en/articles/11146739-how-does-reference-saved-memories-work
  • OpenAI data export: https://help.openai.com/en/articles/7260999-how-do-i-export-my-chatgpt-history-and-data

Anthropic / Claude

Observed capabilities:

  • Profile preferences: account-wide response preferences.
  • Project instructions: project-scoped context.
  • Styles: response tone/format controls.
  • Claude Code memory: markdown/file-based memory via CLAUDE.md, rules, and auto memory files.
  • Claude API memory tool: client-owned storage with tool commands like view, create, str_replace, insert, delete, and rename.
  • Memory import/export: text-first. Claude recommends asking the current AI service to emit memories in a copyable block, optionally as Markdown.
  • Claude memory is transparent and tool-mediated in API/Claude Code contexts.

Sources reviewed:

  • Claude personalization: https://support.claude.com/en/articles/10185728-understanding-claude-s-personalization-features
  • Claude Code memory: https://code.claude.com/docs/en/memory
  • Claude API memory tool: https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool
  • Claude import/export: https://support.claude.com/en/articles/12123587-import-and-export-your-memory-from-claude

Google Gemini

Observed capabilities:

  • Saved info: explicit facts/preferences users can ask Gemini to remember.
  • Personalization profile: preferred name, role/job title, industry.
  • Conversation history learning.
  • Connected work data sources in Gemini Enterprise.
  • User controls: view, update, delete saved memories.
  • Admin controls for enterprise memory/personalization.
  • Memory import is text-first for preferences: copy a prompt into the old AI app, copy the resulting summary, paste it into Gemini.
  • Chat history import is ZIP-based, but that is distinct from saved memory/preferences import.

Sources reviewed:

  • Gemini Enterprise personalization: https://docs.cloud.google.com/gemini/enterprise/docs/configure-personalization
  • Gemini import memory: https://gemini.google/import-memory/

Competitive capability matrix

Capability OpenAI Claude Gemini FoundationaLLM v1
Explicit saved memory Yes Yes Yes Yes: append_memory.
Retrieve memory into context Yes Yes Yes Yes: get_memory.
Delete memory Yes Yes Yes Yes: clear_memory.
View/export memory Yes Yes Yes Yes at CoreAPI level via markdown export. Agent Portal UI later.
Import memory Text/prompt-based in practice Text/prompt-based Text/prompt-based for preferences Yes: import markdown at selected scope.
Ask "what do you remember?" Yes Yes Yes Yes via get_memory.
User-wide memory Yes Yes Yes Yes: scope=user.
Agent/project-scoped memory Project-only memory Project instructions / files Gems/work context Yes: scope=agent.
Combined scoped memory Limited/implicit Depends on project/files Enterprise profile + sources Yes: scope=combined.
Auto memory from conversation Yes Yes in Claude Code/API patterns Yes Yes via prompting and tool use.
Reference chat history Yes Chat search/project-dependent Yes Not v1.
Temporary/no-memory mode Yes Can disable or choose session behavior Yes-ish Future setting; can be prompt/policy controlled initially.
Profile fields Account name/custom prefs Profile preferences Preferred name, role, industry Partial: store name and user_name; dedicated profile UI later.
Connected data-source memory Search/apps Project/files/tools Gmail/Drive/etc. Out of scope for memory v1; platform tools/connectors remain separate.
Admin controls Enterprise workspace controls Org/project controls Enterprise admin controls Not full v1; plan for later.
Sensitive-info policy Yes Guidance/refusal Controls Prompt/tool guidance in v1; stricter enforcement later.
Size/retention controls Memory management File-size guidance Admin/settings Max markdown size in v1; retention later.
Audit/provenance User transparency Tool-call visibility Settings/enterprise controls Store source agent/session/operation/timestamps.
Version/history/restore Yes for saved memory history Possible through files Not core in reviewed docs Not v1.

What is unique about FoundationaLLM

FoundationaLLM's differentiator is explicit scope control across an enterprise agent fleet:

  • agent scope: memory available only to a specific configured agent for a user.
  • user scope: memory available across agents for a user.
  • combined retrieval: returns both user-wide and current-agent memory.

This is a better fit for FoundationaLLM than a single monolithic assistant memory because platform administrators and agent builders can decide which agents use memory and what scope they write to.

Memory storage design

Storage model

Store one markdown profile document per user/scope.

For user-wide memory:

  • Partition: upn
  • Document id: deterministic, for example memory:user:{normalizedUpn}
  • Scope: user
  • Agent fields: null

For agent-scoped memory:

  • Partition: upn
  • Document id: deterministic, for example memory:agent:{normalizedUpn}:{agentObjectIdHash}
  • Scope: agent
  • Agent fields: set

combined memory is never stored. It is assembled at read time from the user memory document and the agent memory document.

Proposed model

MemoryProfile
├── id
├── upn
├── user_name
├── name
├── scope                 # "user" or "agent"
├── agent_object_id        # required when scope == "agent"
├── agent_name
├── content_markdown
├── metadata
├── created_on
├── updated_on
└── deleted

Markdown shape

User memory example:

# User memory

- User prefers concise answers.
- User name is alex@contoso.com.
- User prefers Markdown tables for comparisons.

Agent memory example:

# Agent memory

- For Benefits Assistant, user cares about HSA details.
- For Benefits Assistant, user prefers annual enrollment examples.

Combined read response:

# User memory

- User prefers concise answers.
- User name is alex@contoso.com.

# Agent memory

- For Benefits Assistant, user cares about HSA details.

Storage rules

  • Use UPN as the owner and partition key in v1.
  • Store user_name and name for personalization and addressing.
  • No default memory document size limit in v1.
  • append adds markdown under an automatic timestamp/provenance heading.
  • replace overwrites the selected document.
  • clear replaces content_markdown with an empty document while retaining the memory profile and metadata.
  • get_memory returns 200 OK with empty markdown when no memory exists.
  • No vector embeddings in v1.
  • No semantic deduplication in v1.
  • Optional simple duplicate-line suppression may be added later.

CoreAPI implementation plan

Hand-off for Memory MCP developers: the published API contract is
docs/docs/reference/personalized-memory.md
(endpoints, request/response models, auth/identity, and MCP tool → CoreAPI mapping).

New CoreAPI endpoints

API-only support in this repository:

GET  /instances/{instanceId}/memory?scope=user
GET  /instances/{instanceId}/memory?scope=agent&agentObjectId={agentObjectId}
GET  /instances/{instanceId}/memory?scope=combined&agentObjectId={agentObjectId}
POST /instances/{instanceId}/memory/append
POST /instances/{instanceId}/memory/clear
GET  /instances/{instanceId}/memory/export?scope=user
GET  /instances/{instanceId}/memory/export?scope=agent&agentObjectId={agentObjectId}
POST /instances/{instanceId}/memory/import

Request and response models

MemoryScope
├── user
├── agent
└── combined

AppendMemoryRequest
├── scope                 # user or agent
├── agent_object_id        # required for agent scope
├── agent_name             # optional; CoreAPI can resolve when omitted
├── content_markdown
├── reason
├── operation_id
└── session_id

ClearMemoryRequest
├── scope                 # user or agent
├── agent_object_id        # required for agent scope
└── confirm               # must be true

ImportMemoryRequest
├── scope                 # user or agent
├── agent_object_id        # required for agent scope
├── content_markdown
└── mode                  # append or replace

MemoryResponse
├── scope                 # user, agent, or combined
├── upn
├── user_name
├── name
├── agent_object_id
├── agent_name
├── content_markdown
├── created_on
└── updated_on

CoreAPI behavior

  • Add a MemoryController under instances/{instanceId}/memory.
  • Add ICoreService memory methods and implement them in CoreService.
  • Use IOrchestrationContext.CurrentUserIdentity.
  • Require valid UPN, matching existing CoreService behavior.
  • Validate agent access for agent-scoped operations.
  • Enforce ownership in the memory service/repository by UPN.
  • Return text/markdown for export endpoints.
  • Import only markdown. No provider-specific ChatGPT, Claude, or Gemini importers.

Authorization and identity

The preferred production security model is hybrid:

  • Interactive user requests should use an on-behalf-of (OBO) flow where the User Portal's CoreAPI bearer token is exchanged for a delegated token usable by the Memory MCP server and then CoreAPI Memory API.
  • Agent access token and other non-interactive requests cannot use a true OBO flow because there may be no user-delegated Entra token to exchange. These requests should use a FoundationaLLM-issued identity context that represents the already-resolved UnifiedUserIdentity.
  • Raw X-USER-IDENTITY forwarding is acceptable as an existing platform compatibility mechanism, but should not be treated as the long-term strongest production posture for memory.

The current User Portal source confirms completion requests are sent to CoreAPI with Authorization: Bearer <token> and that the token is acquired with configured User Portal Entra scopes. The actual audience/scope values live in App Configuration and must be verified per deployment.

Implementation impact:

  • Phase 1 and 2 can implement FoundationaLLM.Memory and CoreAPI memory endpoints using the existing CurrentUserIdentity once requests reach CoreAPI.
  • Full OBO propagation through CoreAPI, Orchestration, LangChainAPI, the MCP client tool, and the Memory MCP server should be implemented with the Memory MCP server workstream, because it crosses repository boundaries.
  • Until that end-to-end OBO path exists, Memory MCP integrations must use the platform's trusted service-to-service identity propagation pattern in controlled deployments.

Cosmos/resource provider implementation

Implement memory as a new FoundationaLLM.Memory resource provider from the start.

  • Add a new Cosmos container for memory profiles.
  • Add MemoryResourceProviderMetadata and memory resource type constants.
  • Register the provider in CoreAPI beside FoundationaLLM.Conversation.
  • Use ConversationResourceProviderService as the closest implementation model.
  • Implement policy enforcement in the resource provider by validating the persisted upn against UnifiedUserIdentity.UPN.
  • Route CoreAPI convenience endpoints through CoreService, then through MemoryResourceProviderService.

MCP server plan

The Memory MCP server lives in a different repository. This section is an implementation brief for that future work.

Authoritative API + tool mapping for that repo: docs/docs/reference/personalized-memory.md.

MCP tools

Use three action-based tools:

get_memory
append_memory
clear_memory

Do not create separate tools for user memory versus agent memory. Use scope as an argument.

Tool schemas

get_memory

scope: "user" | "agent" | "combined"

Behavior:

  • Calls CoreAPI GET /memory.
  • Defaults to combined when configured that way in the FoundationaLLM MCP client wrapper.
  • Returns markdown to the agent.

append_memory

scope: "user" | "agent"
memory: markdown string
reason: optional string

Behavior:

  • Calls CoreAPI POST /memory/append.
  • Appends durable user memory to the selected markdown document.

clear_memory

scope: "user" | "agent"
confirm: boolean

Behavior:

  • Calls CoreAPI POST /memory/clear.
  • Requires confirm=true.

MCP server responsibilities

  • Expose MCP protocol endpoints.
  • Validate MCP request shape.
  • Forward calls to CoreAPI.
  • Forward X-USER-IDENTITY.
  • Authenticate to CoreAPI with the configured service credential.
  • Do not store memory.
  • Do not enforce ownership or policy beyond basic request validation.

MCP server non-goals

  • No direct Cosmos DB access.
  • No vector search.
  • No provider-specific memory import/export.
  • No user interface.

Management Portal and MCP client configuration

The existing Management Portal already has an MCP client tool configuration dialog. The plan should use that UI, not invent a separate MCP-memory-specific experience.

Existing UI shape

The agent Tools section has an MCP button that creates a FoundationaLLMMCPClientTool. Existing rows show the tool name and class name.

Agent: Benefits Assistant
Tools
┌────────────────────┬───────────────────────────────┬────────┬────────┐
│ Name               │ Class Name                    │ Edit   │ Delete │
├────────────────────┼───────────────────────────────┼────────┼────────┤
│ get_memory         │ FoundationaLLMMCPClientTool    │  edit  │ delete │
│ append_memory      │ FoundationaLLMMCPClientTool    │  edit  │ delete │
│ clear_memory       │ FoundationaLLMMCPClientTool    │  edit  │ delete │
└────────────────────┴───────────────────────────────┴────────┴────────┘
[ + MCP ]  [ + Claude Agent ]  [ + Custom ]

Configure append_memory

Configure MCP Tool
┌──────────────────────────────────────────────────────────────────────┐
│ Basic Info                                                           │
├───────────────────────────────────┬──────────────────────────────────┤
│ Tool Name                         │ Description                      │
│ append_memory                     │ Append durable user memory.       │
│                                   │ Use scope=user for all agents or  │
│                                   │ scope=agent for this agent only.  │
└───────────────────────────────────┴──────────────────────────────────┘

MCP Server Configuration
┌──────────────────────┬───────────────────────────────────────────────┐
│ Transport Type       │ Streamable HTTP                               │
│ URL                  │ https://memory-mcp.contoso.com/mcp            │
└──────────────────────┴───────────────────────────────────────────────┘

Headers
┌──────────────────────┬───────────────┬───────────────────────────────┐
│ Key                  │ Source        │ Configuration Key / Value      │
├──────────────────────┼───────────────┼───────────────────────────────┤
│ X-API-KEY            │ Existing Config│ FoundationaLLM:APIEndpoints... │
│ X-USER-IDENTITY (*)  │ Platform-added │ forwarded by MCP client work   │
└──────────────────────┴───────────────┴───────────────────────────────┘

Connection Timeout (sec): 30
Default Operation Timeout (sec, optional): 30
[x] Terminate on Close

Tool Selection and Configuration
┌──────────────────────────────────────────────────────────────────────┐
│ [ ] Enable Intelligent Execute                                       │
│                                                                      │
│ Direct mode:                                                         │
│   List Tools  [discovered: get_memory, append_memory, clear_memory]  │
│                                                                      │
│ MCP Tool Name:        append_memory                                  │
│ Response Format:      JSON                                           │
└──────────────────────────────────────────────────────────────────────┘

Tool Arguments
┌────────┬──────────────────────────────────────────────┬─────────┬──────┬─────────┐
│ Name   │ Description                                  │ Type    │ Req  │ Default │
├────────┼──────────────────────────────────────────────┼─────────┼──────┼─────────┤
│ scope  │ "user" = across all agents; "agent" = this   │ string  │  x   │         │
│        │ agent only                                   │         │      │         │
│ memory │ Markdown text to append                      │ string  │  x   │         │
│ reason │ Optional provenance note                     │ string  │      │         │
└────────┴──────────────────────────────────────────────┴─────────┴──────┴─────────┘

Configure get_memory

MCP Tool Name: get_memory
Response Format: Text

Tool Arguments
┌────────┬──────────────────────────────────────────────┬─────────┬──────┬──────────┐
│ Name   │ Description                                  │ Type    │ Req  │ Default  │
├────────┼──────────────────────────────────────────────┼─────────┼──────┼──────────┤
│ scope  │ "combined" returns user + agent memory;      │ string  │  x   │ combined │
│        │ "user" returns cross-agent memory; "agent"   │         │      │          │
│        │ returns this agent only.                     │         │      │          │
└────────┴──────────────────────────────────────────────┴─────────┴──────┴──────────┘

Configure clear_memory

MCP Tool Name: clear_memory
Response Format: JSON

Tool Arguments
┌─────────┬─────────────────────────────────────────────┬─────────┬──────┬─────────┐
│ Name    │ Description                                 │ Type    │ Req  │ Default │
├─────────┼─────────────────────────────────────────────┼─────────┼──────┼─────────┤
│ scope   │ "user" clears cross-agent memory; "agent"   │ string  │  x   │         │
│         │ clears this agent's memory only.            │         │      │         │
│ confirm │ Must be true. Use only when the user         │ boolean │  x   │ false   │
│         │ explicitly asks to forget/reset memory.     │         │      │         │
└─────────┴─────────────────────────────────────────────┴─────────┴──────┴─────────┘

Needed MCP client enhancement

Identity forwarding for trusted HTTP MCP servers uses the platform system context header model:

  • Configure header X-USER-IDENTITY with value context://user_identity in the Tools Experience MCP headers editor.
  • The MCP client resolves context://user_identity to serialized self.user_identity at runtime.
  • Do not reintroduce a legacy forward_user_identity boolean property; main already migrates that shape to the header token.

Agent Portal requirements

The Agent Portal lives in a different repository. This section is a requirement brief for that future work.

End-user memory management

Provide user-facing controls for:

  • View user-level memory.
  • View agent-level memory.
  • Import markdown into selected scope.
  • Export markdown from selected scope.
  • Clear selected scope.

Import/export requirements

API-only support will exist in CoreAPI. The Agent Portal should provide the UX later.

User flows:

  • Import markdown into user memory.
  • Import markdown into a selected agent memory.
  • Export user memory as .md.
  • Export selected agent memory as .md.

Do not build ChatGPT/Claude/Gemini-specific importers. Competitive research supports markdown/text import as the smallest useful abstraction.

Agent configuration requirements

Provide controls or templates to help configure:

  • Whether an agent has memory enabled.
  • Whether the agent should auto-append durable facts.
  • Default write scope: agent or user.
  • Recommended memory policy instructions.
  • MCP wrapper tools for get_memory, append_memory, and clear_memory.

Example agent memory policy

Use memory to personalize future conversations. Retrieve combined memory at the start of a conversation when relevant. Append only durable preferences, user profile details, repeated corrections, and long-lived facts. Do not store secrets, credentials, transient requests, or sensitive personal details unless the user explicitly asks. Use scope=agent for Benefits Assistant-specific preferences and scope=user for general preferences useful across agents.

API-only import/export specification

Export

GET /instances/{instanceId}/memory/export?scope=user
GET /instances/{instanceId}/memory/export?scope=agent&agentObjectId={agentObjectId}

Response:

Content-Type: text/markdown
Content-Disposition: attachment; filename="foundationallm-user-memory.md"

Agent export filename suggestion:

foundationallm-agent-memory-{agentName}.md

Import

POST /instances/{instanceId}/memory/import

Request:

{
  "scope": "agent",
  "agent_object_id": "/instances/.../providers/FoundationaLLM.Agent/agents/benefits-assistant",
  "content_markdown": "# Imported memory\n\n- User prefers concise responses.",
  "mode": "append"
}

Rules:

  • scope=user imports to cross-agent memory.
  • scope=agent imports to one specific agent memory.
  • mode=append appends imported markdown under an import heading.
  • mode=replace replaces the selected memory document.
  • No provider-specific format handling.
  • No bulk all-users export in v1.

Verification plan

Verifications in this repo are structured Markdown test plans under verifications/ with matching results templates. The portal-verification skill requires each verification to include prerequisites, test data safety, recording instructions, step-by-step test cases, and a results template.

Verification files to create with implementation

When the CoreAPI and MCP-client pieces are implemented, create new verification files using the next available IDs (current IDs after merge with main):

verifications/V017-coreapi-personalized-memory.md
verifications/V017-coreapi-personalized-memory-results-template.md
verifications/V018-management-portal-memory-mcp-config.md
verifications/V018-management-portal-memory-mcp-config-results-template.md

Also augment existing main hotspot verifications (V001, V005, V009 realtime, V010, V011, V015) so merge touchpoints continue to pass.

If Agent Portal and Memory MCP server work are in separate repos, create equivalent verification documents in those repos using their local conventions. This plan should be copied or referenced there.

V008 CoreAPI personalized memory verification outline

Feature: CoreAPI personalized memory endpoints.

Application/API URL:

CoreAPI local/deployed base URL for the target environment

Prerequisites:

  • CoreAPI running.
  • Auth configured.
  • A test user identity available.
  • At least two accessible test agents available.

Test data safety:

  • Create only test memory documents for the authenticated user.
  • Do not modify pre-existing user memory unless the test created it.
  • Clear only test-created memory at cleanup.

Test cases:

  1. User memory starts empty.
    • Call GET /memory?scope=user.
    • Expect empty markdown or not-found-normalized response.
  2. Append user memory.
    • Call POST /memory/append with scope=user.
    • Call GET /memory?scope=user.
    • Expect appended markdown.
  3. Append agent memory for Agent A.
    • Call POST /memory/append with scope=agent and Agent A object id.
    • Call GET /memory?scope=agent&agentObjectId=AgentA.
    • Expect Agent A markdown.
  4. Agent isolation.
    • Call GET /memory?scope=agent&agentObjectId=AgentB.
    • Expect Agent A markdown is absent.
  5. Combined memory.
    • Call GET /memory?scope=combined&agentObjectId=AgentA.
    • Expect user memory and Agent A memory.
  6. Export user memory.
    • Call user export endpoint.
    • Expect text/markdown and user memory content.
  7. Import append.
    • Import markdown to Agent B with mode=append.
    • Read Agent B memory.
    • Expect imported markdown present.
  8. Import replace.
    • Import markdown to Agent B with mode=replace.
    • Read Agent B memory.
    • Expect old Agent B content absent and replacement present.
  9. Clear agent memory.
    • Call clear with scope=agent, confirm=true.
    • Read Agent B memory.
    • Expect empty/cleared response.
  10. Authorization boundary.
  • Attempt access using another user's identity if feasible.
  • Expect 403 or no access to original user's memory.
  1. Validation failures.
  • Missing agent_object_id for scope=agent.
  • clear_memory without confirm=true.
  • Oversized markdown.
  • Expect appropriate 400 responses.

Evidence:

  • Save request/response logs with redacted auth headers.
  • Save response bodies for get/export/import/clear flows.
  • Record pass/fail in the results template.

V018 Management Portal MCP configuration verification outline

Feature: configuring the existing MCP client tool for memory via Tools Experience List Tools → Configure.

Canonical steps live in verifications/V018-management-portal-memory-mcp-config.md.

Application URL:

http://localhost:3001

Prerequisites:

  • ManagementPortal, ManagementAPI, and ContextAPI running.
  • A reachable Memory MCP server that exposes get_memory, append_memory, and clear_memory (do not run V018 with a placeholder URL).
  • Test agent created for configuration.

Test data safety:

  • Create a dedicated test agent.
  • Add/delete only memory MCP tools on that test agent.
  • Do not modify existing agents.

Test cases:

  1. MCP Client tool editor opens from Tools Experience Add Tool.
  2. Configure get_memory:
    • Set transport URL to the Memory MCP server.
    • Add header Key X-USER-IDENTITY, Source New Value, Value context://user_identity.
    • Leave Intelligent Execute unchecked; click List Tools; select get_memory → Configure.
    • Save tool, then save agent; reopen and verify MCP server/settings persistence.
  3. Configure append_memory with the same header + List Tools → Configure flow; save tool and agent; reopen and verify.
  4. Configure clear_memory with the same header + List Tools → Configure flow; save tool and agent; reopen and verify.
  5. Validation:
    • Attempt save without URL.
    • List Tools against an unreachable server fails.

Evidence:

  • Browser screenshots of configured dialogs.
  • Saved agent JSON if available from network/API inspection.
  • Results file using verifications/V018-management-portal-memory-mcp-config-results-template.md.

Future cross-repo verifications

Memory MCP server repo:

  • Verify get_memory, append_memory, clear_memory over MCP.
  • Verify MCP server forwards X-USER-IDENTITY to CoreAPI.
  • Verify no direct Cosmos access.
  • Verify CoreAPI errors are returned clearly through MCP tool results.

Agent Portal repo:

  • Verify user can view user and agent memory.
  • Verify markdown import to user scope.
  • Verify markdown import to agent scope.
  • Verify export returns correct markdown.
  • Verify clear only affects selected scope.
  • Verify scope explanations are clear.

Phased implementation checklist

Phase 1: Storage design in FoundationaLLM

  • Added memory model(s).
  • Implemented FoundationaLLM.Memory resource provider.
  • Added Memories Cosmos container support using hierarchical /instance_id, /upn partitioning.
  • Runtime verification showed the service identity cannot create Cosmos containers through AAD data-plane auth, so Memories must be provisioned by infrastructure/configuration before CoreAPI handles memory traffic.
  • Implemented deterministic document ids.
  • Implemented UPN ownership and partitioning.
  • Confirmed no default memory document size limit in v1.

Phase 2: CoreAPI enhancements

  • Added request/response models.
  • Added MemoryController.
  • Added ICoreService methods.
  • Implemented get/append/clear/import/export.
  • Validated identity and target agent access through the Memory resource provider and Agent resource provider.
  • Added V017 verification and results template (CoreAPI personalized memory).

Phase 3: Management Portal / Management memory

  • Avoid new memory-specific UI in v1.
  • Identity forwarding uses Tools Experience headers: Key X-USER-IDENTITY, Source New Value, Value context://user_identity (then List Tools → Configure).
  • Added V018 verification and results template (Management Portal memory MCP config). Do not run V018 until a Memory MCP server is available.

Phase 4: Memory MCP server in separate repo

  • Implement MCP server with get_memory, append_memory, clear_memory.
  • Configure CoreAPI endpoint/auth.
  • Forward user identity.
  • Map MCP arguments to CoreAPI calls.
  • Add cross-repo verification.

Phase 5: Agent Portal in separate repo

  • Build end-user view/import/export/clear flows.
  • Use CoreAPI memory endpoints.
  • Provide agent memory configuration affordances.
  • Add cross-repo verification.

Resolved design questions

  • Memory will be implemented as a new FoundationaLLM.Memory resource provider from the start.
  • V1 will have no default memory document size limit.
  • clear_memory replaces content with an empty document while retaining the memory profile and metadata.
  • append_memory adds an automatic timestamp/provenance heading.
  • get_memory returns 200 OK with empty markdown when no memory exists.

Open questions

  • The Memory MCP server workstream must finalize the production auth path for MCP-to-CoreAPI calls: OBO for interactive delegated users, and a FoundationaLLM-issued identity context for agent access token/non-interactive flows.
  • The in-repo MCP client enhancement is resolved via system context headers (X-USER-IDENTITY / context://user_identity) for trusted internal HTTP MCP servers.